VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Top Ways to Translate Correctly | DITA 1.3 Topicrefs, Conrefs and Keyrefs

To translate DITA 1.3 technical documentation correctly, translate the human-facing instructions and explanatory content in DITA topics while preserving topic IDs, map references, content-reuse relationships, keys, filtering attributes and links that make a documentation set build correctly. This guide explains DITA translation, topicrefs, conrefs, keyrefs, xml:lang, conditional publishing and technical-documentation QA. The target is a coherent manual that leads readers through the same correct task, not a set of individually elegant paragraphs with broken references.

A translator can make a DITA topic sound natural and still ruin the manual by translating a topic ID, altering a conref path or changing the product value of a conditional attribute. Reused warnings may vanish from some outputs while working in another, and an xref can display the wrong topic title. The root problem is that DITA is both language and a publishing graph. Translating the words is necessary, but maintaining the graph is equally necessary.

Quick answer: Keep structural IDs stable, translate readable topic content, preserve map links, resolve reused material, protect keys and conditions, verify language properties and nontranslatable terms, build each delivery variant and test real user tasks.

  • Confirm the audience, source edition, target locale and actual user task.
  • Separate human-language content from technical identifiers, references and control data.
  • Draft natural and precise target text, preserving original decisions and constraints.
  • Validate the file structure and test its actual reader-facing behavior.
  • Keep an evidence trail and review every final deliverable after export.

The visible problem and the canonical job of this guide

This article owns DITA 1.3 topic and map localization. It is not a general software string guide and does not explain XLIFF interchange in place of DITA source semantics; the central job here is to preserve reusable technical-documentation relationships.

A serious translation starts with the question what must the reader or user be able to do after receiving this target-language resource? When a text carries instructions, timing, references or accessible structure, a correct answer needs two kinds of evidence: meaning has survived, and the structure delivering that meaning still works. This principle explains why proofreading a bilingual spreadsheet is useful but insufficient. Reviewers must also observe the final context, because a polished translation can be attached to the wrong action, screen, sequence or resource.

Treat every translation decision as an accountable mapping from a source claim and its context to a target expression. Keep a record of uncertainty, preserve identifiers that act as addresses rather than words, and test the consequences of any permitted reordering. Readers should never have to reverse-engineer the original English to discover what a translated button, caption, PDF passage or manual step really requires. A strong version remains understandable when encountered independently in its intended language.

First principles: what must not get lost

1. Topic structure carries purpose

DITA separates task, concept and reference content so readers can find instructions and supporting explanations predictably. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A task step must remain an executable instruction, not become a descriptive slogan. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Confirm the translated topic still answers its original user question. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

2. IDs are link targets

A topic ID identifies content for references and reuse; it is not a headline that should be translated freely. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: The identifier install_setup may be used by several maps and cross-references. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Resolve all references after translation. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

3. Maps express a reading route

A DITA map organizes a deliverable’s topic structure and navigation rather than simply listing files. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A topic may be reachable in one product manual but excluded from another edition. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Build each intended map and follow its navigation. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

4. Conrefs move content

Content references reuse an element defined elsewhere, creating a dependency that cannot be verified by reading only the local topic. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A safety warning may be reused in five task procedures. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Resolve the referenced text and review all contexts where it appears. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

5. Keys add indirection

Key definitions and keyrefs let maps redirect resources without rewriting every reference in a topic. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: The same help key may point to different product-specific topics in different manuals. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Test key resolution within each publication context. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

6. Conditions select an audience

Product, platform and audience filters determine what content appears in a specific build. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A Windows-only instruction should not appear in a Linux manual just because the translator liked the example. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Compare output variants with the source filter logic. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

7. Language metadata is structural information

xml:lang is a property used by processing and accessibility, not an ordinary phrase for a translator to paraphrase. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A French topic containing an English command name requires careful language handling. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Verify locale declarations and genuine language switches. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

8. Commands are not all prose

UI labels are translatable when localized in the product, but commands, code, paths and identifiers may need exact preservation. This distinction matters because a translation is not an isolated sequence of dictionary equivalents: it is a decision about what a person must understand while interacting with a structured artifact. When the linguistic and functional layers are confused, the work can pass a superficial text review while still withholding essential meaning from its audience.

Illustration: A command line option named –force must not change merely because it resembles an English word. The crucial question is which part of the artifact represents user-visible meaning, which part establishes a relationship between resources, and which part records instructions to software or an accessibility tool. Each type calls for a different editing rule; none should be guessed from its visual appearance alone.

Independent check: Execute or inspect each instruction in its intended environment. Have someone who did not translate the text repeat the test. Ask them to identify the intended message and expected outcome before telling them what the source meant. This separates true target-language comprehension from a reviewer who unconsciously repairs gaps using knowledge of the original.

A repeatable twelve-stage translation and QA method

Apply the following method in order. Each stage creates a concrete output or question for the next stage, so that a successful translation is reproducible instead of dependent on the memory of one editor. For high-consequence or widely reused material, keep a short review log identifying the relevant source, decision, reviewer and final build. The process may be shortened for a tiny project, but its checks should not be silently skipped.

Stage 1: Identify the publication set

Inventory source topics, DITA maps, output formats, locale variants and product/platform conditions before translation. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: One shared topic might appear in many user guides. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Record all intended publication contexts and owners. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 2: Archive the baseline

Save the source DITA package, associated images and a known-good output build. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A missing graphic can masquerade as a translation problem after export. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Preserve reproducible build inputs and tool versions. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 3: Map references

List topic IDs, topicrefs, xrefs, keys, conrefs and conkeyrefs, including transitive dependencies. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A reused note can be defined in another folder entirely. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Produce a dependency inventory for high-risk content. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 4: Define protected material

Identify code, identifiers, command names, product values and paths that must not be translated. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A configuration key in a prose paragraph is still an exact machine value. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Confirm this list with technical owners. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 5: Read each task in context

Understand the user’s starting state, expected action, outcome and target audience for each procedure. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: Reset can mean clearing a filter or wiping a device. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Reconstruct the action path before editing wording. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 6: Translate semantic content

Produce natural target-language headings, steps, descriptions and warnings without changing conditions or results. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: An instruction must preserve prerequisites and negative conditions. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Ask a native-language tester to perform the procedure. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 7: Protect reuse markup

Preserve conref and related reference syntax, verify the resolved source content and translate reusable fragments consistently. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A referenced warning can have several usage contexts. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Render every reuse point and inspect its complete sentence. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 8: Preserve navigation relationships

Keep map targets, keyrefs and link identities while adapting truly reader-facing navigation titles. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A topic title and map navtitle can differ intentionally. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Confirm links lead to the correct translated sections. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 9: Reconcile conditions

Preserve filtering values and confirm that source and target editions include the intended product/platform material. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A translated manual can omit an entire branch because an attribute changed. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Compare conditional-build inventories. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 10: Set language correctly

Update translation language declarations according to the publishing workflow and mark true language switches. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A target manual might include unchanged English command tokens. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Validate language metadata in generated outputs. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 11: Build and validate

Parse the XML, run the DITA publishing pipeline and check missing resource references, duplicate IDs and unwanted content. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: An XML file that parses individually may still fail when resolved through a map. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Build every supported publication variant. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Stage 12: Review task success

Have a user follow translated instructions on a safe test system, record ambiguities and verify final navigation and deliverables. In practice, begin with a small representative example rather than changing the whole corpus. Record the expected reader action or interpretation in one plain sentence, and mark any point where the target edition changes the representation or layout. That sentence becomes the test oracle when reviewers compare source and target later.

Worked checkpoint: A perfect XML build can still contain a wrong procedural order. A reviewer who knows the target language should explain what the translated content now communicates, while a technical reviewer confirms that protected structures still resolve. These are separate responsibilities. If either reviewer needs to invent missing context to justify an answer, the item is not yet ready for release.

Acceptance evidence: Test the reader’s actual task and release the validated artifacts. Document a pass, a specific defect or an unresolved question. Avoid calling a file complete merely because every segment contains target text; completion means that meaningful output has been observed in a real delivery condition.

Sixteen worked examples with corrections and transfer tests

These examples are teaching cases, not claims that every tool implements each optional feature identically. They illustrate how the translator can locate an actual failure mechanism, make a bounded correction and test whether the correction changes a reader’s outcome. Use real source assets when practising. Any fictional resource name, sample person or model identifier here is illustrative rather than a standardized value.

Case 1: Topic ID looks like English

Source situation. A concept topic uses the ID replace_filter and appears in a map. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating replace_filter as a readable label makes the map’s reference point disappear. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve the ID while translating the visible topic title and explanation. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Resolve the map and follow its topic link. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 2: A map with several targets

