Translate Like a Pro | Localize IIIF Content State API 1.0 Bookmarks, Canvas Regions, Deep Links and Multilingual Viewer Handoffs Without Losing the Target

How do you translate or localize an IIIF Content State API 1.0 bookmark without breaking the exact manuscript page, image region or audiovisual moment it is meant to open? Libraries, museums and digital-humanities teams increasingly need multilingual IIIF deep links that travel between search results, exhibition pages, annotation tools and independent viewers. The essential skill is separating human-readable descriptions from the machine-readable target that makes a shared content state work.

Imagine a researcher reading a catalogue in Spanish and selecting a phrase on a French manuscript. The researcher wants to send a colleague a link that opens precisely the same Canvas and highlighted region, even when the colleague uses an English interface. A translated button label is straightforward. Preserving the target, its Manifest relationship, the region selector, any temporal offset and the viewer’s handling of encoded state is a different responsibility. Confusing the two can turn a useful citation into a link to the wrong page.

This guide explains IIIF Content State API 1.0 in conversational terms, using practical examples, editorial decisions, validation exercises and controlled multilingual handoffs. Its narrow focus is portable view state: which digital object a viewer must load, which part should be displayed, and how another application receives the instruction. It complements, rather than replaces, IIIF Presentation manifests, Image API delivery, Content Search results, Authorization Flow and Change Discovery synchronization. It also distinguishes the stable specification from individual viewer interface choices.

Why a shared view needs more than a translated label

A reliable workflow begins by writing down a reader’s intended destination, representing it with the appropriate IIIF Content State form, delivering that representation through a supported mechanism, and confirming that the receiving viewer reaches the same evidence. This article gives each decision a concrete test. It is not an argument that every collection needs a custom viewer; it is a method for making links robust across ordinary variations in language, software and audience.

A portable view is not a translated page

A catalogue search result promises to open page seven of a digitized notebook, not merely the notebook landing page. Start with what the receiving application is supposed to do, not with a phrase that happens to appear on a screen. A precise description of that expected action is what makes multilingual review meaningful. The content state represents the requested resource or focus, while the website around it may speak any language. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Translate the search-result caption and action label; retain the resource URI and precise selection as data. In a review session, identify the publisher-controlled URI, then mark which adjacent fields are display language. Ask the translator to explain every altered value in terms of visitor meaning, not convenience. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A team replaces a Canvas identifier with an English page name that no repository actually serves. Open the link in two unrelated compatible viewers and compare the selected Canvas and region. A screen capture is not enough as a technical test; compare the resolved resource identifier and any selection parameters against the known source. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

The meaning of content state

A museum’s interface remembers a zoomed corner of an image, but another viewer has a completely different toolbar. The same object can be described differently for students, curators and researchers. Those audiences need helpful wording, but they should not silently inherit different claims about the underlying evidence. Content state identifies shareable IIIF content, not private details such as which sidebar is open. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Document what must survive handoff: Manifest, Canvas, region, Range or time; leave layout preferences client-specific. This distinction is especially valuable for digital objects reused by universities and cultural organizations in different countries. No single institution can assume every viewer uses its interface conventions. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

An export attempts to carry CSS classes, pane widths and local session identifiers as if they were interoperable semantics. The receiving viewer must arrive at the intended object even if its controls look different. Keep the original state available while investigating discrepancies. Without it, a reviewer may mistake a newly generated link for the evidence first cited. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Manifest identity must remain stable

Two translations of an exhibition show different public titles for the same digital manuscript. Reading the structure first avoids a surprisingly common confusion: a visible string may be a translation candidate, an immutable identifier, or a statement about source evidence. Each has a different owner. The Manifest URI is the identity used to retrieve the resource, not a string that should be translated. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Store localized titles separately and pass the canonical Manifest identifier when launching a viewer. Use plain language in the interface to set expectations. A translated label should say what the user will open, rather than promising search, playback or access behavior the receiving application cannot provide. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Replacing the URI with a language-specific title accidentally creates a non-resolvable target. Fetch the transmitted identifier and compare it byte-for-byte with the repository’s published resource. A localization pass is complete only when both ordinary readers and interoperability checks agree on what was requested and what was delivered. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Canvas identity and page selection

