DITA Open Toolkit, often called DITA-OT, is a command-line publishing system for structured DITA documentation. A translation team uses it to build target-language HTML5 help and PDFs from approved DITA maps and topics while preserving reusable content, keys, references, warnings and document navigation. This DITA-OT CLI tutorial explains the practical multilingual publishing workflow, including xml:lang, generated text, right-to-left documents, topic reuse, HTML output, PDF output and release-quality validation.
The difficult part of multilingual DITA documentation is not simply converting XML files into a website. One instruction may be reused in several product manuals; a map may supply navigation labels, keys and conditional content; and the publishing toolkit may generate phrases that do not appear in the source files. A document can build successfully while showing the wrong locale, an untranslated label, a misresolved conref or an instruction that belongs to another product variant.
A reliable workflow begins by identifying the controlled source edition and target DITA map, validating the localized topic set, running the dita command for a small representative HTML5 build, checking references and generated labels, repeating the required output transformations and reviewing the actual files with subject specialists. This guide treats DITA-OT as a publisher, not an automatic translator, and separates technical validation from linguistic and safety approval.
Quick answers for DITA-OT publishing
- Use
dita --input=manual.ditamap --format=html5for a basic HTML5 transformation, then specify an output directory for real projects. - For a PDF proof use the supported
pdftransformation and the approved PDF configuration. - The DITA map, reusable references, generated terms and output language all require inspection.
- Validate each language and required product variant separately.
- Preserve a record of the actual output files approved for publication.
Illustrative publishing commands
dita --help
dita --input=manual-fr.ditamap --format=html5 --output=build/fr-html
dita --input=manual-fr.ditamap --format=pdf --output=build/fr-pdfThese examples assume a supported DITA-OT installation and a correctly configured DITA map. The exact directory, fonts, plug-ins and flags depend on the organization’s setup and tool release. Check the current DITA-OT command documentation before substituting build parameters.
1. Know the source authority
A multilingual DITA build needs a controlled source edition and an approved target-language translation. Output transforms cannot establish whether the underlying instructions are authorized. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A new equipment version supersedes an older emergency-stop procedure, but the translated topics still reference the previous release. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Record product version, approved DITA map, target locale, source revision and sign-off roles before building. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Every topic included in the release belongs to the intended product and revision. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A successful transform of stale content can publish dangerous instructions. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
2. Differentiate topics from maps
Topics contain modular information; maps assemble that information, define hierarchy and can assign keys and metadata. A translated map is not just a container for translated paragraphs. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A maintenance help set has correct Spanish task topics but English navigation titles in the map. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Review the map and its topic references separately, including localized titles, metadata and hierarchy. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Navigation and topic content present a coherent target-language help experience. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Testing isolated topics alone misses map-level errors. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
3. Use the official command entry point
DITA-OT provides a dita command that takes an input file or map and a transformation format, plus optional build parameters. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A team migrates from an old Ant build and assumes every legacy flag has the same modern syntax. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Start with dita –input=manual.ditamap –format=html5 and check the command help for the installed toolkit version. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The selected input and transform are recorded and their generated output is identifiable. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Avoid inventing new command flags based on similarity to other build tools. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
4. Create separate output folders
Language editions can have identical topic basenames and asset names. Sharing an output directory invites accidental overwrites and false comparisons. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An English HTML build and a German PDF build use the same folder, confusing generated navigation and graphic files. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Use –output with language-specific directories and archive their build manifests separately. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. No release output silently replaces or mixes files from another locale. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Directory separation is a basic content-integrity control, not optional housekeeping. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
5. Understand xml:lang
DITA-OT uses the language context of source content when producing generated text, index sorting and direction decisions. Language declarations need deliberate placement. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A French map points to translated topics but the root map retains English language metadata, producing incorrect generated labels. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Set xml:lang correctly for the map and relevant content in line with supported language rules, then inspect output. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Generated navigation and labels use the intended language as well as the approved text. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A language tag does not itself translate any source string. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
6. Review generated text strings
Toolkit-generated words such as related tasks, chapters and reference labels may originate outside the translated topics. Missing localization can be more visible than missing body prose. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A translated Thai manual shows an English ‘Related concepts’ heading after all topic paragraphs have been reviewed. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Inspect generated labels in HTML and PDF and confirm that installed localization resources cover the target language. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Readers encounter consistent terminology in both handwritten and automatically generated interface text. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Search-and-replace inside topic files cannot correct every toolkit-generated phrase. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
7. Check language support per output
HTML5 and PDF pipelines have different rendering requirements and supported features. The presence of a locale code does not guarantee perfect typography in all outputs. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A multilingual manual builds HTML correctly but its PDF route uses an unsuitable font and wrong line breaking. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Consult the toolkit’s current supported languages and transform documentation for each required output. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Both HTML5 and PDF pass independent script and layout review for the actual market. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Avoid promising identical behavior from different transformations. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
8. Preserve topic identifiers
Topic IDs and reference anchors are structural interfaces. Translating them casually may break links or conref relationships across maps. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A translator renames task_install to its German equivalent and leaves a key reference pointing to the old value. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Keep stable structural identifiers unless there is an agreed migration with updated dependent references. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Every intended link resolves to the correct localized topic or element. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Visible heading translations should not be confused with internal XML identifiers. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
9. Control key references
A keyref abstracts a target and can vary by map or product context. A key name is not necessarily something the translator should modify. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. One key named device-name resolves to the current model in one manual and an older model in another branch. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Test key resolution in the actual publication map and verify the rendered product names and links. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The target content reflects the correct product, version and language context. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A reusable key can propagate a wrong localized term through many pages. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
10. Control conref reuse
A conref reuses content fragments, and its meaning depends on the referenced element and publication context. Translation teams must know what is shared. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A reusable warning paragraph changes in a shared topic, but a localized branch still points to an older text variant. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Inventory conref dependencies, preserve valid targets and inspect all high-risk rendered occurrences. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Every reused warning and instruction displays the approved current text wherever published. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Comparing only a standalone topic can miss the real publication behavior. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
11. Handle conditional processing
DITA can publish different content based on platform, audience, product or other profiling attributes. Wrong filters can expose irrelevant procedures. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A technical manual translated for one regional product accidentally includes instructions for equipment sold only elsewhere. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Document conditional parameters and test each required deliverable configuration with its corresponding audience or product matrix. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The published variant contains exactly the intended instructions and exclusions. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A complete build does not prove that the selected conditions were correct. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
12. Keep structural elements intact
DITA XML uses specialized elements for tasks, steps, notes, code and references. Replacing their markup with decorative HTML or plain text can break semantics. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A translator pastes a formatted list into a task topic and removes the step elements during editing. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Translate eligible human-facing text while preserving the DITA structure and passing schema or grammar validation. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Procedure order, warning semantics and references survive transformation. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A paragraph that looks like a step is not always structurally equivalent to a step. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
13. Protect commands and parameters
Command examples, syntax names, file paths and exact identifiers may need to remain unchanged even when surrounding explanation is localized. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A French network manual translates a literal CLI flag so that copying the example will fail. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Use a do-not-translate inventory for executable tokens and translate only explanatory text unless the software itself has localized syntax. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Commands remain executable and the description accurately explains them in the target language. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Natural-sounding language is not a justification for rewriting literal commands. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
14. Review warning and hazard language
Safety notes require both semantic precision and correct visual emphasis. Conditional reuse makes the consequences of an inaccurate warning larger. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An Arabic service manual places the electrical isolation warning after the repair steps due to a structural edit. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Validate warning reuse, position, target text and layout with a qualified domain and native-language reviewer. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The worker sees the risk and required protective action before encountering the dangerous step. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Do not treat safety notes as generic editorial callouts. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
15. Check translated link text
Links can be assembled by keyrefs or generated labels, and the human-facing description should identify the correct destination. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An Italian manual displays a translated ‘Specifications’ link whose target still leads to an English-only deprecated topic. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Click representative rendered links, confirm language and product context and review automatic link-text generation. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Readers can predict and reach the correct localized resource. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A successful XML parser does not test the practical usefulness of a hyperlink. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
16. Keep image and diagram text aligned
Screenshots and diagrams may contain translatable labels not visible in the DITA text nodes. The topic can appear localized while the visual remains inconsistent. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A translated industrial guide tells a user to press a French-labelled button but its screenshot shows the old English menu. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Inventory image-localized assets and alt text, test the relationship between visual, caption and procedure. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Screenshots correspond to the target interface version and do not contradict instructions. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Replacing the picture without checking its version can create a different mismatch. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
17. Preserve alternative text
Alternative text gives a nonvisual description of meaningful graphics. It must be translated and kept aligned with the actual image used. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An infographic is localized into Chinese while its alt description remains an obsolete English caption. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Review image description elements and relevant metadata for accuracy, brevity and context. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. A screen-reader user obtains the same essential informational purpose as a visual reader. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Machine-generated alt text should not be accepted without human evaluation. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
18. Handle DITA tables
DITA tables and simpletables can contain localized labels and complex numeric data. Narrow PDF layouts especially require intentional review. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A German comparison table increases column widths and clips a safety limit at the right margin. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Test table structures, heading associations and print behavior in each output format; rework design with approval when necessary. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. All values remain connected to their correct labels and readable in the target edition. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Reducing every table font to a tiny size can hide an important data problem. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
19. Review procedures in sequence
A task’s step order, prerequisite and expected result form a logical dependency. Language edits must not inadvertently change what users do first. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A translator moves a prerequisite into an ordinary note and users miss it before a firmware update. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Compare the approved procedural logic and DITA step structure, then test realistic user workflows. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Users can follow each step in the intended order and identify the correct success condition. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Translating each sentence separately may lose how the steps depend on one another. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
20. Inspect generated indexes
Index terms can appear in topics or be generated and sorted by language context. The collation policy affects findability for real readers. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An accented French technical term is filed under the wrong letter after an index-generation change. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Review sample terms with native-language technical experts and verify HTML search and PDF index behavior separately. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Important terms are located under plausible target-language headings and refer to useful pages. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. An index that contains every word can still be frustrating to navigate. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
21. Support bidirectional output
RTL languages require correct document language, direction behavior and mixed-script tests. DITA-OT provides globalization support but renderers and fonts remain relevant. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. An Arabic troubleshooting page includes an English error code and a decimal value that appear in a confusing sequence. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Mark writing direction appropriately in source and review HTML and PDF examples with the target audience. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The logical instruction and mixed-script sequences are unambiguous in both outputs. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Do not insert arbitrary directional characters across the whole file as a blanket workaround. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
22. Review generated TOC and navigation
A map controls much of a help system’s structure. Navigation, breadcrumbs and headings may depend on shared or generated resources. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A Spanish HTML help build has the right pages but a left navigation bar containing source-language names. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Inspect map titles, generated TOC entries, breadcrumbs, navigation order and target-language labels. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Users can find a task from navigation without knowing the source language. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Random spot checks of body paragraphs are insufficient to validate a help website. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
23. Test PDF fonts independently
DITA-OT’s PDF transformation depends on font configuration and document rendering settings. The same source can render differently in HTML and PDF. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A Korean maintenance booklet builds but missing glyph coverage in its PDF font stack makes part numbers hard to distinguish. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Check formatter and font configuration, inspect font inventory and print representative complex-script pages. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. All target-language characters and technical symbols are readable in the actual PDF. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Assuming HTML success proves PDF font readiness is a common release error. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
24. Keep publication versions reproducible
Toolchain version, plug-ins, locale resources and configuration affect the generated output. Teams need a controlled baseline. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A DITA-OT upgrade changes generated string choices and page breaks in a previously approved translated manual. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Record toolkit version, plug-in list, build configuration and source revisions; compare outputs during upgrades. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Changes introduced by the toolchain are visible, reviewable and attributable. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Rebuilding old content with a new toolkit is not proof that it is unchanged. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
25. Validate references automatically
Broken references, missing files and schema errors are easier to catch early through build diagnostics and validation tools. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A reused topic points to an image removed during branch cleanup, leaving an empty space in final HTML. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Capture build warnings and test key or conref targets and referenced assets before releasing deliverables. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. There are no unexplained missing resource or reference problems in the required outputs. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Suppressing build warnings for speed can bury the only evidence of a missing instruction. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
26. Check localization completeness
Coverage measurements can reveal source-language remnants, but they must distinguish legitimate technical names from untranslated prose. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A Polish release includes English source paragraphs inserted through a reused content library. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Compare expected target topic inventory against the built content and inspect flagged English-language remnants in context. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. Every required reader-facing instruction is either appropriately translated or deliberately retained with justification. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A simplistic ‘no English words’ rule wrongly flags product names and commands. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
27. Review output in realistic readers
HTML5 and PDF reach people through different devices and assistive tools. One browser and one desktop PDF viewer are not enough for critical releases. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A multilingual equipment manual looks fine on the author’s laptop but a mobile browser displays a crucial wide table poorly. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Test representative screen sizes, browser navigation and PDF viewers appropriate to the audience. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The user can follow instructions and reach critical information without specialist software. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. A renderer’s success message cannot substitute for end-user inspection. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
28. Establish publication approval
The subject expert, linguistic reviewer and technical publisher may approve different aspects of a release. Their decisions should be traceable. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A team fixes a missing caption in the XML after final approval but distributes the new PDF without any follow-up check. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Record source and target approvals, document technical changes, rerun affected checks and review the final deliverable. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. The distributed HTML and PDF are precisely those approved for release, with exceptions documented. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Earlier approval does not automatically cover later regenerated files. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
29. Archive the build inputs
Long-lived technical documents need a recoverable relationship between translated source, dependencies and output for corrections and audits. The issue becomes especially important when structured content is published in several languages because one overlooked dependency can affect many generated pages, manuals or audience-specific variants.
A practical example. A client finds a Spanish instruction error months after publication, but the original topic set and map keys cannot be reconstructed. The best diagnostic is to examine the rendered deliverable in the actual publication context, not merely to open the isolated XML file. A reusable topic can behave differently depending on the map and keys that select it.
Recommended workflow. Archive the approved map and topics, required assets, build parameters, toolkit version, output hashes and change notes according to retention rules. Assign the responsible person: technical writers protect structure, translators preserve meaning, subject specialists validate instructions, and the release owner decides which artifact may be distributed. This division of responsibility helps teams repair problems without silently rewriting language or code.
Verification. A future editor can reproduce the edition and identify which reused content needs correction. Include at least one commonplace topic and one difficult topic in the sample set. Save the target filename or URL and the relevant observation so the verification can be repeated in the next language or product release.
Failure to avoid. Do not expose private source repositories or restricted documentation publicly as part of the archive. A technically complete build is valuable evidence that the processing pipeline ran, but it does not demonstrate that a reader can interpret the correct procedure, product context or caution. The released material is judged by what it communicates.
Worked publication case: one equipment manual in three language editions
A manufacturer has an English DITA map for an industrial pump, plus approved German and Arabic topic sets. Several procedures reuse an electrical-isolation warning, while separate product variants use a key to resolve their correct model name. The translated instructions are already approved; the DITA-OT task is to produce stable HTML5 help and controlled PDF outputs without changing that meaning.
Begin by checking the model variant and the map used for each release. If the wrong map is passed to the command, every subsequent output can be internally consistent while showing the wrong model name or task inventory. Review xml:lang values and map-level navigation titles, then build a small HTML5 proof containing a reusable warning, model-name key, ordered repair steps, a table and an image with alternate text.
Next inspect all reuse cases in the generated result. The shared warning must be the approved one, and its appearance must place the hazard before the risky action. The model key must resolve in the intended product scope, not to the source-language default. For German, inspect lengthy technical compounds in page and navigation layouts. For Arabic, review the direction and grouping of English model codes, measurements and error numbers.
Then produce the PDF proof using a controlled font configuration. The PDF must have usable chapter navigation, complete fonts and readable safety tables. The HTML and PDF do not have to share identical page and line breaks, but they must communicate the same procedures. Record build warnings, test output links, check for unapproved English fragments and obtain the final artifact approvals. This produces a defensible translation publishing system rather than a collection of files that merely compiled.
Frequently asked questions
Does DITA-OT translate topics?
No. It transforms structured DITA source into selected output formats. A translator, subject reviewer and documentation owner remain responsible for language quality and authorized instructions. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
What is the difference between a DITA map and a DITA topic?
A topic usually provides modular content; a map organizes topics, navigation, keys and publication context. Both can affect what readers see, so both need localization review. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
Why are generated headings still in English?
Some reader-facing strings are created by the toolkit or transformation resources rather than by the topic’s prose. Review xml:lang and the installed locale support, then inspect the output. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
Can I translate topic IDs and key names?
Treat them as structural identifiers until a controlled migration demonstrates every dependent link and reference has been updated. Translate the visible human-facing text instead. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
How can one conref error affect several books?
One reused content target may appear in multiple tasks or variants. Find where the target is referenced, correct the approved source and test all affected deliverables. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
Will a single clean HTML build prove the PDF is correct?
No. PDF rendering, fonts and page layout have separate failure modes. Produce and inspect each output the audience will actually use. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
How should we handle Arabic documentation?
Set proper language and direction in the source and test actual mixed-script procedures, product identifiers and numerical data in HTML and PDF with qualified reviewers. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
What is the easiest check for a wrong variant?
Verify the exact input map and conditional profile, then inspect model identifiers and high-risk procedures that differ between variants. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
Should a translated screenshot keep English interface labels?
Only when that accurately represents the product the reader will use. Otherwise localize the illustration or explain the language difference under an approved editorial decision. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
What makes a DITA-OT release auditable?
A versioned source map and topic set, translation approval, build configuration, toolkit version, named output artifacts, observed quality checks and release sign-off. Do not infer language accuracy or user safety solely from build status; verify the actual published document in the target context.
Documentation and complementary guides
Use DITA-OT’s official dita command documentation, globalization support and supported language information for current details. For a complementary subject from another eduKate family, read DITA XML translation QA for reused technical instructions. That article covers translation-side preservation; this guide focuses on DITA-OT build and publication evidence. For source-document workflow checks, see the po4a documentation localization guide as a different tool and file pipeline.
Final lesson
DITA-OT’s usefulness comes from repeatable structured publishing. The translator protects meaning, the map selects context, the toolkit assembles output, and the publisher verifies what readers truly receive. When those responsibilities are distinguishable, the same documentation can travel across markets without turning reuse, generated labels or invisible references into hidden errors.