Edit online

Translating DITA Projects Overview

This topic contains some general information about translating DITA content and is meant to help those who do not store their DITA projects through a Content Management System (CMS) or other type of service that already includes their own translation support.

Choosing a Translation Agency

To minimize translation costs, it is recommended to choose a translation agency that is able to handle DITA content directly, without requiring you to convert the content to some intermediary format. This means that you benefit from the DITA reusable content features.

If you plan to translate your DITA project, it is also recommended that you contact a DITA-aware translation agency as early in your process as possible because translation agencies who translate DITA content directly usually need to have a preliminary discussion about how your project is structured, which terms need to be skipped when translating, how various measuring units are translated, how content is reused, your metadata strategy, and how screenshots are handled. Those discussions may influence the way that you organize and write your DITA content.

Note: If your translation agency does not directly handle DITA content, there are commercial tools that can be used to convert DITA to XLIFF (for example, https://www.maxprograms.com/products/fluenta.html).

Optimizing Content for Translation

In general, there are three main principles to take into account when writing DITA content that will be translated:
  1. Use a controlled vocabulary (for example, the Simplified Technical English vocabulary).
  2. Avoid reusing inline elements other than product names. The following DITA Users List discussion describes the reasons for this: https://lists.oasis-open.org/archives/dita/201301/msg00029.html.
  3. Avoid profiling/filtering content at inline level, for similar reasons.

General DITA Project Structure

It is usually considered best practice to organize your DITA maps/topics in a separate folder for each language. One folder that contains the English version of all of your DITA resources and a separate folder for each of the other languages you will translate with equivalent DITA resources translated in that specific language.

General Translation Workflow

When translating DITA content, the most common workflow involves these steps:
  1. Create your content in the primary language.
  2. Before each release, you gather all the DITA files that have been changed and need to be translated. The DITA Translation Package Builder Add-on could be handy for this.
  3. Send a copy of the relevant DITA files to the translation agency (known also as "localization service provider").
  4. Receive translated DITA content back from the translation agency and integrate it in each language-specific project folder.

Publishing Translated Content

All of your translated DITA maps and topics should have the xml:lang attribute set with the appropriate value on the root element. Along with the actual translated content, the published output may also contain static text (such as the word Table followed by the table number, Figure following by the number, or Note appearing before the content of each DITA <note> element). The DITA Open Toolkit includes support for various languages for HTML-based output and PDF-based output. You can also add support for other languages: Globalizing DITA Content: Customizing Generated Text. For information about how to add a new language to the Oxygen WebHelp Responsive output, see Adding a New Language.


Translation agencies usually do not assume any liability for incorrectly translated content. If possible, it is recommended to have someone who is familiar with the particular language be responsible for reviewing and accepting the translated content. For example, if your company has regional headquarters located in various countries, perhaps someone from each headquarters could review the translated content.

Other Resources

Here are some links to other resources that might help you with translating DITA projects: