new versions of complete multilingual best practices documents

Following are a proposed set of best practices for sourcing multilingual content in DITA in order to publish it within a single output document. In the descriptions below, it’s expected that the document has a ‘base language’ which is the language in which the author writes the largest part of the document, and instances of text in one or more ‘secondary languages.’

Translatable Multilingual Text

A common case for multilingual documents is one in which certain parts of a document must be translated into multiple secondary languages, and must then be published with all translations appearing in the same document. One example of this would be an instruction sheet consisting of identical content in multiple languages. Another example is a document whose base language is English, but which contains warnings in multiple languages.

Recommendations for this situation are as follows:

Use topic-sized chunks of content to the extent possible. In this case, each language should have its own topic, with file names or reference names (in a CMS) annotated using the xml-lang attribute by language/locale. Pieces are to be assembled using the associated DITA map.
If you believe your text chunk is too small to be regarded as a topic., review carefully your reasoning for this decision. We recommend that even a single translatable sentence be assigned its own topic to expedite translation. If it’s because the content consists of small chunks of content, such as product names, or phrases, modify it to be complete phrases, at least, and preferably complete sentences. For the most part, there is no reason why any complete sentence couldn’t have its own topic, as long as the topic title can be ignored.

When translating multilingual content, as with any other content, the sentence is the minimum useful chunk. We also strongly recommend that translatable strings be maintained at least at the sentence level, rather than at the fragment level.
If the content simply can’t be stored in its own topic, store the content chunks for a single language together in one or more ‘collection topics.’ A collection topic is a topic containing smaller chunks of content that is not in the flow of a document, and that is never called from a DITA map; a generic <topic> type may be useful for this to enable storage of various types of content. In a collection topic, each content chunk has its own ID string, so that it can be conref’d from the primary source document as needed. However, every chunk should consist of complete sentences, to enable appropriate creation of translation memory (TM). The document type used for a collection topic should share the same domains as the documents that will reference it.

Non-translatable Multilingual Text

A different issue is presented when a document contains text in multiple languages that is not intended for translation. This is common in a number of situations:

Use of text in a variety of languages required for compliance with government regulations
Use of text in a variety of languages to provide critical hardware instructions
Use of text within a single liturgical or academic manuscript, where either multilingual text is provided with no translation at all, or the description and explanation of the text is the subject of the document, and so translating it in the ordinary way would corrupt the intended document content.

In all the above situations, the original multilingual text must remain visible in the document.

When working with non-translatable multilingual text, it’s expected that the document has a ‘base language’ which is the language in which the author is writing the document, and instances of one or more ‘secondary languages.’ Using this terminology, the recommendations are:

Encapsulate each instance of secondary language text within its own container element or elements. The containers can include sub-elements, but there must be containing elements on which to set the appropriate attributes. The containers can be either block-level (for example, <p>, <section>), or inline (for example, <ph>, <uicontrol>, <keyword>) elements. For example, if an instance of secondary language text consisted of three consecutive paragraphs, each <p> would be considered a containing element.
Within the containing element, set the xml:lang attribute to indicate the language of the text, and set the translate attribute to “no”, to indicate that in this case nothing needs to be translated.

With this type of content, there is no requirement to separate the secondary language content in its own topic; it can remain in the same topic as the base language content, and be stored in the same file or CMS record as the rest of the document.

Examples and Sample Output

Here are links to examples of multilingual text

Multilingual Example 1
Multilingual Example 2
Multilingual Example 3

dita-translation message

Incorporating Multilingual Content with DITA: Best Practices

Translatable Multilingual Text

Non-translatable Multilingual Text

Examples and Sample Output

Multilingual Example 3

For Finland and Sweden

Varoitus!

Varning

Multilingual Example 1

Federal Communications Commission (FCC) Declaration of Conformity (For USA)

Multilingual Example 2

Industry Canada Compliance Statement (For Canada)