Translate Web Annotation JSON-LD Without Losing Target Anchors

Translating a Web Annotation JSON-LD record quickly is not the same as translating every string in a JSON file. The central job is to localize the comment, tag, or explanatory body while preserving the precise passage, image region, or resource the annotation points to. A reliable web annotation localization workflow separates editable human language from stable annotation identifiers, selectors, motivations, and target references before any words change.

A teacher might annotate a science reading with “This claim needs evidence,” then provide a Malay or Chinese version for another class. If the translated annotation attaches to the wrong sentence, its language can be perfect and its educational meaning still wrong. The student sees a criticism beside a different claim. Translation quality in this setting must include anchoring quality, not merely fluent prose.

This guide explains how to translate W3C Web Annotation Data Model records, especially JSON-LD TextualBody values and tagging labels, without corrupting target, source, selector, exact, prefix, suffix, id, or the intent expressed by motivation. It focuses on one reader job: deliver localized annotations that still refer to the correct original evidence. It does not teach general translation theory or redesign annotation systems.

Begin with the object, not the sentence

A web annotation is a structured relationship rather than an isolated note. A reader highlights two lines of an online article and writes a comment. The note is the body; the highlighted part is the target; and the annotation connects them. A platform can store a target as an entire page or describe a narrower section by way of selectors. Translators must see those components separately because only one component may contain words intended to be replaced.

Imagine a laboratory handout saying that a metal sample warmed from 20 °C to 45 °C. A student’s English annotation reads, “State whether the increase is temperature or thermal energy.” The translation can replace this instructional sentence, but it must not replace the text quote used to find the passage in the English source. The quote serves as an address into the original material. If it is translated to Malay while the source page remains English, the anchor may disappear. The problem resembles changing a postal address because it contains readable words: it looks linguistically tidy, but delivery fails.

The first action is therefore inventory. Identify the annotation’s persistent id, the body, the target, any selector, optional state, its motivation, and the target document version. Mark the body as a candidate for human translation. Mark the other fields for preservation or for separately reviewed migration if the underlying source itself will change. This order is faster than making repairs after students report orphaned notes.

A deliberately small specimen

A minimal JSON-LD example can represent a comment associated with a stable passage of a school handout. The official model uses @context, id, type, body, and target. For a language-tagged comment, an embedded TextualBody with value, format, and language is appropriate. A text quote selector may have exact as well as surrounding prefix and suffix used for disambiguation.

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://example.edu/annotations/heat-17-ms",
  "type": "Annotation",
  "motivation": "commenting",
  "body": {
    "type": "TextualBody",
    "value": "Jelaskan mengapa bacaan suhu meningkat.",
    "format": "text/plain",
    "language": "ms"
  },
  "target": {
    "source": "https://example.edu/lessons/heat-en",
    "selector": {
      "type": "TextQuoteSelector",
      "exact": "The temperature rose from 20 to 45 degrees Celsius.",
      "prefix": "During the demonstration, ",
      "suffix": " Students recorded the reading."
    }
  }
}

This is an illustrative record, not a claim that the example URLs host resources. Its comment is in Malay, while its target points to English source text. That asymmetry is intentional. One language can describe another language’s evidence. id identifies this particular localized annotation; a project deciding between variant annotations and alternate-language bodies must define its own identity policy. The translator should not spontaneously reuse or rename identifiers to make them match translated words.

Before translating, the reviewer should articulate the intended effect in ordinary language: a learner looking at the English temperature sentence will see the Malay instruction to explain the rise. That plain-language test catches mistakes that a syntactically valid JSON document cannot detect. The machine sees a body and a target; the teacher must ensure their relationship is pedagogically appropriate.

Draw a change boundary around natural language

A practical change boundary has three classes. The first includes strings that the learner reads as instructional speech: comments, descriptions, help text, and some human-readable tags. The second includes machine values that happen to be written with letters: types, motivations, fragment identifiers, paths, and selector class names. The third includes hybrid strings, especially quoted original text, whose human language is serving as a locator. Different preservation rules apply to each class.

In the sample, value is translatable because it is what the teacher wants the pupil to read. language changes to the code representing that language. The format value text/plain is a media type, not a phrase for translation. TextualBody, TextQuoteSelector, and commenting are terms from a vocabulary, so translating them breaks the intended semantic meaning. The source URL must remain stable unless the project is explicitly migrating its annotation to a corresponding localized source document.

The third class requires the most judgment. An English quote in exact may look like the perfect sentence to translate. However, the quote is stored to match a particular segment of the English source. Change that phrase and the selector may no longer select anything. The operational rule is to keep the quoted source text intact when the source does not change. When the project does translate the source, rebuild the selector against that new source and verify it independently; do not perform the two operations as one unreviewed find-and-replace.

Preserve motivation because it tells users what the action means

An annotation may be for commenting, tagging, highlighting, assessing, describing, or another modelled purpose. Motivation is not decorative metadata. A platform can use it to decide how a note is presented and whether it belongs in a review sidebar, a tagging view, or a teaching feedback panel. The localized body might contain the same words under different motivations and still mean a different kind of interaction.

Suppose a teacher writes “Key idea” beside a paragraph. If the record has a tagging motivation, it may contribute to a group of topic tags. If a workflow expects a commenting motivation, the same text may instead appear as a teacher comment. Replacing the motivation with a translated ordinary word such as an equivalent of “commenting” in another language is not localization of the display: it is an invalid vocabulary value. A competent translator marks motivation fields read-only and allows the application to provide any localized user-interface phrase for those coded operations.

Do not conflate the body language with the motivation either. A comment saying “This might be an example” is still a comment even if translated for another class. A tag meaning “examples” remains a tag, but its actual string may need different grammatical form depending on whether students search by topic or read a sentence. The QA pair is a semantics check on the human string and an identity check on the motivation. Both are necessary, and they are evaluated through different evidence.

Work out whether a target belongs to a source or a translation

There are at least two legitimate classroom arrangements. In the first, international students read an English article and receive notes in their preferred language. The source reference stays the English page; only annotation body language changes. In the second, students read localized copies of the article. Every version has its own text, pagination, and sometimes ordering. A translation may therefore require a target migration to the translated page as well as a new quotation selector there.

The dangerous case is an accidental mixture: a body translated for Malay students, an English source URL, and a quote selector translated as though it were locating the Malay page. It cannot reliably match either version. A second dangerous case changes the source URL to a Malay translation but leaves an English quote selector behind. The record may pass JSON validation and fail visually. Neither situation can be fixed by improving the note’s prose because the error lives in the target layer.

Create a simple target-decision record for each batch: target version, intended class language, whether the source changes, whether the selectors are rebased, and who verifies the correspondence. If a source is unchanged, freeze its locator information. If a source is replaced, perform a migration with an explicit mapping between old and new passages. That mapping should be reviewed by a reader who understands both passages, not inferred from how similar the sentences look.

TextQuoteSelector is a locator, not a translation field

A TextQuoteSelector includes an exact selected phrase and may include preceding prefix and following suffix context. These fields help software find the segment in the target resource, especially when the quoted phrase appears more than once. The strings are readable text, but they are part of the selection mechanism. W3C describes them as quoted text that a client uses for targeting; they are not interchangeable with the annotation’s message.

Take a history article that mentions “trade routes” twice. One occurrence describes the Silk Road and another describes maritime exchanges. A note saying “Compare these two networks” might refer only to the maritime paragraph. If an editor preserves exact but accidentally replaces prefix and suffix with a translation from a different version, the selector becomes ambiguous. A client may attach the note to the wrong occurrence or show that the text could not be found. For a pupil, that wrong attachment changes the question being asked.

When testing, resolve the annotation against the actual original resource, not against a convenient local text pasted into a spreadsheet. Search for the exact selected text, inspect its surrounding context, and confirm that the intended occurrence is selected. A collision between repeated phrases should be treated as a locator defect, not ignored because a first occurrence can technically be found. If the source page is dynamic, record the current content or version so a future edit does not silently invalidate the review.

TextPositionSelector has different risks from text quotes

Some systems describe a target by character offsets rather than quoted strings. A text position selector has a start and end measured in the target representation. Translation of the comment does not require changing those offsets when the source stays unchanged. However, if the source itself is translated or reformatted, its length, grapheme composition, and order may change. Copying the same offsets to another language is not equivalent to selecting the same idea.

Imagine the source passage “The sample remained stable.” at a known character range. A Chinese translation can represent comparable meaning with a different number of Unicode code points. Keeping the old start and end numbers may mark half a word, an unrelated paragraph, or an empty range. Combining characters and right-to-left text add further hazards. The reviewer must use the selection model’s counting rule rather than assuming that a visible character always consumes one code unit in every programming environment.

The helpful division is this: body translation means no positional rebasing; source translation may require target rebasing. If an authoring system converts a quote selector to a position selector during export, test the newly exported file rather than trusting visual equivalence in the editor. Document whether the editor used Unicode code points, UTF-16 code units, or a normalized text representation. When the mapping cannot be guaranteed, report an anchoring risk instead of claiming automatic transfer.

Human tags require terminology decisions

Textual tags are often shorter than explanatory comments. That makes them easy to translate quickly, but their information role can be more delicate. A teacher might label annotations as “Claim,” “Evidence,” “Counterexample,” and “Next step.” Translating those labels independently can create different terms for the same classroom action. Students then search for “evidence” and miss half the relevant notes because the tags have split into synonyms.

Treat a tagging body as part of a controlled vocabulary when the course relies on tag filtering, analytics, or consistent marking language. Establish one preferred term for each classroom concept in each target language, and record a note about its usage. When a term carries multiple senses, add a brief scope instruction. A label for “evidence” in a science experiment may not be the same word choice as evidence admitted in a legal argument. Vocabulary selection must respect the learning task rather than mimic dictionary entries.

Some platforms use identifier-based semantic tags rather than plain text labels. If the tag points to a URI for a concept, keep that URI stable and translate only its presented label through the appropriate vocabulary system. Do not substitute a translated URL slug for a stable concept identifier. A tag service may use the URI to group notes across language variants, which is exactly what multilingual search needs. Preserve the common concept even as the visible phrase changes.

Names, identifiers, and provenance should stay accountable

Annotations can record their creator, creation time, and other provenance. These fields answer who said something and when. Translators must avoid making it seem that a localized note was authored or endorsed by the original speaker if it was materially changed. For a teacher note, the translated version might be a faithful restatement; for peer comments, it may include ambiguity or colloquial phrasing that deserves a review flag.

Keep the original annotation identifier and the localized annotation identifier distinct when the project stores variants as separate records. If a platform uses a multilingual body policy, follow that design rather than inventing duplicate records. The key is that readers and administrators can trace an annotation back to its source, translation status, and reviewer. Changing the id because it contains an English word without coordinating references can orphan replies or duplicate annotations during import.

A useful review ledger records original record ID, source version, target locale, body fields edited, target-selector policy, reviewer, verification outcome, and publication status. The ledger need not appear in the classroom UI. Its value becomes visible when a teacher later reports that one note in a group of two hundred is attached incorrectly. With a stable mapping, the team can find that record, compare its versions, and fix the locator without touching the other translated comments.

A practical extraction method for a mixed-language collection

The fastest safe batch workflow begins by making a read-only copy of the source records. Parse each JSON-LD record and extract only text intended for translation. A simple extraction table can include a row identifier, JSON pointer or application field path, source language, source text, surrounding teaching context, maximum desired length, and whether the item is a comment, a tag, or a caption. Give the translator enough target context to select the right voice without exposing every graph property as editable text.

For example, row A-017 might point to body.value, show an English instruction, identify its target as a paragraph about thermal energy, and specify that the destination is a Malay Secondary 2 classroom. The translator does not need to edit the selector.exact string. That selector is available only as read-only context. When the target document has the same text in several locations, the extractor can add a screenshot or a short surrounding passage to prevent semantic mistakes, but must not ask the translator to rewrite the identifier.

Import the translated text by matching each row to its stored field path and record identity. Validate that the number of records, their IDs, motivations, target sources, selector types, and locator values are unchanged whenever source-target migration is not part of the task. This is a comparison against the baseline, not merely a schema check on the new file. A structurally valid import can still be a different annotation collection if IDs or targets have been replaced inadvertently.

Understand language tags rather than inventing them

The language property identifies the language of a body, and the model points to established language-tag practice. The code is not a free-form translated language name. A tag such as ms identifies Malay, while a more specific tag can be appropriate for a particular variant when the project actually needs that distinction. A Chinese body might use zh-Hans or zh-Hant when script distinction matters. The correct choice depends on the deployment, not on a desire to include more characters.

