How do you translate HTML or XML correctly when some words must change but product codes, attributes, and embedded commands must not? W3C Internationalization Tag Set (ITS) 2.0 gives publishers and localization teams a way to identify translatable content and explain exceptional choices. This tutorial focuses on ITS translate flags, localization notes, and protected spans—not on generic word-for-word translation or on translating every software file format.
The practical problem is that a page can read beautifully after translation and still fail. A model might turn a product identifier into a plausible phrase, move the wrong text into a user-visible button, disregard a localization note, or flatten two distinct inline elements. The safe answer is to make the translatable boundary explicit, preserve the original document’s relationships, and compare the rendered result with the source. The examples below are fictional teaching examples, not extracts from a live service.
For a quick decision, separate natural-language content from instructions and identifiers; check local and global ITS rules; record every note that explains a confusing string; maintain the language and inline-element boundaries; and check both the source tree and the visitor-facing page after localization. This is a focused guide to authoring and interpreting ITS annotations, not a replacement for full ITS processor conformance testing.
- What to translate: visible prose, instructions and meaningful accessible names.
- What to preserve: stable identifiers, executable syntax and protected labels.
- How to decide: inspect the applicable ITS rules and the purpose of the string.
- How to prove quality: structural diff plus bilingual review in the running interface.
The visible problem: a fluent translation can be structurally wrong
Imagine a translator receives a perfectly ordinary paragraph, a button name, two XML keys, an inline command and a note about an unusual term. The words look simple. The real difficulty is that each piece of text has a different job. A translated command is no longer a working command; an unchanged support instruction may be unreadable; and an incorrectly moved link can imply a different destination. Translation quality therefore needs both the meaning of the sentence and the boundaries supplied by the document.
An efficient diagnosis begins by asking what would break if this particular character sequence changed. If a label names an interface action, it generally needs a target-language rendering. If it is a key used by application code, it generally must remain stable. If it is a registered product name or a physical label, the decision depends on approved naming and device conventions. The goal is not maximum translated coverage; it is correct, usable coverage.
First principles: why ITS annotations matter
1. A document is both language and structure
A translatable paragraph is a linguistic unit inside a larger document tree. The tree determines what a string is, where it appears, and how its content interacts with identifiers, inline components and actions.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
2. Protection is a positive editorial decision
A ‘do not translate’ instruction should not be a vague demand to keep everything English. It should mark a specific element whose meaning, identity or external dependency requires preservation.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
3. Local and global annotations need a resolution policy
An author may mark an element directly or write an external rule covering a class of elements. Teams must inspect the effective rule, including inheritance and selector behavior, rather than guessing from a tag name.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
4. A localization note communicates intent
Brief strings are especially hazardous because the grammar does not reveal the full job. Good notes explain the object, user action, audience, required distinctions and constraints.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
5. The source language and target locale are not synonyms
A content language answers what language a string contains. A target locale also introduces market-specific conventions and content applicability. These should not be collapsed into an unreviewed country guess.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
6. Inline segmentation affects grammar
Emphasis, hyperlinks and placeholders can sit inside one sentence. Extracting fragments independently may erase information about agreement, reference or the placement of a modifier.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
7. The rendered user journey is part of correctness
A valid file can still display a broken instruction. The target language must work in the browser, screen reader, form, device or publication workflow where the text will actually be encountered.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
8. A note is not a substitute for review
Even excellent metadata cannot determine whether a translation is socially appropriate, legally correct or clear to the actual reader. The note improves the evidence available for human judgment.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
9. Do not translate protocol identifiers
Machine-readable values that merely resemble ordinary words require explicit protection. Their interpretation belongs to the application contract, not the style guide.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
10. The canonical task is selective localization
This guide teaches the boundary between localizable content and protected structure. It does not duplicate the separate translation-series guides on idioms, tone, general glossaries or vocabulary acquisition.
Apply this principle to W3C Internationalization Tag Set (ITS) 2.0 by identifying a concrete source element, recording the effective interpretation, and asking what the target reader will do with the content. The danger is not only grammatical. An instruction may lead to the wrong operation, a protected identifier may be lost, or an omitted annotation may hide why a particular word has to remain unchanged. For this reason the translator, content owner and quality reviewer should each be able to explain the same decision in plain language.
Repeatable twelve-stage method for an ITS-aware translation
Step 1: Inventory the source
Export the actual HTML or XML and record language, document revision, format, publishing destination and intended audiences. A screenshot alone cannot identify hidden accessible labels or binding attributes.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 2: Define the translation unit
Group each sentence with its surrounding context, related controls and inline elements. Do not confuse an extraction row with a complete linguistic unit.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 3: List protected values
Identify technical keys, commands, product identifiers and other externally defined strings. Give a reason and an owner for each protection decision.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 4: Read effective ITS rules
Review local annotations and global selectors; verify tool support and rule resolution. An apparently present rule is not necessarily applied by every pipeline.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 5: Collect localization notes
Read note text and linked resources, resolve ambiguous verbs and names, and record questions that an editor must answer before drafting.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 6: Assess language and locale
Identify the source language and target languages; separately evaluate any market-specific scope and locale filter decisions.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 7: Translate meaning in context
Draft fluent target-language sentences without touching protected identities. Preserve user intention, required specificity and grammar appropriate to the target language.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 8: Reattach inline structures
Reintroduce emphasis, links, codes and variables carefully. Allow language-appropriate sentence order without breaking element ownership or resource destinations.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 9: Check terminology and domain
Validate defined terms against the relevant concept and subject area, rather than imposing a translation on every instance of a familiar word.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 10: Run automated structural checks
Compare keys, code fragments, placeholders, element counts and rule-coverage reports. Flag unexpected changes for a person to review.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 11: Review the rendered experience
Open the localized page or app, complete the action, inspect responsive layouts, keyboard navigation and accessible names.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Step 12: Release with traceability
Record the reviewed file version, approver, unresolved limitations, references and post-release correction route so future updates do not silently discard the decisions.
A useful acceptance test is to show the source fragment, the target fragment and a one-sentence account of what stayed invariant. If someone cannot tell whether a changed token is a translated label or an altered machine value, the handoff is incomplete. For decide what in an HTML or XML document is translatable, preserve structural markup, and deliver a valid localized version, write the expected result before running a tool, retain evidence when an automated check fails, and separate changes in language from changes in document behavior.
Worked examples: selective translation in real document situations
Worked example 1: Protected brand inside sentence
Source situation: An online guide says ‘Use the BeaconX console to reset your password.’ The product name is a brand, not an ordinary adjective.
An unreliable approach: Replacing BeaconX with a locally meaningful phrase would create a product that does not exist. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Translate the instruction naturally while keeping BeaconX byte-for-byte unless the brand owner supplies an approved localized name. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Check the source and target for exact product tokens, then ask a first-time reader to identify the action. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 2: HTML translate=no span
Source situation: A help page contains a sentence and a nested span marked translate=’no’ for the label printed on a physical device.
An unreliable approach: Translating every visible word could make on-screen instructions disagree with the physical button. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Translate the surrounding sentence and preserve the marked label, even when the grammar needs restructuring around it. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Inspect the DOM and verify the physical label matches the output rather than relying on screenshots alone. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 3: Nested override
Source situation: A paragraph is generally excluded, but its child includes a support sentence explicitly marked for translation.
An unreliable approach: One blanket rule can mistakenly suppress the child or expose unrelated internal values. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Resolve the effective category using the relevant ITS processing and inheritance rules, then localize only the authorized child. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Review effective translation states at each node and compare a target-language render. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 4: XML attribute versus text
Source situation: An XML element stores a display label and a machine-readable key such as action_id.
An unreliable approach: The key may look like English but is a stable connector; changing it breaks lookups. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Make text and attribute translation decisions separately. Treat machine IDs as protected unless a format explicitly defines a translatable attribute. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Run a structural diff for keys and compare the visible label in the interface. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 5: Localization note on a short string
Source situation: A standalone ‘Open’ appears on a button for opening a file, but a translator might interpret the adjective.
An unreliable approach: Choosing the adjective form can create a fluent yet functionally misleading button. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Carry a localization note that specifies ‘imperative verb; opens selected file’ and confirm button width in the target layout. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Test the localized button by completing the actual file-opening task. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 6: No-note ambiguity
Source situation: A game displays ‘Charge’ in a menu. It could be a payment, attack, power-up or electrical action.
An unreliable approach: A translation memory may pick a popular sense without enough interface context. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Request a screenshot, feature owner definition, or task description, then add a reusable localization note for the approved sense. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Ask a bilingual tester to state what action the player expects before and after tapping. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 7: Inline emphasis as text
Source situation: A warning includes an emphasized word inside a sentence rather than a separate paragraph.
An unreliable approach: Extraction tools that split at every element produce fragments with broken grammar. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Treat within-text elements as part of the same linguistic flow when their role is inline; maintain their positions or legitimate repositioning. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Read the translated full sentence aloud and inspect emphasis in the final renderer. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 8: Code element in tutorial
Source situation: A web lesson says ‘Type reset –all and press Enter’, with the command shown as code.
An unreliable approach: Translating the command’s English-looking tokens makes the lesson impossible to follow. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Keep executable commands intact while adapting surrounding teaching text and any genuinely translatable explanatory labels. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Copy the command from the localized page into a safe test environment and check exact characters. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 9: Link text and destination
Source situation: A navigation link is labeled ‘Read the safety rules’ and points to a canonical manual URL.
An unreliable approach: A translator may alter the URL path or leave the link text untranslated. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Translate the visible accessible link label, preserve the real target URL unless there is an approved locale-specific destination, and test the destination. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Confirm the label’s promise matches the resource delivered by the link. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 10: Placeholder inside string
Source situation: A notification says ‘Hello, {first_name}. Your order {order_id} is ready.’
An unreliable approach: Changing a placeholder or its braces can produce unresolved variables in production. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Protect placeholder names, reorder sentence constituents as grammar requires, and preserve the runtime’s interpolation syntax. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Test at least a short and long example name and a realistic order code. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 11: Terminology without overlocking
Source situation: A university site uses a defined term for an academic programme and also uses the same ordinary word casually.
An unreliable approach: Locking every appearance of a word can force the formal term into ordinary prose. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Use terminology annotations where a concept is genuinely designated, and leave ordinary language free to vary appropriately. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Check all highlighted term occurrences against context rather than performing indiscriminate search-and-replace. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 12: Domain in a mixed page
Source situation: A page pairs clinical instructions with general customer-support copy.
An unreliable approach: The same English word can denote a clinical measurement in one section and a casual description in another. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Carry domain context to the section where it applies and avoid propagating a specialist rendering across unrelated text. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Ask domain reviewers to validate the specialized section and general-language reviewers to assess the rest. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 13: Language identification
Source situation: A multilingual quotation appears inside an English article, with short phrases already in another language.
An unreliable approach: Automatic language detection may attempt to translate or spell-check every span incorrectly. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Keep the original quotation where intended, declare its language accurately, and translate only when editorial intent demands it. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Inspect screen-reader pronunciation and language metadata without claiming those checks replace human review. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 14: Locale filter
Source situation: A page contains country-specific legal information intended only for a subset of target markets.
An unreliable approach: Translating a notice for every market may falsely imply that it applies everywhere. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Use locale filtering and editorial market scoping so excluded material is not presented as applicable in a wrong jurisdiction. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Compare the release matrix by locale and ensure omission is a planned content decision, not a missing translation. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 15: Provenance and machine translation
Source situation: Machine translation creates a draft for a support page with several protected terms.
An unreliable approach: A seemingly high-quality output may hide the fact that no qualified reviewer checked the content. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Keep available provenance or review metadata connected to the translated segment and require a named review stage. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Compare source, machine suggestion, reviewer decision and published wording in a traceable record. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 16: Whitespace and inline punctuation
Source situation: An XML fragment puts a punctuation mark next to a nested emphasized phrase.
An unreliable approach: Moving spaces blindly may yield doubled punctuation or a missing word boundary. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Treat the sentence as a linguistic unit while preserving markup validity and checking the target language’s punctuation conventions. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Render at mobile and desktop widths and check copy-paste text as well as appearance. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 17: Accessibility labels
Source situation: An icon button has an accessible label that is not visibly displayed in the main text.
An unreliable approach: A visual-only review can miss the entire phrase and leave assistive users with an English instruction. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Determine whether the format exposes a translatable accessible label, localize its meaningful text, and keep programmatic identities stable. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Navigate by keyboard and inspect accessible names in the target language. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Worked example 18: Fallback after rule failure
Source situation: An extraction pipeline does not understand a particular global ITS rule but continues silently.
An unreliable approach: Strings intended to be protected may enter translation with no warning, or required copy may be skipped. This can pass a superficial fluency check because the target sentence may sound natural while the underlying instruction or data relationship is no longer true. Before rewriting it, identify the exact boundary between a reader-facing word and a string with an external or structural role.
Safer treatment: Fail visibly when a required ITS rule cannot be interpreted; isolate affected sections and route them for review. The reason this matters is that a localization decision must remain defensible after the translator has forgotten the original screen. Record which tokens were deliberately left unchanged, which were interpreted using context, and who owns any exceptional naming decision. A future editor should be able to recreate that judgment without guessing.
Proof and transfer: Compare effective annotation reports and do not publish merely because the document still parses. Now apply the same question to a different language and a different screen size. Does the translated version still tell the intended person what to do, and will the underlying application still recognize every preserved value? If either answer is uncertain, return the fragment to review rather than silently marking it complete.
Failure modes, diagnostic questions and repairs
1. Everything was translated
Symptom: The author forgot protected text or extraction ignored rules. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Compare immutable tokens against source; isolate changed keys, restore them and verify the real parser. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
2. Nothing was translated in a subsection
Symptom: An inherited exclusion or overbroad selector suppressed useful copy. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Inspect effective rule decisions and refine the markup or selector coverage before re-export. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
3. A button is fluent but misleading
Symptom: An ambiguous short string lacked action context. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Provide a localization note with the button’s real effect, then retest the flow. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
4. Punctuation breaks across a link
Symptom: Inline material was segmented and reassembled mechanically. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Review the full sentence in rendered context, not isolated extraction units. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
5. An accessible name remains untranslated
Symptom: Visual QA never inspected nonvisible labels. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Include accessibility attributes in the localization inventory and validate with assistive testing. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
6. A brand becomes a common noun
Symptom: No approved naming rule reached the translator. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Mark the brand and give a style decision and an escalation contact. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
7. A country-specific notice appears worldwide
Symptom: Market scope was confused with language. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Validate locale filtering and editorial applicability independently of text quality. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
8. An unsupported rule was ignored
Symptom: The tool chain parsed markup but lacked complete ITS handling. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Run a capability test and stop on unsupported critical annotations. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
9. A placeholder is changed
Symptom: The translator mistook variable syntax for prose. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Protect and compare tokens, then test interpolation with representative data. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
10. A reviewer signs off on screenshots only
Symptom: The structured source was not checked. The first diagnostic question is whether the problem arises from source authoring, extraction, translation choice or the final renderer. Do not repair a wrong source annotation by simply tweaking the final sentence; the error will return on the next import.
Correction: Require both structural and in-context acceptance evidence. After repair, repeat a test that would have failed before, and keep the outcome with the localized release. A check that merely reports ‘reviewed’ is weaker than a check naming the actual preserved values and the real reader task.
Practice and transfer: solve before reading the model reasoning
Practice 1
A card shows ‘Current’ as a heading for a live electrical measurement. What should its localization note say?
Model reasoning: Specify that ‘current’ names electrical current rather than ‘present time’; identify the unit and interface context. Preserve sensor keys and units even when the natural-language label changes. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 2
A warning contains a serial number in bold. Is the bold text necessarily translatable?
Model reasoning: No. Formatting does not decide translation status. Protect the serial number because it is identity-bearing data, keep the emphasis, and translate only the surrounding explanation. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 3
A help site has a main translation rule and an exception on one nested element. What is the safe check?
Model reasoning: Inspect the effective ITS decision for that element, including the actual processor’s rule resolution, then review the full output rather than treating the parent as the only authority. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 4
A field named user_token is displayed in a tutorial. Can it be rewritten as ‘user code’?
Model reasoning: The descriptive prose may use ‘user code’, but the literal field name should remain user_token when it identifies a real key. Confirm with the source format before replacing characters. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 5
A button ‘Save’ is localized as a noun. What additional information solves the ambiguity?
Model reasoning: Add a note describing the imperative action and the object that is saved. Test the target string within its neighboring controls and the complete save flow. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 6
A translator wants to move an inline link into an entirely different sentence. When is that acceptable?
Model reasoning: Only when the restructured target still links the same relevant phrase to the intended destination and preserves the needed inline structure. Test navigation and accessible names. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 7
A product has a marketing name and a model code. Should both be protected identically?
Model reasoning: Not necessarily. The model code is usually invariant; the name follows approved brand localization policy. Record separate decisions, owners and fallback instructions. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Practice 8
An extraction export lists 300 source strings with no context. What is the first quality improvement?
Model reasoning: Attach context: location, screenshots or DOM path, language, effective translate status, key, intended action and localization notes. A longer string list without those attributes is still unreliable. The final step is to say what evidence would disprove the choice. Test the user-visible result and inspect any identifiers or markup that the surrounding system depends on. If the result works only in a translator’s spreadsheet, but not in the actual page or device, it is not ready for release.
Frequently asked questions
Is ITS 2.0 a machine translation engine?
No. It is a standards-based way to communicate internationalization and localization information. An engine or translator can use that information, but ITS does not itself produce a translation.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Does translate=’no’ mean readers should never see that text?
No. It means the identified content is not intended for translation in that context. Visibility, accessibility and authorization are different questions.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Can a brand name ever have a translated form?
Yes, if the brand owner approves it for the relevant locale. A protected default does not outrank a documented naming decision; it forces the decision to be deliberate.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Are global rules safer than local annotations?
Neither is automatically safer. Global rules scale across repeated structures; local annotations explain exceptions at the source. Effective precedence, coverage and review matter.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Can ITS protect placeholders in every tool?
Only when the extraction and localization systems interpret the relevant rules and retain the protected content. Check actual tool support, not the existence of a standards label.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Should every short word carry a localization note?
No. Prioritize genuinely ambiguous or consequential strings. Excessive notes can obscure critical instructions; notes should be concise enough to use.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
What is the fastest beginner check?
List user-visible text, immutable tokens, links, accessible labels and annotated exceptions. Produce one target page and test those five categories against the source.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Can I use ITS for a PDF without structured source files?
ITS is most directly useful where supported structured content and tools can carry its annotations. A flat scanned PDF first needs a reliable content extraction and localization workflow.
In practice, this answer should be applied at the level of the individual document and the localization system in use. The responsible decision is the one that preserves the reader’s intended action and the source’s technical contract, and can be checked using visible evidence rather than confidence alone.
Next learning routes and primary sources
This ITS guide owns the decision about which XML and HTML content should be translated and how contextual notes travel with that decision. For broader English meaning and sentence control, visit the eduKateSG How English Works branch. For growing accurate word knowledge, use the Vocabulary Learning Hub. The existing Top Ways to Translate Correctly family covers idioms, tone and register, natural meaning, and terminology; those subjects should not be recast here as if this were their canonical home.
Vocabulary Learning Hub · How English Works · W3C ITS 2.0 Recommendation and data categories · Google Search Central: people-first content
Educational scope note: examples are synthetic. Verify any production interpretation of an ITS feature against the normative W3C specification and the capabilities of the actual extraction, translation and publishing tools. This article is not a certification test for an ITS implementation.
Related translation-series reading
Dublin Core metadata and identifiers · Markdown documentation and code fences · SVG accessible titles and descriptions
