How are map references and links adapted for localized content?

DITA map references and links are adapted for localized content through the use of conditional processing, language-specific keys, and translation of navigation elements to ensure that links and references work seamlessly with translated content.

Adapting DITA Map References and Links

When adapting DITA map references and links for localized content, organizations often employ conditional processing or language-specific keys to ensure that links and references in the map point to the appropriate language versions of content.

Conditional Processing

DITA maps allow for applying conditional processing attributes like conkeyref. These attributes are used to control the inclusion of content based on certain conditions. In the context of localization, conditional processing can be used to include or exclude language-specific topics or content. For example, conkeyref can be used to include content with a specific key reference that corresponds to the target language.

Language-Specific Keys

Language-specific keys are used to identify content that is specific to a particular language. For example, keys like “en” for English and “fr” for French can be used. By associating topics or content with these language-specific keys, it is ensured that the correct content is included in the DITA map during the localization process.

Translation of Navigation Elements

Navigation elements, such as table of contents (TOCs), indexes, and cross-references, need to be translated to match the target language. This includes not only the text but also considerations like text direction (left-to-right or right-to-left) and formatting to accommodate different character sets and text length.


A DITA map containing references to topics in both English and Spanish might use conditional processing attributes like conkeyref to include language-specific references based on the target language:

  <title>User Manual</title>
  <topicref href="common-intro.dita" />

  <!-- Conditional processing for French -->
  <topicref href="instructions-fr.dita" conkeyref="fr" />

  <!-- Conditional processing for English -->
  <topicref href="instructions-en.dita" conkeyref="en" />

In this example, the map includes references to language-specific topics based on the conkeyref attribute. When the map is localized for a French-speaking audience, the French version of the instructions-fr.dita topic will be included, ensuring that links and references in the map point to the correct language version, providing a seamless experience for users.