A historical newspaper has hundreds of Canvases, and a German search hit belongs on one small clipping. One useful mental test is to imagine the visitor changing languages halfway through the journey. The selected resource must remain the same even if navigation labels and explanatory prose change. The selected Canvas identifies the page-like surface; its position in a translated table of contents is not sufficient. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Carry its identifier and, when needed, its relationship to the containing Manifest. A strong implementation makes this separation explicit in the data model. It stores translated wording as wording, and it retains the external reference as a reference rather than regenerating it. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A catalogue passes only an array index, which changes after pages are inserted or reorganized. Reorder the display labels and confirm the bookmark still opens the originally cited Canvas. Do not treat visual similarity as proof of equivalence. Two pages can look alike while pointing to different assets, versions or regions. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

The partOf relationship

A recipient receives a Canvas target but cannot discover which of several published Manifests contains it. A complete handoff should be explainable without relying on the exporting software. If another institution cannot tell what was selected, the description is not genuinely portable. The partOf reference tells the viewer where to find a Canvas or Range within a Manifest. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Keep the relationship as a structured reference, not a translated explanatory footnote. Before applying a bulk operation, test a representative record with several languages, unusual characters and more than one selection type. A failure at that scale is easier to diagnose than one found after publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Removing partOf from a non-dereferenceable Canvas leaves an otherwise correct link without enough navigation context. Test the link from a fresh browser session without cached Manifest knowledge. Prefer a test that would fail on the common mistake described above. This makes review diagnostic rather than a ceremonial approval step. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Image region selectors

A teacher highlights a narrow marginal note rather than the complete scanned page. Design the handoff around the reader’s intended question. The content reference answers where to look; translated prose explains why that location deserves attention. A Canvas fragment such as xywh expresses coordinates, not a phrase to be localized or rounded. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Translate the explanation of the selected area while preserving the numeric region and its coordinate basis. Reviewers should be able to repeat the exact journey independently. Record the target identifier and intended focus in a compact acceptance note before publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Changing commas to locale-specific separators or guessing the crop produces an image of unrelated text. Measure the intended crop against the source Canvas and confirm focus under multiple display sizes. Where the source is protected or unavailable, record that limitation rather than quietly replacing the target with an accessible but different object. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Temporal selections in audiovisual resources

An oral-history portal wants a deep link to a thirty-second passage within a longer recording. Technical fidelity and good writing serve different purposes. A readable translation helps a person, while a stable target lets software take that person to the actual evidence. Temporal offsets identify a portion of time-based content and must retain the correct unit and ordering. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Localize the surrounding transcript or caption without editing the temporal target itself. Compare the sender’s intent with the receiver’s result. Seeing a page open is only the beginning; it may still be the wrong page, the wrong region or an unintended playback moment. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A localized page converts seconds to minutes but updates only the label, leaving the actual playback point inconsistent. Start playback from the shared state and compare the audible passage with the original citation. Log the exact language and client environment used in the test. That information helps separate text-direction problems from missing target references. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Ranges and navigational structure

A multilingual exhibition offers an index of chapters that visitors can select in different languages. Treat the shared target as a citation-like commitment. When a label changes, the commitment to the original resource and selected part should not change by accident. A Range represents an ordered structural selection and is not merely a display heading. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Carry the Range reference while translating the navigation text where the presentation model permits. Create two outputs from the same source: a reader-friendly explanation in the target language and a stable content-state payload. Then test the reader journey from the actual published link. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A translated chapter name is substituted for a Range URI, causing a viewer to lose the structural destination. Open the same named chapter through both language interfaces and compare the resource reference. When repairing failures, change the smallest layer responsible: a display label, a serialization step, a target relationship or the receiver’s parser. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

The contentState motivation

A saved annotation is sent to a viewer and intended to initialize a view, not to add commentary to the manuscript. Start with what the receiving application is supposed to do, not with a phrase that happens to appear on a screen. A precise description of that expected action is what makes multilingual review meaningful. The specification uses a motivation value of contentState for the portable initialization intent. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Preserve this protocol value and translate only the visible wording such as Open saved view. In a review session, identify the publisher-controlled URI, then mark which adjacent fields are display language. Ask the translator to explain every altered value in terms of visitor meaning, not convenience. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A translator renders the motivation value as a local-language verb, so software no longer recognizes the instruction. Inspect the decoded annotation and ensure its motivation retains the exact interoperable value. A screen capture is not enough as a technical test; compare the resolved resource identifier and any selection parameters against the known source. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Full Annotation form