Do not assume that a class’s location automatically determines the written language variety. A school in Singapore may use English, Malay, Chinese, or Tamil as the teaching language for different activities. A multilingual annotation system might display one or several language options to a learner; its selection policy must be defined separately from the file’s contents. An annotation tagged with the wrong language can be hidden by a language filter even when the translation is excellent.

After import, have a reviewer check several records by switching the application’s language or filter. The question is whether the body that appears is the intended target-language text and whether the correct class or student can access it. If the application falls back to English for missing locales, report the fallback rather than presenting it as a successful translation. An apparently complete file may still contain untranslated bodies with incorrect language tags.

Test text formats and embedded markup deliberately

A TextualBody can declare a plain-text or HTML format. If the body uses text/plain, characters such as angle brackets and ampersands are text rather than markup to be interpreted. If the body uses text/html, the translated string might contain formatting, emphasis, or links. Do not silently change the format while translating. Changing only the body text while preserving the format is often sufficient, but the content must match the declared media type.

For a classroom note, a teacher might emphasise the word “not” in “Do not add the two percentages.” In a permitted HTML body that emphasis should remain attached to the correct translated word. A naive translator may translate the entire HTML string through a generic service and break the tags, detach the emphasis, or strip a hyperlink. Conversely, a string that looks like HTML but is stored as plain text can display literal tags if the system does not interpret them. Both cases are usability problems, not only aesthetic errors.

Use a safe HTML editor or a structured translation view that protects markup boundaries. Keep existing links unchanged unless there is a reviewed localized destination. Preview the rendered note in the real annotation client. Test screen-reader ordering and keyboard focus where the product supports these controls. If the user interface truncates longer languages, adjust the presentation or write a precise shorter translation without dropping the instructional condition that makes the note useful.

Work the first example: science feedback on an English source

A teacher annotates the sentence “A temperature rise does not by itself tell us the amount of heat transferred.” The English comment is “Explain why mass is relevant before calculating energy.” The students will read the same English lesson, but the class discussion notes will be provided in Malay. The answer is to localize the comment and its language metadata, leaving the original quote selector and lesson URL unchanged.

A poor attempt translates the source sentence inside the selector as well. The resulting selector searches for Malay words inside an English paragraph. The comment may disappear from the margin. A second poor attempt keeps the quote selector but translates the URL slug from /heat-en to an imagined /haba-ms, creating a destination that may not exist. The teacher sees a working Malay sentence in the export file and reasonably believes the job is finished, yet students cannot find the note where it belongs.

The repaired workflow changes only the body.value, changes body.language to ms, confirms body.format, and runs a viewer test against the original English article. A reviewer then checks the pedagogical meaning: the note asks students to explain the relevance of mass, not to calculate mass immediately. Localization has succeeded only when the student encounters that question at the intended sentence and understands the relationship between mass, temperature change, and energy.

Work the second example: changing a history source language

Now consider a different assignment. A school has translated an English history reading into Chinese and wants each old teacher annotation to appear alongside the equivalent Chinese passage. This is no longer just body translation. The task includes relocating targets because the source resource has changed. The English quote “Trade networks connected distant ports” might be rendered as a Chinese sentence with different position and punctuation.

First preserve the old English annotation as the reference record. Then identify the conceptually equivalent segment in the reviewed Chinese reading. Point the new record to the actual Chinese resource, build a selector from the text as it appears there, and verify it in the Chinese client. The translated annotation body should refer to what the Chinese sentence actually says, rather than relying on an old English punctuation pattern. If a paragraph was split or condensed, a human may need to choose a narrower or broader target deliberately.

This illustrates why bulk translation and target migration must remain separate approval stages. The first is a language task with preservation of pointers; the second is an editorial mapping task with possible structural changes. In a school assessment, merging them can cause pupils to receive feedback on a different claim from the one their peers see. A correct migrated annotation requires both a sound translation and a documented passage correspondence.

Work the third example: literature with repeated quotations

In a literature discussion, the same short phrase may recur at the beginning and end of a poem. The teacher’s annotation comments on its changed meaning in the final stanza. A quote selector using only the phrase may attach the note to the first stanza, where its interpretation is misleading. Translating the body into another language does not remove this ambiguity. The issue exists in the source anchor, and localization exposes it when the reviewer checks the display carefully.

Use the recorded prefix and suffix, a more specific selector, or whatever stable targeting mechanism the annotation client supports. Confirm that the target includes the relevant stanza before translating the teacher’s interpretation. When the poem is distributed in different editions, verify the exact edition used in the class: punctuation, line breaks, and even one revised word can affect targeting. Do not claim that an annotation is edition-independent because it was exported as JSON-LD.

The localized note should explain the final-stanza function in accessible language without replacing the quotation in the locator. A bilingual literature specialist can verify the nuance of “returns,” “echoes,” or “reverses,” depending on the poem. The technical reviewer checks one thing and the subject reviewer another. Bringing the checks together is more efficient than asking one person to intuitively confirm both interpretation and machine anchoring from a screenshot.

Check accessibility before declaring success

A multilingual annotation may be visually present but inaccessible to a learner using keyboard navigation or assistive technology. A sticky-note icon might contain the localized body but have a generic English accessible name. A sidebar might show the correct comment while the highlighted passage is announced without any indication of a note. These are application-level issues that JSON syntax validation cannot detect.

Test with the actual client controls available to the school. Navigate from the source passage to its associated annotation without relying on pointer hover alone. Ensure that assistive technology does not announce the entire raw JSON object or the target URI as the comment. When a body is tagged with a right-to-left language, inspect punctuation and mixed-language terms; visual reversal should not alter the underlying target or quoted source text. Keep the document’s reading order consistent with the passage learners are studying.

Accessibility review also includes pedagogy. Long translated explanations may be harder to process in a narrow popover than in a review panel. If the note exceeds the interface, provide an accessible expansion or improve the layout. Do not solve clipping by deleting the essential exception in the instruction. The goal is not to force a translated string into the original number of characters; it is to preserve usable learning guidance attached to the correct evidence.

Build a two-layer validation plan

Layer one is a structural comparison. Confirm that records parse; required fields exist; body types, language tags, motivations, target sources, and selectors meet the profile expected by the software. Compare read-only fields with the source baseline. A simple property inventory can detect unexpected changes before anyone opens the teaching platform. If the collection contains one hundred records and only twenty are meant to be translated, it is suspicious when all one hundred targets have new identifiers.

Layer two is behaviour. Open the target document as a learner, navigate to annotations, filter by language, and verify a carefully chosen sample. Include a common passage, repeated-phrase passage, very short tag, long explanation, non-Latin script, link, and a source document with recent edits. For each sample ask two questions: does the body say the right thing, and does it attach to the right content? Both answers must be yes. A schema validator can establish neither by itself.

A practical failure register distinguishes “body untranslated,” “wrong language tag,” “orphaned target,” “ambiguous selector,” “wrong motivation,” “formatting broken,” and “classroom meaning changed.” These categories help a team route problems to language reviewers, engineers, or teachers. They also prevent false optimism: a record is not ready just because a JSON parser returns no errors. A robust import gate rejects unresolved high-impact issues, even when the translated sentences read fluently.

Why a good translation can still be the wrong comment

Consider an English teacher comment: “This evidence does not support the conclusion.” A translator may produce a grammatically perfect sentence conveying that idea. But if the note is attached to a supporting paragraph rather than to the essay’s conclusion, the learner may interpret it as criticism of the entire assignment or the wrong source. An annotation’s meaning is distributed between the message and its location. Moving the note changes its apparent claim.

This phenomenon explains the central QA principle for annotation localization: do not assess sentences without their targets. A translator looking only at extracted strings may choose an ambiguous pronoun such as “this” because it made sense in the source. The target might show two diagrams, making that pronoun insufficient for another language. Provide a short context hint or approved wording that names the claim rather than weakening the sentence. At the same time, avoid adding new judgments that the teacher did not make.

Human review must check deixis: “here,” “above,” “the second sentence,” “this graph,” and “the previous point” depend on document layout and targeting. A localized reading order may move sections around. The safest note may repeat the referent explicitly while preserving the teacher’s intended criticism. A fluent translation is necessary; location-aware interpretation makes it useful.

Failures that deserve a hard stop

Some defects can be repaired during routine polishing. Others should block release. A note that opens slowly is inconvenient; a note attached to the wrong safety instruction may be dangerous. An annotation copied onto a graded answer can change what a student thinks they must submit. A citation note whose target now points to an unrelated source may mislead research. If the annotation is used to make a decision rather than to decorate a page, anchoring errors have real consequences.

