You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Mozilla Localizability Guidelines

Last Update: 31-Mar-98
Contact: Rick Elliott <relliott@netscape.com>
Discussion: netscape.public.mozilla.i18n or mozilla-i18n@mozilla.org

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.

# Guideline Why?

1 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:

Localizers prefer to use tools that work directly on binary resources or separate text files, such as Java .property files.

Localization kits are simpler when they don't depend on complicated build environments.

Software updates are simpler; if a bug fix or new feature involves no UI, there's no need to re-release the localized portions of the product.

2 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.

3 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.
See example

4 Use only standard or "approved" resource types. Program data should be contained in standard platform resource files:

For cross platform string resources, use the file ns/include/allxpstr.h

For standard Windows controls, use the .rc* files located ns/cmd/winfe.

For standard Macintosh resources, use the .r files located in ns/cmd/macfe.

For Java or Javascript, use ListResourceBundles or .property files

If you feel you must develop a new resource types, you should be prepared to provide a template, modular parser or editing tool so that others can localize your work. 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.

5 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:

it eases testing by allowing QA to test the same binary with different localizations, eliminating a potential source of errors.

it simplifies the task of identifying what files need to be localized and which don't.

it simplifies the update process for revisions in which there are no UI changes.

6 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.
See example

7 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.

8 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.

9 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.
See example

10 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.

11 Use ToolTips.
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.

12 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.

13 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.

14 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.

15 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.

16 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.

#	Guideline	Why?
1	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: Localizers prefer to use tools that work directly on binary resources or separate text files, such as Java .property files. Localization kits are simpler when they don't depend on complicated build environments. Software updates are simpler; if a bug fix or new feature involves no UI, there's no need to re-release the localized portions of the product.
2	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.
3	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. See example
4	Use only standard or "approved" resource types. Program data should be contained in standard platform resource files: For cross platform string resources, use the file ns/include/allxpstr.h For standard Windows controls, use the .rc* files located ns/cmd/winfe. For standard Macintosh resources, use the .r files located in ns/cmd/macfe. For Java or Javascript, use ListResourceBundles or .property files If you feel you must develop a new resource types, you should be prepared to provide a template, modular parser or editing tool so that others can localize your work.	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.
5	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: it eases testing by allowing QA to test the same binary with different localizations, eliminating a potential source of errors. it simplifies the task of identifying what files need to be localized and which don't. it simplifies the update process for revisions in which there are no UI changes.
6	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. See example
7	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.
8	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.
9	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. See example
10	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.
11	Use ToolTips. 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.
12	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.
13	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.
14	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.
15	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.
16	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.

Mozilla

Mozilla Localizability Guidelines

See Also