A research database stores a durable bookmark as a complete Web Annotation object with an id and target. The same object can be described differently for students, curators and researchers. Those audiences need helpful wording, but they should not silently inherit different claims about the underlying evidence. The full form explicitly states type Annotation, motivation contentState and the targeted IIIF resource. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Retain structural property names while making accompanying editorial notes available in selected languages. This distinction is especially valuable for digital objects reused by universities and cultural organizations in different countries. No single institution can assume every viewer uses its interface conventions. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Translating JSON-LD keys makes the object pleasant to read in a document but invalid for the intended consumer. Parse the JSON-LD and check that its identity, motivation, target and required context survive round-trip export. Keep the original state available while investigating discrepancies. Without it, a reviewer may mistake a newly generated link for the evidence first cited. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Annotation URI form

An institution wants a short URL for a bookmark held by its annotation server. Reading the structure first avoids a surprisingly common confusion: a visible string may be a translation candidate, an immutable identifier, or a statement about source evidence. Each has a different owner. The URI points to a retrievable content state Annotation rather than directly to a Manifest. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Keep the link stable and make the dereferenced JSON-LD available under appropriate access conditions. Use plain language in the interface to set expectations. A translated label should say what the user will open, rather than promising search, playback or access behavior the receiving application cannot provide. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A recipient assumes every URL points directly to a Manifest and ignores the annotation motivation. Dereference the URI and inspect the returned type before deciding how the application should process it. A localization pass is complete only when both ordinary readers and interoperability checks agree on what was requested and what was delivered. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Target body form

A link needs to select one Canvas and its Manifest parent without the overhead of a full saved annotation. One useful mental test is to imagine the visitor changing languages halfway through the journey. The selected resource must remain the same even if navigation labels and explanatory prose change. The compact target object can express the selection without an explicit surrounding Annotation wrapper. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Construct the target as a structured object and pass it using the specification’s expected transfer procedure. A strong implementation makes this separation explicit in the data model. It stores translated wording as wording, and it retains the external reference as a reference rather than regenerating it. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Compressing the target further into a plain Canvas string discards a necessary partOf relationship. Reconstruct the implied annotation and confirm it describes precisely the expected view. Do not treat visual similarity as proof of equivalence. Two pages can look alike while pointing to different assets, versions or regions. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Target URI form

A visitor chooses to open an entire collection or Manifest without selecting a particular detail. A complete handoff should be explainable without relying on the exporting software. If another institution cannot tell what was selected, the description is not genuinely portable. A simple URI is appropriate only when a resource identifier is sufficient to express the intended view. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Prefer the uncomplicated link for whole resources; use richer target forms when precision requires them. Before applying a bulk operation, test a representative record with several languages, unusual characters and more than one selection type. A failure at that scale is easier to diagnose than one found after publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A developer assumes the URI-only form can store an xywh crop or time-based selection by itself. Compare the requested behavior with what the link actually encodes, rather than what a local viewer happens to remember. Prefer a test that would fail on the common mistake described above. This makes review diagnostic rather than a ceremonial approval step. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Query parameter iiif-content

A multilingual discovery portal links to an independent viewer through an HTTP GET URL. Design the handoff around the reader’s intended question. The content reference answers where to look; translated prose explains why that location deserves attention. The Content State specification names the request parameter iiif-content for this handoff. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Keep that parameter name fixed and localize nearby call-to-action text without renaming protocol fields. Reviewers should be able to repeat the exact journey independently. Record the target identifier and intended focus in a compact acceptance note before publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A website translator converts the parameter key into a translated phrase, breaking receiving applications. Click the link from a second domain and inspect the received parameter for exact preservation. Where the source is protected or unavailable, record that limitation rather than quietly replacing the target with an accessible but different object. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Content state encoding

