Localizing in XHTML output targets

Overview of how translation works for XHTML processing

For XHTML output, the unit of translation for the files included in a DITA map is the individual DITA topic file. In order to translate a topic to another language, it is necessary to translate text in the file and to cause the DITA Open Toolkit to translate any character strings it places in output, such as the string "Related links" in XHTML output.

xml:lang and translate universal element attributes

The language used in an element contained in a DITA topic is controlled by setting two universal attributes. They are:

xml:lang: Specifies the language of the element content. When no xml:lang value is supplied, the default value of US English (en-us) is assumed.
translate: Indicates whether the content of the element should be translated or not.

If a topic element does not specify the xml:lang attribute, it inherits the value from any ancestor element in the file. If no xml:lang attribute is specified, the default value en-us is assumed. The translate attribute controls whether the content of an element needs to be translated.

For more information regarding the XML standards related to the xml:lang attribute, see http://www.w3.org/International/articles/language-tags/Overview.en.php.

Steps to localize a DITA topic

To translate a topic to another language, first set tne xml:lang attribute in the topic. Typically this is set on the root element. Setting the attribute causes the Toolkit processing to substitute localized values for any strings in inserts into the output. The final step is to translate text in the topic to the target language.

How DITA Open Toolkit processing handles localization for XHTML output

When it processes a topic, the Toolkit uses the xml:lang value in each topic element to determine how to do string substition and to flow text (for example, left to right or right to left). If no xml:lang attribute is specified, it follows the ancestor chain of the current topic to determine xml:lang from any containing element. If none is found, the default language is used.

Note: Setting xml:lang in the .ditamap file embedding a topic has no effect on how the topic gets translated by the Toolkit.

Example

Here is an example of how this works. In the first case we have a concept that begins:

<concept id="about_produce_template" xml:lang="en-us">

This sets the language to US English for this topic. The XHTML output for the topic looks like the following figure, with the generated strings highlighted:

If we change the value of the xml:lang attribute to "de-de", the XHTML output will include generated strings in German, as shown in the following figure.

Finally, if we change the value of the xml:lang attribute to "ar-eg", the XHTML output will include generated strings in Arabic with text flowed right to left, as shown in the following figure.