Hard-stop conditions include target URLs changed without approved migration; selector quotes rewritten against unchanged source text; mismatched language codes that hide content; lost bodies after import; changed annotation motivation without specification; and comments whose referents no longer make sense. Reviewers should record these in language students and content editors can understand. “Selector integrity failure” may be correct technical language, but “The note now points at the wrong sentence” better communicates the urgency.

Use a small release checklist rather than a huge unprioritized defect log. Every unresolved critical issue should identify the record, its intended source, its current wrong behaviour, the person responsible, and the retest required. If the source page is unavailable or permission-protected, note that the target could not be verified. Do not substitute a static screenshot as proof that the annotation will work in a live classroom.

An efficient classroom review sequence

Begin with one representative annotation before processing the batch. The teacher identifies the original target and explains the learner action. The translator produces a target-language body and, if necessary, a terminology note. The engineer imports it into a safe test space without changing identifiers or selectors. The teacher sees the rendered result on the real page and confirms that its meaning and position are both correct. Only then should the same controlled method be applied to more records.

This pilot reveals assumptions about the annotation client’s handling of languages, body formats, replies, selectors, and hidden text. It is much cheaper to discover that a language filter expects a particular tag on the first record than after translating a thousand comments. For larger sets, prioritize a sample that includes multiple motivations and selector types rather than testing only the most common note. One successful comment is weak evidence about an unrelated tagging workflow.

For release, maintain source and target snapshots. A snapshot need not expose student identities in a public file; the team can use redacted sample records and secure internal evidence. After export, inspect the count of annotations attached to the intended resources, the distribution of languages, and the frequency of unattached entries. An unexpected change in those figures is a signal for investigation, not necessarily proof of misconduct or a software bug.

A changed-context exercise: translate the annotation and the article

Imagine that a geography class uses a bilingual online reading about flood risk. The English article has the sentence “Impermeable surfaces increase surface runoff after intense rain.” A teacher note says, “Explain why the effect is stronger in this neighbourhood.” The school publishes a reviewed Chinese version of the article and asks for Chinese teacher notes. An assistant proposes to translate the note, keep the English TextQuoteSelector.exact, and change only target.source to the Chinese page.

That proposal does not satisfy the reader job. The translated note might be correct, but the English quote cannot be assumed to select its corresponding Chinese sentence. A correct process preserves the original English record, selects the equivalent passage in the actual Chinese text, constructs a new selector there, and tests the note in the deployed Chinese reading. The reviewer also checks whether “this neighbourhood” is clear in the new layout and whether the translated article preserved the same local referent.

Now vary the exercise. Suppose the English article remains in place and only the note is localized. In that case the earlier approach of preserving the English source URL and quote selector is appropriate. The rule changes because the target changed, not because Chinese requires special treatment. This transferable distinction works for Malay science comments, Tamil history notes, Arabic legal annotations, and any other language pair supported by the application’s design.

Beyond classroom feedback: transfer the method to research

Research teams annotate archived interviews, newspaper articles, and public-domain documents. A note may identify a methodological limitation or clarify a source term. If the group works in multiple languages, translating the annotation can make the review accessible without altering the quoted source. The same change boundary applies: translate explanatory body text; preserve its evidentiary anchor unless the target resource changes and a deliberate remapping is performed.

Consider an interview transcript in English with a researcher note reading, “The speaker qualifies the previous claim.” A French translation that loses “previous” changes the analytic relation. A French note that points to the wrong exchange is worse because it misidentifies the evidence. The reviewer should cross-check the note against the speaker’s actual turn, whether the transcript is plain text, a timed recording, or a page image. The model can describe targets at different media levels, but the client must support the chosen selector for validation to be meaningful.

For high-stakes research, keep a clear provenance trail for the original note and its language variants. If the source has licensing restrictions, do not copy entire protected passages into a translation spreadsheet merely for convenience. Minimal snippets or authorized context can be sufficient. Good localization respects not only grammar and targeting, but also the rights and privacy of the source material.

Beyond classrooms: transfer the method to customer support

An online manual can attach annotations to particular troubleshooting steps. A support agent’s note might say, “This instruction applies only to revision B.” Translating it for international users is helpful, but a shifted anchor could make the note appear beside the instructions for revision A. Even if the words are accurate, the resulting guidance can cause avoidable mistakes. The same two-layer validation—body meaning plus target identity—applies in a product environment.

