Best Practices - Writing DITA with Localization in Mind – Tips for using text in DITA Maps

DITA Maps are used to assemble topics into a topic hierarchy for print, Web, Help, or any other deliverable. DITA Maps are thus the backbone for content reuse in DITA. By creating two separate DITA Maps that reference the same topic, two different deliverables can be created.

DITA Maps can contain text that might require translation. The title of the DITA Map, for example, might need to be translated as it is used on the front page of your deliverable and the same is true for <navtitle> elements, which are used for a shortened form of title for an online format.

Tip: Translate DITA Maps through the same process as regular topics

As a best practice, DITA Maps are translated through the same processes as regular topics. Be careful, however, with the metadata stored inside the DITA Map. Whether metadata needs to be translated depends upon the target language. It is therefore important that you come to an agreement with your translation agency on which elements require translation and which elements do not. The following section provides more details 

Using Elements to Hold Metadata 

For DITA topics, the <prolog> element is used to store metadata associated with a topic. Most of the metadata in a topic prolog can also be authored in a DITA map, within the Map’s <topicmeta> element.

Inside these elements, you can indicate such attributes as topic writer, copyright holder, and critical tracking dates.

Because most metadata is stored as regular text in the XML, translation tools will identify them as “translatable” unless they are configured otherwise. This poses a risk because translators may be translating text, such as the organization name or product name that is supposed to remain in the source language even after translation.

For example, you may declare the following metadata in the <bookmeta> element (the bookmap specialization of the <topicmeta> element):

<bookmeta>
  …
  <organizationname>Yokogawa</organizationname>
  …
<bookmeta>

When you translate the DITA Map into French, the organization name will be the same and so it has no translation, but when translating the DITA Map into Japanese, translation may be desirable and an expanded name may be desirable.

<bookmeta>
  …
  <organizationname>横河電機</organizationname>
  …
</bookmeta>