How to Translate a DITA Map (Not Just the Topics)

Quick answer — A DITA map assembles topics into a deliverable and carries its own translatable content: navigation titles, key definitions, topic groups and relationship tables. Translating topics without the map produces English navigation over translated pages.

The map is content, not just plumbing

It is easy to read a .ditamap as configuration — a list of file references — and scope it out of translation. It is not configuration. navtitle attributes, topicmeta titles, topicgroup and topichead labels, and key definitions all carry text that appears in the output. Skip the map and the reader gets a translated topic with an English breadcrumb above it.

Key definitions are the sharp part

A keydef binds a key name to a value — often a product name, a version string or a UI label reused across hundreds of topics. Topics reference the key; the map supplies the text. That means one edit in the map changes text everywhere, which is the whole point and also the risk. The key name must never be translated; the value it points at usually must be.

Relationship tables

reltable builds related-links sections automatically. The links are generated, so they follow the translated topics, but any labels in the table are map-level text that needs translating with it.

Nested and peer maps

Large documentation sets use maps referencing other maps. A translation scope that catches the root map and misses the submaps produces a partially translated navigation tree, which reads as a bug rather than a gap.

Walk the map references before scoping. There are usually more than the team remembers.

Filtering applies here too

ditaval conditions filter at build time and are applied to maps as well as topics. A map can therefore assemble a different set of topics per product, which means the translated deliverable for one product may not need every topic in the set.

Knowing that up front is the difference between translating what ships and translating everything.

Output formats change what matters

A PDF deliverable cares about the map's ordering and titles for its table of contents. A help site cares about them for navigation and search. The same map content surfaces differently, and both need it translated.

document translation handles the structure and translation memory keeps key values consistent with the topics that reference them.

The topic side is covered on the DITA translation integration page, and map specifics on the [DITA map integration](/integration/ditamap) page.

Bookmaps and front matter

A bookmap adds front and back matter — preface, notices, glossary, index markers. That content sits in the map structure rather than in a topic, so a topic-only scope leaves a translated manual with an English preface.

Legal notices in particular tend to live here, and they are the pages a regulated deliverable is judged on.

Testing the navigation

Build the deliverable and click through the table of contents in the target language. Navigation is the first thing a reader touches and the last thing anyone checks, and a broken submap shows up immediately in a built tree.

Where to start

List every map in the set, including nested ones, before scoping any topics. The navigation is what a reader touches first and it is the most visible thing to get wrong.

FAQ

Does a DITA map need translating separately from topics? Yes. Navigation titles, topicmeta titles, topic group labels and key definitions all live in the map and appear in the output, so translating topics alone leaves English navigation over translated pages.

What is a keydef and how is it translated? A key definition binds a key name to a value reused across many topics. The key name must never be translated; the value it points at usually must, and changing it once updates every topic referencing it.

What happens with nested maps? A scope that catches the root map and misses submaps produces a partially translated navigation tree. Walk the map references before scoping, because there are usually more than the team remembers.

Do ditaval conditions affect what needs translating? Yes. A map can assemble a different topic set per product, so the deliverable for one product may not need every topic. Knowing that up front separates translating what ships from translating everything.