new versions of complete multilingual best practices documents

Hi,

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

.

____

Nancy Harrison

IBM Rational Software

Phone: 781-676-2535



multilingual-best-practices.dita

example1.dita

example2.dita

example3.dita

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:

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 OutputHere 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
LUOKAN 1 LASERLAITE

KLASS
1 LASER APPARAT

Varoitus!
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.

Varning
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:
This device may not cause harmful interference, and

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.

=

multilingual-best-practices.doc