ITS WG Collaborative editing page

Back to Techniques

Provide a way to specify comments for translators

To assist the translator to achieve a correct translation, authors may need to provide information about the text that they have written. For example, the author may want to:

tell the translator how to translate part of the content
expand on the meaning or contextual usage of a particular element, such as what a variable refers to or how a string will be used on the UI
clarify ambiguity and show relationships between items sufficiently to allow correct translation (e.g. in many languages it is impossible to translate the word 'enabled' in isolation without knowing the gender, number and case of the thing it refers to.)
explain why text is not translated, point to text re-use, or describe the use of conditional text
indicate why a piece of text is emphasized (important, sarcastic, etc.)

Localization information is especially important in documents designed for storing resource-type data (as opposed to article-type document) Resources such as messages, or prompt are often lacking necessary context information for the localizers.

Provide your own note markup

The best way to allow for such information is to provide an element where the author of the document can enter the text of its notes.

Example 1: Localization annotation in a resource-type document

The <comment> element holds the localization information associated to the <value> element.

<data name="ERR_NOTFOUND">
 <value>Cannot find {0}.</value>
 <comment>{0} represents the path of a file.</comment>
</data>

Providing localization information in an article-type document can be a bit more difficult as you want to avoid breaking the flow of the text.

Example 2: Localization annotation in an article-type document:

The <locNotes> element hold notes associated with the <topic> element, and the locNote attribute contains localization notes for the text enclosed in the element.

<topic>
 <locNotes>Do not translate the name of the elements or attributes of MagicML.
Elements are between brackets. For potions ingredients translation, see the 
Potions.html file shipped with the localization kit.</locNotes>
 <title>Using MagicML</title>
 <par>A MagicML document is divided into three main categories:</par>
 <list>
  <par>The <spells> section contains the descriptions of magic spells.</par>
  <par>The <potions> section contains receipts for magic potions.</par>
  <par>The <curses> section contains the description of 
<span locNote="As in 'malediction' (not expletives)">curses</span>.</par>
 </list>
 ...
</topic>

Note that using attributes is generally not recommended for most of the same reasons why translatable attributes are discouraged. Use attributes only if you cannot do otherwise.

ITS Rules Declaration

In all cases, use <its:locInfoRule> with its:locInfoPointer to indicate what markup in your format corresponds to the localization information.

Declaration for Example 1:

<its:locInfoRule its:selector="//data/value"
 its:locInfoPointer="../comment" />

Declaration for Example 2:

<its:locInfoRule its:selector="//topic"
 its:locInfoPointer="locNotes" />
<its:locInfoRule its:selector="//span"
 its:locInfoPointer="@locNote" />

If the notes are stored in elements, do not forget to make sure they are not counted as part of the text to localize. For this use the <its:translateRule> element:

Declaration for example 1:

<its:translateRule its:selector="//data/comment"
 its:translate="no"/>

Declaration for example 2:

<its:translateRule its:selector="//locNotes"
 its:translate="no"/>

Provide a reference to the notes

Another way to provide localization information in a document is to offer references to notes rather than store the text of the note along with the annotated content. The note can be located elswhere in the document or in a different document.

Example 3: Reference to a localization note

The attribute noteref value is a reference to a note for the content of the element.

<item id="msg100" noteref="myNotes.html#msg100">
 <data>Some text</data>
</item>

ITS Rules Declaration

Use <its:locInfoRule> with its:locInfoRefPointer to indicate what markup in your format corresponds to the localization information.

Declaration for Example 3:

<its:locInfoRule its:selector="//data"
 its:locInfoRefPointer="../@noteref" />

Types of Localization Notes

You may want to distinguish between two types of localization information: One type for very important notes the localizers must read to avoid making mistakes, another type for informative notes.

Example 4: Two type of localization notes

The <READTHIS> element indicates an important note.

<item id="msg_Count">
 <data>Number of occurences found in %s = %d</data>
 <READTHIS>%s and %d MUST always stay in the same order!</READTHIS>
</item>

ITS Rules Declaration

Use the its:locInfoType attribute to specify the type of note.

Declaration for Example 4:

<its:locInfoRule its:selector="//data"
 its:locInfoPointer="../READTHIS" its:locInfoType="alert" />

If no type is specified, the type "description" is used.