Writing localizable code

This page tells you about best practices and guidelines when dealing with UI code with respect to localization. It is aimed at Mozilla and extension developers.

For technical details please also look at XUL_Tutorial:Localization.

About Localizers

A few notes about localizers for developers who rarely deal with them:

• localizers like tools, and they don't like editors,
• localization tools are often based on key-value pairs,
• at least some localizers have their talents focused on language skills and are not savvy in programming, or even building applications.

Guidelines

Thus, there are a few guidelines you should follow to make localization of your code easier:

Choose good key names

The names chosen for your keys (regardless of whether that's a DTD or a properties file) should be descriptive. Think of them as long variable names. If you change the semantics of a localized string, change the key. This will more likely be a good key name, and it will help tools to pick up that the change you do is different from just a spell fix.

Try not to assume grammar in composite strings

Splitting sentences into several keys often inadvertently presumes a grammar, a sentence structure, and such composite strings are often very difficult to translate. When a composite string is needed, try to give the translators "room to move". An example of a well used composite string is Firefox's setting for visited pages: the translator can (implicitly) position the text field as he sees fit.

Don't use preprocessor macros

The use of #if #else #endif or #expand is strongly discouraged. There are few exceptions to this rule, but in general, the localized file should comply with standards and should not require build tools to be transformed. If you want to add build processing to localized files, be sure to request feedback from l10n@. In most cases, you can just as well put the processing into the content code and reference different key-value pairs in l10n.

Use a good source directory structure

Be sure to put the localizable files in the right place. The addition of new top-level directories is a compromise between module ownership in the cvsroot repository and the ease of localization.

Use a good chrome directory structure

For a particular module mod, a target path jar:ab-CD.jar!/locale/ab-CD/mod/foo.dtd has been widely tested and is a good place for your files referenced as chrome://mod/locale/foo.dtd. Using a directory structure like this eases the localization process without the source code and is especcially recommended to extension authors. JAR Manifests can make this easy.

l10n impact

On frozen trees, there is the rule to not check in l10n-impact changes. So what does that mean? l10n-impact is

• any change to mozilla/@mod@/locales; Localizers find out if they have to catch up on changes by doing bonsai queries, just as everybody else does. No change means that this query result is empty.
• any changed or new use of existing localized strings; Anything that triggers a QA cycle on our 40+ localizations is l10n-impact.