Mozilla Localizability Guidelines
Contact: Rick Elliott <firstname.lastname@example.org>
Discussion: netscape.public.mozilla.i18n or email@example.com
This document provides a set of guidelines and suggestions for developing localizable versions and derivatives of Mozilla. Some of the guidelines require more in-depth examples or discussion; if available, you can follow the See Example link to see this extra information.
Don't mix data and code.
No hard coded strings, fonts or other user visible or configurable data in source code: all UI and configuration elements must be stored in separate files.
Localization is most successful when it is a "no-compile" process:
Don't mix UI and preferences.
Generally localized UI elements (e.g. menus, dialogs, messages) should be separated from generally non-localized elements (e.g. preference data) by storing them in separate files.
|Typically, preference data is much more difficult to localize than standard UI data. UI localization is done most often by 3rd party vendors, who employ linguists of only limited technical background. Localizing preference data should be restricted to knowledgeable engineers, but this is difficult to do if the it is mixed with the UI resources.|
No bit mapped text in Graphics.
If you need text to identify a graphical element, use ToolTips or a text-overlaying function (similar to the toolbars in Communicator).
It can be impossible to fit localized text into the bounds of a graphic
object, creating major localization headaches.
Use only standard or "approved" resource types. Program data
should be contained in standard platform resource files:
||Localization is a highly tools dependent process; if these tools fail because they encounter unexpected resource types, it delays this process as non-conforming resource types are translated by hand until the tools can be modified or created to handle them.|
Separate code from data in the delivered product.
Resources should not be linked into the program binary. Separate resource modules should be used (e.g. .dll, .ad, .class (or .jar) files, etc.)
Keeping the UI and configurable data separate from the binary executable
code has the following benefits:
Write in complete sentences.
String resources should be composed of complete sentences or phrases; concatenated strings should be minimized. When a concatenated string is required, it must use a positioning technology such as the Java MessageFormat() function or NSPR 2.0 sprintf, to allow reordering of multiple string parameters.
English word order and lack of gender differs greatly from the way
many other languages are constructed. What might seem a clever use of string
fragments in English could be a disaster in French, for example.
Sometimes you have to write it twice.
If the same English string is used in differing contexts, multiple string resources should be created. Even if the same phrase, in two different contexts, is identical in English, this may not be the case in another language.
|Many languages have multiple words where English has only one. For example, we can use the word "File" as a noun or a verb, but this may not be true for a different language.|
Don't make UI elements positionally dependent.
Dialogs must be able to have all controls and text widgets reordered to fit natural (i.e. human) language syntax in any language without breaking functionality.
|Buttons, entry fields and static text all might have to be reordered to support a different language. If the order of controls matters, you need to provide a way to deal with this in the localized product.|
Don't crowd the UI.
Dialogs should be constructed with at least 30% (preferably 100%) expansion room in mind. If this becomes impossible, a second dialog or a tabbed interface must be implemented.
English is perhaps one of the most compact Romance languages. On platforms,
such as Windows and Mac, where dialogs don't automatically resize, a lot
of time is spent in post translation dialog resizing. This is "by hand"
work. Much of this extra work can be eliminated by simply allowing sufficient
room to begin with.
Toolbars should have no more than 8 to 10 items.
If more buttons / icons are required, consider using drop down lists, multiline or scrolling toolbars, or some other solution.
|Another example of Guideline #9. Even in English, a long toolbar won't fit in 640 x 480 resolution. Guidelines 9 and 10 are also for the benefit of vision impaired users, who might use large fonts and lower screen resolutions to make the product more visible.|
All buttons / icons should use ToolTips and/or status bar messages (if possible).
|Using ToolTips allows you to attach longer descriptive text to buttons or icons which ordinarily would not fit, especially when that text is localized.|
Externalize HTML headers.
HTML is (sadly) a mixture of code (tags) and data (content). However, the tags themselves may be treated as data and changed during localization. If your code generates HTML, much of the document structure may need to be derived from strings stored in resource files.
|Localized HTML resources often require additional header information, such as the META CHARSET tag. Localizers must have access to these headers to make their changes.|
Maximize XP resources.
Cross platform resources reduce L10n costs - if they are implemented correctly. You should use them whenever possible. However, they need to support cross-language and cross-encoding needs. Cross platform string resources are (currently) stored in ns/include/allxpstr.h
|Cross platform resources only need to be translated once; they can then be used in multiple versions of the product. You must keep in mind, however, differences that arise between platforms when the language is no longer English. For example, the default encoding on Macintosh is Mac-Roman. This encoding is identical to Windows code page 1252 and the ISO-8859-1 code page for the first 128 characters; however, for the extended character range, this is no longer true. Localized cross platform strings might need a way to specify character set or other relevant information to be truly cross platform.|
Comment your resources.
Include comments in your resource files (if possible), especially for unusual terms or phrases, for resources that must not be translated, or for resources which must only be translated in a particular way.
|Such comments will aid the localization engineers and translators. Establishing a regular, parsable format for these comments that can be read by localization tools will help building localization kits.|
Avoid literal resource dependencies
Don't have your code depend on a resource to be in a particular form.
|If your code expects a string or other UI element to be certain way, it may not work when the UI is translated.|
Preserve the resource/identifier relationship
Keep resource identifiers constant from version to version. If resource 101 = "foo" in version 1.1, do not change the ID to 102 in version 2. Similarly, if the string "foo" no longer appears in version 1.2, don't assign the new string "bar" to resource ID 101; rather, implement a new resource, 102, and make that equal to "bar".
Again, localization is a highly tools dependent operation. "Leveraging"
tools can save time and money by reusing translations from version to version,
but only if they can find and match points of reference within your resource
files. These reference points are, generally speaking, the resource ID
and the resource string itself. Changing the relationship between these
will most likely break any leveraging tool's ability to preserve your investment
in previous localization work.
Note: this is NOT saying "Don't change resources from version to version." You can certainly modify resource 101, as long as it is still used for basically the same purpose. For example, you could change "foo" to "Foo", or "foo?" or "Foo!", etc. But if string 101 was actually something like "Quit" in version 1.1, don't make "Quit" string 102 in version 1.2, and don't make string 101 now equal to "Open" in version 1.2.