A complex bookmark contains JSON-LD with punctuation and multilingual text that might be double-encoded during sharing. Technical fidelity and good writing serve different purposes. A readable translation helps a person, while a stable target lets software take that person to the actual evidence. For JSON-LD in GET parameters, the specified content-state encoding uses encodeURIComponent followed by base64url without padding. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Apply the prescribed encoding to the structured state, and use ordinary URI handling for plain URI forms. Compare the sender’s intent with the receiver’s result. Seeing a page open is only the beginning; it may still be the wrong page, the wrong region or an unintended playback moment. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Using ordinary base64, leaving padding or double-encoding only one step yields an unreliable link. Decode the shipped state and compare the parsed object with the original before trusting the destination. Log the exact language and client environment used in the test. That information helps separate text-direction problems from missing target references. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Plain URIs are a special case

A curator passes a single Manifest URL into the iiif-content parameter. Treat the shared target as a citation-like commitment. When a label changes, the commitment to the original resource and selected part should not change by accident. The specification distinguishes a plain URI from JSON-LD payloads and does not require content-state encoding for it. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Identify the transmitted form before applying serialization or transformation. Create two outputs from the same source: a reader-friendly explanation in the target language and a stable content-state payload. Then test the reader journey from the actual published link. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A middleware service indiscriminately base64url-encodes every value and confuses older clients and consumers. Test both a simple Manifest URI and a structured Canvas target through the same integration. When repairing failures, change the smallest layer responsible: a display label, a serialization step, a target relationship or the receiver’s parser. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Unicode and language-specific labels

An Arabic exhibition caption appears beside a Japanese description of the same bookmarked painting. Start with what the receiving application is supposed to do, not with a phrase that happens to appear on a screen. A precise description of that expected action is what makes multilingual review meaningful. Unicode text can appear in editorial surrounding content, but character safety must be addressed when encoding JSON state. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Use language-aware display fields for prose; keep target URIs and normalized protocol values consistent. In a review session, identify the publisher-controlled URI, then mark which adjacent fields are display language. Ask the translator to explain every altered value in terms of visitor meaning, not convenience. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A link builder assumes ASCII-only strings and corrupts a non-Latin note during a round trip. Try real non-Latin samples and compare decoded characters, directionality and exact target identity. A screen capture is not enough as a technical test; compare the resolved resource identifier and any selection parameters against the known source. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Different viewers, one resource

A gallery kiosk sends a bookmark to a scholar’s desktop application with unfamiliar navigation controls. The same object can be described differently for students, curators and researchers. Those audiences need helpful wording, but they should not silently inherit different claims about the underlying evidence. Content State is intentionally independent of a particular interface or application framework. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Specify acceptance tests around the selected resource and focus, not the appearance of toolbar controls. This distinction is especially valuable for digital objects reused by universities and cultural organizations in different countries. No single institution can assume every viewer uses its interface conventions. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A team marks a valid viewer as broken because its zoom animation differs from the exporting application. Measure functional equivalence by resource, Canvas, region, time and user-visible destination. Keep the original state available while investigating discrepancies. Without it, a reviewer may mistake a newly generated link for the evidence first cited. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Search result to target journey

A visitor searches for a name mentioned in a manuscript and follows the result into a page viewer. Reading the structure first avoids a surprisingly common confusion: a visible string may be a translation candidate, an immutable identifier, or a statement about source evidence. Each has a different owner. Search tells us where a match was found; Content State transports the view needed to inspect that match. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Translate the result snippet while keeping the search hit’s original target tied to the source object. Use plain language in the interface to set expectations. A translated label should say what the user will open, rather than promising search, playback or access behavior the receiving application cannot provide. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A translated phrase is searched again inside another language text layer, selecting a different occurrence. Use the source annotation or source region to open the cited location, then display translation as a separate aid. A localization pass is complete only when both ordinary readers and interoperability checks agree on what was requested and what was delivered. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Content State is not Change Discovery

A digital library publishes new language labels and distributes update notifications to aggregation partners. One useful mental test is to imagine the visitor changing languages halfway through the journey. The selected resource must remain the same even if navigation labels and explanatory prose change. Change Discovery announces resource lifecycle events; Content State initializes a particular view. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Use each API for its own job and connect them only through stable underlying resource references. A strong implementation makes this separation explicit in the data model. It stores translated wording as wording, and it retains the external reference as a reference rather than regenerating it. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A partner sends a Change Discovery activity to a viewer as if it were a bookmark. Verify that update feeds refresh indexes and deep links open resources without conflating their purposes. Do not treat visual similarity as proof of equivalence. Two pages can look alike while pointing to different assets, versions or regions. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Security and untrusted targets