This use case also shows why dates and version numbers matter. An annotation can be valid for one document revision and misleading for the next. Localization should preserve source provenance and record whether the target was inspected after the manual changed. If the company publishes fully localized manuals, annotations must be rebased against each version’s passages. A stable item identifier can help link equivalences, but it does not guarantee that two documents discuss exactly the same steps.

The transfer principle can be stated simply: if a message derives meaning from being near something else, translate the message and verify the something else separately. This covers teacher feedback, research comments, editorial suggestions, and help-system notes. It is what makes annotation localization a distinct reader job instead of another general article about translating accurately.

A practical reviewer checklist

Before signing off, reviewers should confirm the intended reading audience, the annotation’s body language, and whether its target is the original source or a localized copy. Compare stable fields with the source record and investigate unauthorized changes to IDs, URLs, motivations, selector types, quotations, and positions. If the project includes target migration, demand an explicit mapping table and a human test of the new anchors. Do not treat successful JSON parsing as proof of passage equivalence.

Then inspect the rendered client. A student should see each note at the intended passage, identify who is speaking, read the body in the intended language, and follow any links or classroom actions without guessing. Include a repeated quotation, a right-to-left or non-Latin language where relevant, and a long note that challenges the interface. Verify that a screen reader or keyboard user has a reasonable route to the comment if accessibility is required by the deployment.

Finally, record known limits. A dynamic page may reflow; a source may be edited tomorrow; a third-party annotation client may not implement all W3C selector types; and a translation may be awaiting subject-specialist review. The report should distinguish what was actually tested from what remains a risk. Confidence becomes credible when its boundary is visible, not when a project announces that every file is “fully translated” after running a string replacement.

The method in one decision

Ask first whether the source material changes. When it does not, localize the reader-facing body and preserve the target machinery. When the source changes, treat target remapping as a second, separately tested project. In both cases, check that the annotation body communicates the right instruction beside the right evidence in the actual client. This is faster than debugging orphaned highlights after release because it protects the relationships that make the comments useful.

An annotation is not merely a sentence. It is a sentence in relation to a particular part of a resource. That relation is the difference between feedback and misinformation. Good translation therefore respects both language and location, while keeping machine identities stable wherever the learning job permits.

Frequently asked questions

Should I translate `TextQuoteSelector.exact`?

Not when the target remains the original source. It is locator text expected to match that source. If you move the annotation to a separately translated source, rebuild and validate the selector against the actual translated passage.

Can I translate the `commenting` motivation?

No. It is a controlled value describing the annotation’s role. Translate the user-facing text, not the vocabulary term.

How can a body be Chinese while the selected quote is English?

The body is a comment in the learner’s language, while the target is an English passage. They perform different jobs and need not have the same language.

Is a valid JSON-LD file enough for publication?

No. Parsing checks syntax, not whether a selector attaches to the intended passage or whether a teacher’s instruction is accurate.

What happens if the same phrase appears twice in the article?

Inspect prefix, suffix, or another supported selector so the client selects the correct occurrence. A selector that lands on the first plausible match can still be wrong.

Are annotation IDs supposed to be translated?

Generally not. Identifiers support references, replies, and synchronization. Use a documented variant policy rather than inventing new IDs based on translated wording.

Why does a language tag matter if the sentence already looks translated?

Clients may filter and display annotation bodies by language. A wrong tag can hide or misroute an otherwise accurate translation.

Can I reuse position offsets for a translated article?

Not safely without a verified mapping. Translation changes length and ordering, so old offsets may select unrelated material.

Is a screenshot adequate QA evidence?

It can support a review, but it does not prove that live selectors, language filters, keyboard access, or future source versions work. Test in the actual client.

What should be blocked before release?

Unverified target migration, orphaned or wrong passage anchors, lost bodies, changed motivations, critical linguistic errors, or missing review of assessment-relevant feedback should block the affected records.

Authoritative sources

W3C, Web Annotation Data Model, Recommendation, 23 February 2017.
W3C, Web Annotation Vocabulary, Recommendation, 23 February 2017.
W3C, Selectors and States, technical specification for target selection models.

How People Translate Quickly | Web Annotation JSON-LD QA: Translate Comments Without Losing Their Targets