OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-translation message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: new versions of complete multilingual best practices documents


Here is the complete set of artifacts relevent to the multilingual best practices.  Let me know if there's anything you think is missing.

DITA versions

HTML versions

Microsoft Word version


Nancy Harrison
IBM Rational Software
Phone: 781-676-2535





Title: Incorporating Multilingual Content with DITA: Best Practices

Incorporating Multilingual Content with DITA: Best Practices

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:

  1. 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.
  2. 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

Title: Multilingual Example 3

Multilingual Example 3

Put your short description here; used for first paragraph and abstract.

For Finland and Sweden




Laitteen käyttäminen muulla kuin tässä käyttöohjeessa mainitulla tavalla saattaa altistaa käyttäjän turvallisuusluokan 1 ylittävälle näkymättömälle lasersäteilylle.


Om apparaten används på annat sätt än i denna Bruksanvisning specificerats, kan användaren utsättas för osynlig laserstrålning, som överskrider gränsen för laserklass 1.

Title: Multilingual Example 1

Multilingual Example 1

Example of multilingual text used for government compiance.

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

Table 1. table 1
Responsible Party: Bloggs Corporation Somewhere, USATelephone: (123) 456-7891

declares, that the products

Table 2. table 2
Product name: Laser Printer 1234 and 5678
Model number: 1234
Product option: Go-faster stripes unit
comply with Part 15 of the FCC Rules. Operation is subject to the following two conditions:
  1. This device may not cause harmful interference, and
  2. This device must accept any interference received, including interference that may cause undesired operation.

This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful interference in a residential installation. This equipment generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with the instructions, may cause harmful interference to radio communications. However, there is no guarantee that interference will not occur in a particular installation. If this equipment does cause harmful interference to radio or television reception, which can be determined by turning the equipment off and on, the user is encouraged to try to correct the interference by one or more of the following measures:

  • Reorient or relocate the receiving antenna.
  • Increase the separation between the equipment and receiver.
  • Connect the equipment into an outlet on a circuit different from that to which the receiver is connected.
  • Consult the dealer or an experienced radio/TV technician for help.
Title: Multilingual Example 2

Multilingual Example 2

Example of multilingual text used for compliance with Canadian government regulations.

Industry Canada Compliance Statement (For Canada)

This Class B digital apparatus complies with Canadian ICES-003.

Cet appareil numérique de la classe B est conforme à la norme NMB-003 du Canada.



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]