Source situation. A map references a safety overview followed by installation and maintenance topics. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating file paths or changing hierarchy can cause missing pages in the finished manual. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Keep topicref targets and order unless a documented localization design change is authorized. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Build and navigate the entire target map. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 3: A shared warning in multiple tasks

Source situation. A warning about disconnecting power is reused with a conref in several procedures. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Editing only the local visible reference without the shared source leaves a mixture of languages. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Translate the authoritative reused element and examine its appearance in every importing task. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Verify all outputs display the same safety action. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 4: A keyref to a product help page

Source situation. An xref uses a key that resolves differently for two hardware models. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Replacing the key with a hardcoded path sends one model’s readers to the wrong page. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve key indirection and translate any reader-facing link text under the map context. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Build each hardware edition and click the link. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 5: A conkeyref fragment

Source situation. A message includes reused content resolved via a map-defined key and fragment identifier. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating the fragment ID makes the reference unresolved despite correct surrounding prose. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Keep reference identities stable and localize the referenced content through its source. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Check resolution with a strict publication build. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 6: An operating-system filter

Source situation. A task contains platform-specific Windows and macOS steps selected by attributes. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating the attribute value as ordinary wording changes which step set is selected. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve filter values and translate only the instructions shown for each platform. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Compare platform builds side by side. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 7: A UI control label

Source situation. An instruction says Click the Export button, but the product has different names in different locales. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Literal translation of Export differs from the actual localized UI label and confuses users. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Reference the approved product localization and preserve exact control labels for the target UI. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Perform the step using the localized product. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 8: A command-line option

Source situation. A command example contains –output and a file extension. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating the option name produces a command that does not run. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Keep machine-executable syntax intact while translating the explanatory sentence and supported sample values only. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Run the command safely in a test environment. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 9: A version-specific note

Source situation. A release note states a feature is unavailable before version 5.2. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating until as after reverses the version condition and suggests an unsupported operation. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve the chronology and exact version identifier in natural target language. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Compare behavior across the documented versions. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 10: A localized image

Source situation. A screenshot contains UI labels in the source language and appears in a translated task. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. The text instructs users to find a target-language label that is absent from the screenshot. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Replace the screenshot with a correct localized capture or explain the mismatch transparently. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Have a reader locate every depicted control. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 11: A target-language note

Source situation. An XML note provides context to translators but is not intended to appear in the publication. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating and inserting the note into task prose exposes workflow information to readers. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Distinguish editorial metadata from published content and keep it in the correct place. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Inspect the generated document for accidental notes. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 12: An XML language property

Source situation. A target topic is translated into Spanish but still declares the source document language. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Publishing or assistive systems may choose the wrong voice or metadata language. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Set appropriate language properties in the locale packaging and identify genuine unchanged passages. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Check the generated HTML or PDF language information. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 13: A procedure with alternatives

Source situation. The task says to choose either Ethernet or Wi-Fi setup, not both. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. A vague target conjunction turns an exclusive choice into a requirement to perform both procedures. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve logical branches and decision criteria when rewriting the steps. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Ask a user to explain which branch they would follow. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 14: An xref with changing title

Source situation. A destination topic is renamed in the translated edition and an xref uses generated link text. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Hardcoding an old English title in the source reference creates inconsistent navigation. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Use DITA-generated references where appropriate or update visible linked text consistently. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Verify source and destination names across output formats. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 15: A term protected by translate no

Source situation. A product’s trademark is intentionally nontranslatable in a reusable phrase. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. Translating the protected token destroys brand identity and can break external recognition. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve the protected span while adapting grammar around it; consult product naming policy. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Inspect all branded occurrences in target deliverables. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Case 16: A publication with duplicate topics

Source situation. One map includes the same reusable concept under two parent branches for different readers. Before translating, identify the complete context in which this item is encountered. The same words can carry different instructions when they occur beside a control, inside a reference, under a figure or within timed media. The source situation is the evidence that justifies the target wording.

Tempting but incorrect move. A translator assumes one occurrence is accidental and deletes it from the map. The mistake is attractive because it may sound fluent or preserve a familiar word pattern. However, the reader does not benefit from fluency that changes the permitted action, removes a relationship or makes relevant information undiscoverable. Compare the intended outcome, not just the visible strings.

Better translation decision. Preserve intentional reuse and test that navigation context remains appropriate under each branch. Translate the reader-facing layer with an appropriate target-language form. Keep technical material stable unless its governing specification and project workflow authorize a coordinated change. Where the artifact mixes both layers, make the boundary explicit in a translator note or review record rather than silently deciding alone.

