# How to Translate a DITA Map (Not Just the Topics) | Vitra.ai

> The map is where the table of contents, key definitions and titles live. Translate the topics alone and half the deliverable stays English as well.

**Canonical URL**: https://www.vitra.ai/general/translate-a-ditamap
**Source**: This is the Markdown rendering of https://www.vitra.ai/general/translate-a-ditamap, generated at build time from that page.

---

4 min read

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

The map is where the table of contents, key definitions and titles live. Translate the topics alone and half the deliverable stays English as well.

[Samhitha J Bhatt](https://www.vitra.ai/author/samhitha)
Senior Product Manager , Vitra.ai
Updated Aug 17, 2026

![How to Translate a DITA Map (Not Just the Topics)](https://www.vitra.ai/static/images/blog/translate-a-ditamap.jpg)

Table of contents

[The map is content, not just plumbing](#the-map-is-content-not-just-plumbing)

[Key definitions are the sharp part](#key-definitions-are-the-sharp-part)

[Relationship tables](#relationship-tables)

[Nested and peer maps](#nested-and-peer-maps)

[Filtering applies here too](#filtering-applies-here-too)

[Output formats change what matters](#output-formats-change-what-matters)

[Bookmaps and front matter](#bookmaps-and-front-matter)

[Testing the navigation](#testing-the-navigation)

[Where to start](#where-to-start)

[FAQ](#faq)

Contributors

[Samhitha J Bhatt](https://www.vitra.ai/author/samhitha)
Senior Product Manager

Subscribe to our newsletter

Subscribe

> **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](https://www.vitra.ai/features/document-translation) handles the structure and [translation memory](https://www.vitra.ai/features/translation-memory) keeps key values consistent with the topics that reference them.

The topic side is covered on the [DITA translation integration](https://www.vitra.ai/integration/dita-translation) page, and map specifics on the [[DITA](https://www.vitra.ai/general/dita-translation-guide) 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.

Our blog

## Lastest blog posts

Tool and strategies modern teams need to help their companies grow.

Automotive

[Automotive Brochure Localization by Market](https://www.vitra.ai/automotive/automotive-brochure-localization)
A car brochure is a spec grid, a legal footer and a photo library, all market-specific. What actually has to change, and why the layout decides the schedule.

[Samhitha J Bhatt](https://www.vitra.ai/author/samhitha)
Aug 18, 2026

Automotive

[Automotive Campaign Localization Across Markets](https://www.vitra.ai/automotive/automotive-campaign-localization)
Campaigns run through national companies and dealer networks, so one master becomes hundreds of files. Where the offer text and the disclaimers actually break.

[Samhitha J Bhatt](https://www.vitra.ai/author/samhitha)
Aug 18, 2026

Automotive

[Car Service Manual Translation for Technicians](https://www.vitra.ai/automotive/automotive-service-manual-translation)
A workshop manual is read mid-repair by someone with the car on a lift. What that demands of procedures, torque figures and fault codes, in every language.

[Samhitha J Bhatt](https://www.vitra.ai/author/samhitha)
Aug 18, 2026

[View all posts](https://www.vitra.ai/blog/page/1)

---

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://www.vitra.ai/general/translate-a-ditamap"
  },
  "headline": "How to Translate a DITA Map (Not Just the Topics)",
  "image": [
    {
      "@type": "ImageObject",
      "url": "https://www.vitra.ai/static/images/blog/translate-a-ditamap.jpg"
    }
  ],
  "datePublished": "2026-08-17T00:00:00.000Z",
  "dateModified": "2026-08-17T00:00:00.000Z",
  "author": [
    {
      "@type": "Person",
      "name": "Samhitha J Bhatt"
    }
  ],
  "publisher": {
    "@type": "Organization",
    "name": "Vitra.ai",
    "logo": {
      "@type": "ImageObject",
      "url": "https://www.vitra.ai/static/images/vitra-v-logo.png"
    }
  },
  "description": "The map is where the table of contents, key definitions and titles live. Translate the topics alone and half the deliverable stays English as well."
}
```

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://www.vitra.ai"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "General",
      "item": "https://www.vitra.ai/general"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "How to Translate a DITA Map (Not Just the Topics)",
      "item": "https://www.vitra.ai/general/translate-a-ditamap"
    }
  ]
}
```

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Does a DITA map need translating separately from topics?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "What is a keydef and how is it translated?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "What happens with nested maps?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    },
    {
      "@type": "Question",
      "name": "Do ditaval conditions affect what needs translating?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "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."
      }
    }
  ]
}
```