Localization
The SDK supports basic localization of strings appearing in your main add-on's JavaScript code. It doesn't, yet, support localization of HTML, CSS, or content scripts.
Writing Localizable Code
To write localizable code, you do this:
var _ = require("l10n").get;
console.log(_("Hello!"));
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 itsget
function to "_
" (underscore). - Wrap all references to localizable strings with the
_()
function.
That's a fully functional add-on as it stands. If you run it you'll see the expected output:
info: Hello!
Localizing Your Code
To localize the code, create a directory called "locale" under your main add-on directory. In it, create one file for each locale you need to support. The files:
- use the
.properties
format - are named "xx-YY.properties", where "xx-YY" is the name of the locale in question
- contain one entry for each string you want to localize.
For example, if you want to add a French localization for the add-on above, you'd add a file called "fr-FR.properties" in the "locale" directory, and add the following to it:
Hello!= Bonjour!
Now if you run the add-on with Firefox switched to the French locale, you'll see:
info: Bonjour!
Using Identifiers
If l10n.get()
can't find a localization of a string using the current
locale, then it just returns the string you passed in. This is why the
example above displayed "Hello!" when there were no locale files present.
This has the nice property that you can write localizable, fully
functional code without having to write any locale files. You can just
use the default language in your code, and subsequently supply
.properties
files for all the additional locales you want to support.
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.
To avoid this you can use identifiers in your code, and supply localizations for all the languages you intend to support. For example, in your main.js:
var _ = require("l10n").get;
console.log(_("hello_string"));
Then you can create .properties
files for both en-US
and fr-FR
:
# en-US translations hello_string= Hello!
# fr-FR translations hello_string= Bonjour!
Plurals
The l10n
module has basic support for plural forms. The following
.properties
file includes separate localizations for the singular
and plural form of "child":
child_id[one]= one child child_id= %d children
To use it, list the count of the item after its identifier:
var _ = require("l10n").get;
console.log(_("child_id", 1));
console.log(_("child_id", 2));
This will give the following output:
info: one child info: 2 children
At the moment l10n
only distinguishes between two plural forms:
"one", and "not one". So it doesn't support
languages which have different plural rules.
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-FR
.properties
files include
placeholders:
# en-US translations hello_id= Hello %s!
# fr-FR translations hello_id= Bonjour %s!
To use placeholders, supply the placeholder string after the identifier:
var _ = require("l10n").get;
console.log(_("hello_id", "Bob"));
console.log(_("hello_id", "Alice"));
In the en-US
locale, this gives us:
info: Hello Bob! info: Hello Alice!
In fr-FR
we get:
info: Bonjour Bob! info: Bonjour Alice!
Ordering Placeholders
When a localizable string can take two or more placeholders, translators can define the order in which placeholders are inserted, without affecting the code.
Primarily, this is important because different languages have different rules for word order. Even within the same language, though, translators should have the freedom to define word order.
For example, suppose we want to include a localized string naming a person's home town. There are two placeholders: the name of the person and the name of the home town:
var _ = require("l10n").get;
console.log(_("home_town_id", "Bob", "London"));
An English translator might want to choose between the following:
"<town_name> is <person_name>'s home town."
"<person_name>'s home town is <town_name>"
To choose the first option, the .properties
file can order the
placeholders as follows:
home_town_id= %2s is %1s's home town.
This gives us the following output:
info: London is Bob's home town.
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, HTML files, or CSS files: at the moment, you can only localize strings appearing in JavaScript files that can
require()
SDK modules. -
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_string" 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. In a future release we'll add a command to
cfx
that scans the add-on for localizable strings and builds a template.properties
file listing all the strings that need to be translated. -
The algorithm used to find a matching locale is based on the Firefox implementation which is known to be sub-optimal for some locales. We're working on improving this in bug 711041.