How to prove it worked. Review the two access paths independently. Repeat the scenario with different input values, output sizes or users where those factors can change the result. Ask a target-language reviewer to say what they think will happen before acting. A correction is defensible when the same content produces the intended decision and the underlying system remains functional.

Ten failure modes and their repairs

A failure mode is a repeatable route from an apparently harmless editing decision to a communication defect. Fix the mechanism rather than patching one example. The questions below are suitable for a reviewer checklist, classroom discussion or a localization team’s defect taxonomy.

1. Translated topic ID

Symptom: The target’s ID no longer matches references used by maps. Repair: Restore stable identifiers and validate dependencies. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

2. Conref silently unresolved

Symptom: A reused fragment is missing even though the local topic parses. Repair: Resolve all content references during a full build. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

3. Keyref flattened

Symptom: A map-specific key is replaced with one hardcoded destination. Repair: Restore key indirection and test each map variant. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

4. Product filter changed

Symptom: A platform or product attribute is translated like prose. Repair: Restore source filter values and compare generated edition inventories. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

5. Command localized

Symptom: A command line flag is altered to sound natural in the target language. Repair: Preserve executable tokens and run the instruction safely. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

6. Warning context lost

Symptom: A reused safety note becomes grammatical only in one of several placements. Repair: Review all reuse contexts and adapt the shared fragment appropriately. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

7. Language declaration stale

Symptom: The target edition declares the source language. Repair: Correct locale metadata and test output. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

8. Map navigation unreviewed

Symptom: The translated topics are good but their navigation titles are inconsistent. Repair: Verify all map-generated routes. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

9. Image remains source-language

Symptom: Screenshots contradict the localized instructions. Repair: Provide suitable localized captures or precise explanations. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

10. XML-only validation

Symptom: A single topic parses, yet the full documentation build contains missing references. Repair: Run complete builds for every supported delivery profile. Reproduce the problem using the smallest real example that still fails, then verify the repair on the full deliverable. The translator should state what meaning was at risk; the technical reviewer should state what observable artifact or process now confirms the fix.

For transfer, imagine that the same source material is republished for a second language, device or audience. Would the repair still protect the intended relationship? If not, refine the workflow rule and document the dependency. A strong repair scales to the next similar occurrence without assuming that every sentence will happen to use the same word order or layout.

Practice: twelve checks you can perform on your own material

Exercise 1: Interpretation

Find one phrase whose meaning depends on neighboring content, and write the missing context before translating it. Use Topic ID looks like English as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Preserve the ID while translating the visible topic title and explanation. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Resolve the map and follow its topic link.

Exercise 2: Structure

Identify three strings or labels that look translatable but actually act as technical keys, file references or protected data. Use A map with several targets as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Keep topicref targets and order unless a documented localization design change is authorized. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Build and navigate the entire target map.

Exercise 3: Release evidence

Rewrite a long sentence into natural target-language phrasing without removing a condition, limitation or intended user action. Use A shared warning in multiple tasks as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Translate the authoritative reused element and examine its appearance in every importing task. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Verify all outputs display the same safety action.

Exercise 4: Interpretation

Locate a structured item whose visible text differs from its underlying programmatic identifier. Use A keyref to a product help page as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Preserve key indirection and translate any reader-facing link text under the map context. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Build each hardware edition and click the link.

Exercise 5: Structure

Check whether a source-language assumption about singular, plural or word order survives target-language grammar. Use A conkeyref fragment as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Keep reference identities stable and localize the referenced content through its source. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Check resolution with a strict publication build.

Exercise 6: Release evidence

Ask a native-language reviewer to explain the text without seeing the source; record any uncertainty they report. Use An operating-system filter as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Preserve filter values and translate only the instructions shown for each platform. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Compare platform builds side by side.

Exercise 7: Interpretation

Compare a successful-looking text export to the actual rendered deliverable and identify one nonlinguistic risk. Use A UI control label as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Reference the approved product localization and preserve exact control labels for the target UI. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Perform the step using the localized product.

Exercise 8: Structure

Repeat the same test with an unusually long target string and observe whether comprehension or behavior changes. Use A command-line option as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Keep machine-executable syntax intact while translating the explanatory sentence and supported sample values only. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Run the command safely in a test environment.

Exercise 9: Release evidence