A public viewer accepts bookmark links from email, messaging applications and outside websites. A complete handoff should be explainable without relying on the exporting software. If another institution cannot tell what was selected, the description is not genuinely portable. The received target may refer to an unfamiliar URI and should be handled with appropriate trust boundaries. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Apply URL safety checks, access policy and resource-type verification before fetching untrusted content. Before applying a bulk operation, test a representative record with several languages, unusual characters and more than one selection type. A failure at that scale is easier to diagnose than one found after publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A browser or proxy blindly follows a malicious target or logs access tokens embedded in a shared link. Test disallowed schemes, private network addresses and sensitive query strings through the viewer’s security controls. Prefer a test that would fail on the common mistake described above. This makes review diagnostic rather than a ceremonial approval step. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Authorization and restricted resources

A museum shares a deep link into a licensed audio archive with a colleague who lacks access. Design the handoff around the reader’s intended question. The content reference answers where to look; translated prose explains why that location deserves attention. A valid Content State target does not itself grant the recipient a right to view restricted media. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Translate permission explanations accurately and let the separate access process enforce authorization. Reviewers should be able to repeat the exact journey independently. Record the target identifier and intended focus in a compact acceptance note before publication. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A public caption promises unrestricted playback because the sender could see the recording. Open the link as an unauthenticated visitor and verify that both explanation and access outcome are truthful. Where the source is protected or unavailable, record that limitation rather than quietly replacing the target with an accessible but different object. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Citation and historical evidence

A historian cites the left-hand signature block of a particular archival folio. Technical fidelity and good writing serve different purposes. A readable translation helps a person, while a stable target lets software take that person to the actual evidence. A precise bookmark supports inspection of a claim only if it also retains reliable object and page context. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Include stable descriptive citations alongside the machine-readable state where appropriate. Compare the sender’s intent with the receiver’s result. Seeing a page open is only the beginning; it may still be the wrong page, the wrong region or an unintended playback moment. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A link captures a region but omits the document title and institutional holding information needed for later interpretation. Revisit the citation after a catalogue revision and confirm that the target and source description remain traceable. Log the exact language and client environment used in the test. That information helps separate text-direction problems from missing target references. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Localization of labels versus IDs

A multilingual team wants to replace the word Canvas with its local equivalent in help text. Treat the shared target as a citation-like commitment. When a label changes, the commitment to the original resource and selected part should not change by accident. Terms in human help documentation are different from property names, type values and identifiers in JSON-LD. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Translate what the visitor reads while protecting the vocabulary that participating software recognizes. Create two outputs from the same source: a reader-friendly explanation in the target language and a stable content-state payload. Then test the reader journey from the actual published link. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

A global string replacement modifies the same term inside code and descriptive prose at once. Diff the serialized state before and after localization; protocol keys and URIs should remain unchanged. When repairing failures, change the smallest layer responsible: a display label, a serialization step, a target relationship or the receiver’s parser. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Testing deep links systematically

A repository launches five new language interfaces across desktop, mobile and public kiosks. Start with what the receiving application is supposed to do, not with a phrase that happens to appear on a screen. A precise description of that expected action is what makes multilingual review meaningful. A complete test matrix crosses language, viewer, resource type, selection type and access state. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Create a compact set of known target cases and require every supported viewer to reach the same evidence. In a review session, identify the publisher-controlled URI, then mark which adjacent fields are display language. Ask the translator to explain every altered value in terms of visitor meaning, not convenience. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Testing only the default English Manifest hides errors in region encoding, right-to-left labels or restricted items. Record expected and actual Canvas IDs, crop coordinates, start time, HTTP response and access decisions. A screen capture is not enough as a technical test; compare the resolved resource identifier and any selection parameters against the known source. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

A sensible publishing and repair workflow

A museum team is ready to publish multilingual bookmarks created from older catalogue records. The same object can be described differently for students, curators and researchers. Those audiences need helpful wording, but they should not silently inherit different claims about the underlying evidence. The durable unit is the original content reference; captions and navigation labels are maintained independently. Notice the difference between a public explanation of the choice and the underlying object reference: the former may improve when translated, but the latter must remain anchored in the publisher’s data. If the reader cannot describe which source object is being inspected, the interface has not made the evidence clear.

