[ESW Wiki] Update of "its0601TechLocInfoDev" by YvesSavourel

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "ESW Wiki" for change notification.

The following page has been changed by YvesSavourel:
http://esw.w3.org/topic/its0601TechLocInfoDev

------------------------------------------------------------------------------
  
   * 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 <span> 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 <data> 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.
+

Received on Tuesday, 28 March 2006 16:47:00 UTC