DITA Translation: Reuse, Conrefs and What Breaks

Quick answer — DITA's whole premise is that a topic is authored once and assembled into many deliverables. That makes translation efficient and it makes content references, key references and conditional profiling the things that break when handled carelessly.

Reuse changes the economics

In an unstructured documentation set, the same warning appears in nine manuals and is translated nine times. In DITA it is one topic referenced nine times, so it is translated once. That is the argument for DITA and it holds up. A structured set typically has far less unique text than its page count suggests, and translation cost tracks unique content rather than output volume.

Conrefs point at content that must exist

A conref pulls an element from another topic. When the target is translated, the reference resolves to the translated element — provided the target exists in that language and keeps the same element ID. Break the ID during translation and the reference resolves to nothing. The output builds with a gap where the reused warning should be, and nobody notices because the build does not fail.

Keyrefs are indirection, and safer

keyref resolves through a key definition in the map rather than pointing directly at content. That indirection is what lets one topic produce different output per product or per market.

Key definitions live in the map, so translating them is a map-level job rather than a topic-level one — which is easy to miss when the topics are what get handed to a translation process.

Conditional profiling multiplies the matrix

audience, product, platform and rev attributes filter content at build time. A topic can therefore contain text that only appears for one product.

Filtered-out content still needs translating if that product ships in that language, and it is invisible in the rendered output used for review. Translate the source, review the built output for each profile.

What must never change

Element IDs, @id attributes, key names, @conref and @keyref targets, and anything inside a codeblock.

Those are structure and code, and the DTD or schema will reject a file that breaks them — which is the good case, because it fails loudly.

Where memory pays hardest

Technical documentation is the most repetitive content there is. Procedures, warnings, parameter tables and prerequisite lists recur constantly.

translation memory returns those unchanged across releases and across products, and it is what keeps one term rendered identically across a set no reviewer could read end to end.

quality control then handles the sampling rather than the whole.

Maps and the assembly layer

Topics are content; the map is the assembly. Both need translating, and a translated topic set assembled by an English map produces a deliverable with a translated body and an English table of contents.

The map side is covered on the DITA map integration page, and the topic side on the DITA translation integration page.

Localization kits and vendor handoff

DITA toolchains can produce a localization kit: the topics that changed, their dependencies, and the map context needed to make sense of them. Sending the whole set instead is the common alternative and it is wasteful.

Generate the kit from the diff rather than the repository. It is the difference between paying for what changed and paying for the archive again.

Where to start

Run one map end to end and build the output. The build is what reveals broken conrefs, and it reveals them all at once rather than one support ticket at a time.

FAQ

Why is DITA cheaper to translate? Because content is authored once and reused. A warning appearing in nine manuals is one topic referenced nine times, so it is translated once and cost tracks unique content rather than page count.

What happens if a conref breaks during translation? The reference resolves to nothing and the output builds with a silent gap where the reused content should be. The build does not fail, so it is usually found by a reader rather than by the process.

Do conditional attributes affect translation? Yes. Filtered-out content still needs translating if that product or audience ships in that language, and it is invisible in the rendered output people review, so review has to cover each profile.

Does the DITA map need translating too? Yes. Topics are content and the map is the assembly, including key definitions. A translated topic set assembled by an English map produces a translated body with an English table of contents.