Freeze a small acceptance corpus, correct data-level errors, then deploy translations without altering source IDs. This distinction is especially valuable for digital objects reused by universities and cultural organizations in different countries. No single institution can assume every viewer uses its interface conventions. A useful way to teach this decision is to let two readers use different interface languages, compare the visible wording, and then identify the exact reference both journeys should resolve. The result should be understandable as well as technically repeatable.

Shipping hundreds of new localized links before checking the first ten spreads silent breakage widely. Keep a rollback path for newly generated links and an audit trail of which source records they reference. Keep the original state available while investigating discrepancies. Without it, a reviewer may mistake a newly generated link for the evidence first cited. Write the expected outcome as a checkable statement before running the test. The reviewer should know what a success looks like and what particular mistake the test is designed to detect.

Worked implementation exercise: multilingual source-to-viewer handoff

Suppose a library publishes a bilingual catalogue entry for a handwritten diary. A Spanish reader searches for a person’s name and selects a result linked to Canvas 14. The search service knows the relevant Canvas and a rectangular region around the name. The viewer, however, is run by another institution. Begin with the canonical Manifest URI, the Canvas URI and the specified rectangle. Make a content state target that carries the Canvas and its Manifest relationship; apply the prescribed serialization if it travels as JSON-LD through an HTTP GET parameter.

Now build two visible links with different action text: one in Spanish and one in English. Both links carry the same target, although their public descriptions differ. Launch each from a fresh browser session. Record the Manifest that loads, the selected Canvas and the highlighted or zoomed location. Do not accept a pass simply because both links land on the diary. They must reach the same cited evidence. If the receiving viewer cannot honor a selection, make the limitation visible instead of silently pretending that the selection was reproduced.

Next add a restricted oral-history item. The source link identifies a permitted time offset in a recording, but access requires authentication. Confirm that an unauthenticated visitor sees an accurate access explanation and not an unrelated substitute. Finally test Japanese and Arabic explanatory text, a source with punctuation inside an identifier and a saved state whose Canvas is not independently dereferenceable. These cases exercise character handling, target relationships and permission boundaries without asking a translator to change any of them.

A practical review checklist

A good handoff can be reviewed in seven passes. First, identify the source resource and preserve its URI. Second, determine whether the intended view is a whole Manifest, a Canvas, a Range, a region or a temporal segment. Third, choose a supported Content State form with the relationships needed to describe the target. Fourth, serialize the state appropriately for the chosen transport. Fifth, localize interface text and descriptions independently of machine-readable protocol fields. Sixth, open the state in more than one client and language. Seventh, record mismatches, rights restrictions and content changes rather than smoothing them over.

The order matters. If a team starts by translating strings in the serialized state, it may inadvertently edit fields that software uses to parse or resolve the selection. If the team waits to test until publication, it may have no clean record of the original reference. Starting with identity and ending with a reproducible viewer test makes the workflow easier to teach to cataloguers, translators, developers and digital-humanities researchers.

Frequently asked questions

What is the difference between a Manifest link and a Content State link?

A Manifest link opens an entire resource; a Content State can specify that resource or a more precise selected part, such as a Canvas region or time offset. The distinction is important for citations and research tasks requiring exact evidence.

Can translated interfaces share the same bookmark?

Yes, when both interfaces resolve the same source resource and selection. Their labels can differ while identifiers, coordinates and structural references remain stable. Viewer support still needs to be tested.

Should a JSON-LD key be translated?

No. Names used by the protocol are machine-readable keys. Translate public-facing help, captions and metadata language fields, while keeping structure defined by the specification intact.

Does Content State replace IIIF Presentation?

No. It depends on IIIF resources and their model. The Presentation API describes the resources, while Content State communicates the intended view to an application.

Can a shared link override archive access restrictions?

No. The target may be correct even when the recipient is not authorized to access the underlying media. The viewer should enforce access policy separately.

How should a complex state travel in a URL?

Use the Content State API’s content-state encoding for JSON-LD passed through a GET query parameter. Plain URI states follow the specification’s different handling. Test both forms end to end.