How are language-specific variations of reused content handled in DITA?

In DITA, language-specific variations of reused content are managed through a combination of key-based references and language-specific attributes. This allows content creators to maintain a single source of content while providing variations for different languages or locales.

The core factors of reusing language-specific content are:

  • Key-Based References: DITA uses key-based references to connect reused content to the source. These keys are typically associated with specific elements within the content, making it possible to create variations for different languages or other purposes.
  • Language-Specific Attributes: In DITA, attributes like xml:lang are used to define the language of specific content within an element. For language-specific variations, the xml:lang attribute can be applied to the content at the element level, indicating the language or locale for which it is intended.
  • Conref Push and Pushafter: Conref push and pushafter attributes enable the inclusion of language-specific content variations. For example, content intended for French audiences can be pushed into the reused topic element based on the presence of the xml:lang attribute.
  • Conditional Text: Conditional text processing can be used to selectively include or exclude variations based on the target language. Specific conditions can be set to include content only when the document is being produced for a certain language.
  • Localized Content: DITA also allows for creating separate, language-specific topic variants that contain the localized content. These variants can be associated with the main topic and selected based on the document’s target language.


A DITA-based user manual for a software application includes a set of warning messages. To provide language-specific variations of these warnings, the following approach can be used:

  1. The warnings in the main topic are marked with language-specific xml:lang attributes. For example, a warning might have xml_lang=”en-US” to indicate it’s in U.S. English.
  2. For French translations, a separate topic variant is created with warnings translated into French. The warnings in this variant have xml_lang=”fr-FR”.
  3. In the DITA map, conditional processing attributes or keys are used to include the appropriate language-specific warning based on the target language. For example, for an English version, conkeyref or conref push retrieves the English warning. For a French version, it retrieves the French warning.