User:Ramzi Linden/I18N Specifications

Verbiage

1. When writing a descriptor, or Help text, try to consider if your text has a subject + a verb.
   • hypothetical:
     • NOT SO GOOD: "Controls the angle that is reflected."
     • BETTER: "Controls the angle that light is reflected.
     • BETTER YET (for Help text): "The Surface Reflection Power Tool controls the angle that light is reflected from the water."
2. New UI text follows the Viewer Style Guide:
   • New UI text is highly localizable. The phrasing elimates geek-speak or robotic sentences in favor of conversational subject+verb sentences.
   • UI text does not depend on slang or idiom that does not translate easily.
3. New Help text is also highly localizable in the same manner.

Text and Layout

1. All new text strings should be extracted from a /skins/default/xui folder that contains XML files encoded as UTF-8.
   • New files use the existing standards of the Viewer's hierarchical-loaded localization architecture.
   • The Viewer should be capable to ship multiple locales for any parent language, such as es-ES vs. es-MX
2. Startup error messages, such as driver faults or wrong command parameters, are also internationalized in a similar manner.
3. When text needs to be assembled from multiple parts (concatenation), it is done so in a way that can accommodate alternate word order and specialized formatting of non-text information.
4. All GUI layout is wide enough to accommodate the reasonable text expansion of a foreign language. Generally, this means every widget can accommodate approximately 50% more space than is required by its English text, without the need for manual resizing.
   • Whenever possible, window layouts put the widget below its label, instead of beside it. This allows a full line width for text expansion of the label.
   • Multi-line text widgets are programmed to word-wrap.
   • Programmatic word-wrap handles alternate international punctuation gracefully, such as a double-byte period 。, colon ：, 「quotation marks」, （parenthesis） , ？ , etc.
   • The buttons in Dialogs and Toasts resize dynamically to accommodate text expansion. The largest button in a group of buttons may change in each locale.
   • Whenever possible, plan on 1.5 * width of the string AS YOU SEE IT IN ENGLISH. (A set of examples is in the image below.)
   • Flush-right any Help button ("?").

It is important to abstract in your head the width of the widget from the width of the text string. Foreign languages often result in longer strings to say the same thing.