Verify that a help link, reference, timestamp or navigation destination still points to the right place. Use A version-specific note as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Preserve the chronology and exact version identifier in natural target language. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Compare behavior across the documented versions.

Exercise 10: Interpretation

Find a passage that includes a genuine language switch and decide which layer should describe the change. Use A localized image as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Replace the screenshot with a correct localized capture or explain the mismatch transparently. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Have a reader locate every depicted control.

Exercise 11: Structure

Create an explicit defect report that contains a source, observed result, expected result and reproducible steps. Use A target-language note as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Distinguish editorial metadata from published content and keep it in the correct place. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Inspect the generated document for accidental notes.

Exercise 12: Release evidence

Run a final release rehearsal with an independent reader, then record which evidence would justify publication. Use An XML language property as an optional starting point. Begin by writing down what the original reader needed to know or do. Separate facts given in the source from assumptions about its surrounding product or publication. This matters because an apparently successful translation can conceal an unexamined guess.

Model reasoning: Set appropriate language properties in the locale packaging and identify genuine unchanged passages. Your answer should show why the chosen translation preserves the message, which surrounding structure remains untouched, and what test would expose a failure. An acceptable response is not necessarily identical in wording to another student’s version; it must be defensible against the actual source and use case. Check the generated HTML or PDF language information.

How to score a finished translation

Use five dimensions, each scored from zero to two: semantic accuracy, target-language clarity, structural integrity, accessibility or usability, and release traceability. A zero means absent or wrong; one means partly demonstrated or dependent on inference; two means independently demonstrated. The ten-point total is a teaching aid, not a formal certification. A serious structural or safety defect cannot be offset by perfect style in another category.

For semantic accuracy, compare the decisions a reader can make; for clarity, test reading without source-language support; for structure, validate the actual files and relationships; for accessibility, try nonvisual or constrained devices as appropriate; for traceability, identify the source version and review evidence. If one dimension fails, repair it and rerun dependent tests. A changed translation may alter length, placement, pronunciation, or link context, so an old pass is not automatically current evidence.

Frequently asked questions

What is DITA localization?

It is translation of reader-facing topic content while retaining the XML semantics and publishing relationships that generate technical manuals and help systems. It includes language quality, data preservation and build testing. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

Should I translate topic IDs?

Generally not. Topic IDs anchor references and reuse. Translate visible headings and explanations instead, unless a coordinated technical migration updates every dependent reference. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

What is a topicref?

It is a map-level reference that helps determine publication structure and navigation. A translated edition must preserve correct targets and meaning in reader-facing labels. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

How is a conref different from a keyref?

A conref is content reuse from another element; keyref uses a key defined in a map to resolve a resource or link. Both create dependencies that need contextual QA. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

Can I change conditional attributes to the target language?

Do not treat product, platform or audience filter values as ordinary prose. They control build selection and should change only as part of a deliberate, tested configuration migration. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

What if a DITA topic is reused in several manuals?

Review the shared translation in every important output context. A sentence that reads naturally in one manual may have unclear references in another. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

Do I translate UI labels in a procedure?

Align them with the actual localized product interface. Human-facing labels are generally translated, while command names and machine identifiers may remain fixed. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

What does xml:lang do?

It declares natural-language context used by processing and accessibility systems. Ensure the localized content and output metadata accurately describe the language edition. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

How can I tell if a translation broke a manual?

Build the relevant maps and output variants, check reference resolution and navigation, then have users perform the translated procedures. A parser alone is not enough. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

Is DITA XML the same as XLIFF?

No. DITA represents structured publication content and reuse; XLIFF is a localization interchange format. A pipeline may involve both, but they have different canonical functions. The practical way to decide is to start from the user outcome and then identify the relevant format or workflow constraint. Check that constraint independently of spelling and fluency. When project-specific conventions differ, record the convention and test it on the final deliverable instead of assuming one vendor’s preview is universal.

Sources, related lessons and what to read next

Technical authority: OASIS DITA 1.3 technical-content specification. Use the applicable published specification and verify the version supported by your authoring and delivery tools. Where this guide offers an example or a practical house rule, do not mistake it for an additional requirement imposed by the formal standard.

The next useful move is to choose one representative source resource, translate it using the twelve stages, collect a small set of negative test cases and run the finished artifact through an independent reader review. If the text is accurate but the document or system fails, treat the defect as a translation delivery failure, not as a cosmetic issue. If the file passes technical validation but the reader misunderstands the task, treat it as a language failure. Both are correctable through a repeatable process.