We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

Don't use these techniques to develop new add-ons. Use WebExtensions instead.

If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

Given locale files for "en-US" and "fr" which provide translations of hello_id, the panel will now display "Hello!" or "Bonjour !", according to the current locale:

The translation is inserted into the node which has the data-l10n-id attribute set. Any previously existing content is just replaced.

The string is inserted as text, so you can't insert HTML using a statement like:

# Does not work. HTML tags are inserted as text.
hello_id= <blink>Hello!</blink>

Localizing element attributes

This feature is new in Firefox 39

You can localize certain attributes of elements with an l10n-id by setting its value with l10n-id.attributeName in the properties file like:

hello_id.accesskey= H

The following attributes are supported:

accesskey

alt

label

title

placeholder

Further the localization of the ARIA attributes aria-label, aria-valuetext and aria-moz-hint are supported with the same aliases as on Firefox OS:

ariaLabel

ariaValueText

ariaMozHint

Using localized strings in JavaScript

To reference localized strings from your main add-on code, you do this:

var _ = require("sdk/l10n").get;
console.log(_("hello_id"));

Assigning to "_" in particular is not required, but is a convention from the gettext tools and will make it possible to work with existing tools that expect "_" to indicate localizable strings.

Import the l10n module, and assign its get function to "_" (underscore).

Wrap all references to localizable strings with the _() function.

If you run it you'll see the expected output for the current locale:

info: Hello!

info: Bonjour !

Note that because you can't require() modules in content scripts, you can't yet reference localized strings from content scripts.

Plurals

The l10n module supports plural forms. Different languages have different rules for the formation of plurals. For example, English has two forms: a singular form for "one", and a plural form for "everything else, including zero":

one tomato
no tomatoes
two tomatoes

But Russian has different forms for numbers ending in 1 (except 11), numbers ending in 2-4 (except 12-14) and other numbers:

The SDK uses the Unicode CLDR data to describe the different plural forms used by different languages.

Unicode CLDR plural forms

The Unicode CLDR project defines a scheme for describing a particular language's plural rules. In this scheme a language maps each distinct range of numbers on to one of up to six forms, identified by the following categories: zero, one, two, few, many, and other.

English has two forms, which can be described by mapping "1" to "one" and "everything else" to "other":

one → n is 1;
other → everything else

Russian uses four forms, that can be described as follows:

one → n mod 10 is 1 and n mod 100 is not 11;
few → n mod 10 in 2..4 and n mod 100 not in 12..14;
many → n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
other → everything else

In the .properties file for each language you can define a different localization for each plural form possible in that language, using the CLDR keywords. So in English we could have two plural localizations (note that the "other" category does not take the CLDR keyword):

The localization module itself understands the CLDR definitions for each language, enabling it to map between, for example, "2" in the code and "few" in the ru-RU.properties file. Then it retrieves and returns the localization appropriate for the count you supplied.

Placeholders

The l10n module supports placeholders, allowing you to insert a string which should not be localized into one which is. The following "en-US" and "fr" ".properties" files include placeholders:

# en-US translations
hello_id= Hello %s!

# fr translations
hello_id= Bonjour %s !

To use placeholders, supply the placeholder string after the identifier:

Using localized strings in preferences

Preferences have mandatory title and optional description fields. These are strings which appear alongside the preference in the Add-ons Manager, to help explain to the user what the preference means.

To provide the localized form of the preference title, include an entry in your "properties" file whose identifier is the preference name followed by _title, and whose value is the localized title.

To provide the localized form of the preference description, include an entry in your "properties" file whose identifier is the preference name followed by _description, and whose value is the localized description.

Now when the browser's locale is set to "en-US", users see this in the Add-ons Manager:

When the browser's locale is set to "fr", they see this:

The menulist and the radio preference types have options. The label attribute of each option is displayed to the user. If the locale file has a entry with the value of the label attribute prefixed with "{name}_options." as its key, where {name} is the name of the preference, its value is used as a localized label.

Using identifiers

If the localization system can't find an entry for a particular identifier using the current locale, then it just returns the identifier itself.

This has the nice property that you can write localizable, fully functional add-ons without having to write any locale files. You can just use the default language strings as your identifier, and subsequently supply .properties files for all the additional locales you want to support.

For example, in the case above you could use "Hello!" as the identifier, and just have one .properties file for the "fr" locale:

Hello!= Bonjour !

Then when the locale is "en-US", the system would fail to find a .properties file, and return "Hello!".

However, this approach makes it difficult to maintain an add-on which has many localizations, because you're using the default language strings both as user interface strings and as keys to look up your translations. This means that if you want to change the wording of a string in the default language, or fix a typo, then you break all your locale files.

Locale updater

The locale updater add-on makes it easier to update locale files. Once you've installed it, open the Add-on Manager, and you'll see a new button labeled "Update l10n" next to each add-on you've installed:

Click the button and you'll be prompted for a new .properties file for that add-on. If you provide a new file, the add-on's locale data will be updated with the new file.

Limitations

The current localization support is a first step towards full support, and contains a number of limitations.

There's no support for content scripts or CSS files: at the moment, you can only localize strings appearing in JavaScript files that can require() SDK modules and in HTML. See bug 787351.

The set of locale files is global across an add-on. This means that a module isn't able to override a more general translation: so a module informal.js can't specify that "hello_id" occurring in its code should be localized to "Hi!".

The SDK tools compile the locale files into a JSON format when producing an XPI. This means that translators can't localize an add-on given the XPI alone, but must be given access to the add-on source.

The add-on developer must manually assemble the set of localizable strings that make up the locale files.