• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
Add-ons
  1. MDN
  2. Mozilla
  3. Add-ons
  4. Add-on SDK
  5. Tutorials
  6. Localization

Localization

In This Article
  1. Localized strings
  2. Using localized strings in HTML
    1. Localizing element attributes
  3. Using localized strings in JavaScript
    1. Plurals
      1. Unicode CLDR plural forms
      2. Plural forms in the SDK
    2. Placeholders
    3. Ordering placeholders
  4. Using localized strings in add-on meta data
  5. Using localized strings in preferences
  6. Using identifiers
  7. Locale updater
  8. Limitations
  9. See also

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. 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.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

The SDK supports localization of strings appearing in:

  • your main add-on's JavaScript code
  • HTML files packaged with your add-on
  • the title, description and homepage fields of your add-on's metadata
  • the title and description fields of your add-on's preferences.

It doesn't, yet, support localization of CSS or content scripts, or the add-on's title and description that appear in the Add-ons Manager. See Limitations below.

Localized strings

Translated strings are kept in a directory called "locale" under your main add-on directory, one file for each locale. 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, consisting of an identifier for the string and its translation in that locale, in the format identifier=translation
  • need to use UTF-8 without BOM encoding
  • Lines starting with "#" (after optional whitespace) are comments

Suppose your add-on contains a single localizable string, represented in English as "Hello!", and you want to supply US English and French French localizations.

You'd add two files to the "locale" directory:

my-addon/
         data
         lib
         locale/
                en-US.properties
                fr.properties

"en-US.properties" contains this:

hello_id= Hello!

"fr.properties" contains this:

hello_id= Bonjour !

Now whenever your JavaScript or HTML asks the localization system for the translation of the hello_id identifier, it will get the correct translation for the current locale.

Using localized strings in HTML

This example uses the action button API, which is only available from Firefox 29 onwards.

To reference localized strings from HTML, add a data-l10n-id attribute to the HTML tag where you want the localized string to appear, and assign the identifier to it:

<html>
  <body>
    <h1 data-l10n-id="hello_id"></h1>
  </body>
</html>

Then you can use this HTML file to build your interface, for example inside a panel:

var button = require("sdk/ui/button/action").ActionButton({
  id: "localized-hello",
  label: "Localized hello",
  icon: "./icon-16.png",
  onClick: function() {
    hello.show();
  }
});
var hello = require("sdk/panel").Panel({
  height: 75,
  width: 150,
  contentURL: require("sdk/self").data.url("my-panel.html")
});

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.

  1. Import the l10n module, and assign its get function to "_" (underscore).
  2. 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:

один помидор     // one tomato
два помидора     // two tomatoes
пять помидоров   // five tomatoes

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

Plural rules for all languages can be found in the CLDR Language Plural Rules page (although this table is out of date compared to the CLDR XML source).

Plural forms in the SDK

In the code, you supply an extra parameter alongside the identifier, describing how many items there are:

var _ = require("sdk/l10n").get;
console.log(_("tomato_id"));
console.log(_("tomato_id", 1));
console.log(_("tomato_id", 2));
console.log(_("tomato_id", 5));
console.log(_("tomato_id", .5));

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

# en-US translations
tomato_id[one]= %d tomato
tomato_id= %d tomatoes

In Russian we could have four plural localizations:

# ru-RU translations
tomato_id[one]= %d помидор
tomato_id[few]= %d помидора
tomato_id[many]= %d помидоров
tomato_id= %d помидоры

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:

var _ = require("sdk/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" 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("sdk/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.

Using localized strings in add-on meta data

This feature is new in jpm 1.0.6. Support for homepage was added in jpm 1.0.7

By including a "locales" structure in your add-on's "package.json" file, you can localize the title, description and homepage of your add-on.

This structure holds objects referenced by the locale name containing at least one of title, description or homepage as a property.

For example, here's a "package.json" defining a German localization for title and description:

{
    "locales": {
        "de": {
            "title": "Monstergenerator", 
            "description": "Erstelle dein eigenes Monster"
        }
    },
    "name": "monster-builder", 
    "license": "MPL 2.0", 
    "author": "me", 
    "version": "0.1", 
    "title": "Monster Builder", 
    "id": "monster-builder@me.org", 
    "description": "Build your own monster"
}

Using localized strings in preferences

By including a "preferences" structure in your add-on's "package.json" file, you can define preferences for your add-on that the user can see and edit using Firefox's Add-ons Manager.

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.

For example, suppose your "package.json" defines a single preference:

{
    "preferences": [
        {
            "type": "string", 
            "name": "monster_name", 
            "value": "Gerald",
            "title": "Name"
        }
    ], 
    "name": "monster-builder", 
    "license": "MPL 2.0", 
    "author": "me", 
    "version": "0.1", 
    "title": "Monster Builder", 
    "id": "monster-builder@me.org", 
    "description": "Build your own monster"
}

In your "en-US.properties" file, include these two items:

monster_name_title= Name
monster_name_description= What is the monster's name?

In your "fr.properties" file, include the French translation:

monster_name_title= Nom
monster_name_description= Quel est le nom du monstre ?

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.

See also

These are links for developers looking to localize non-SDK add-ons.

  • How to localize HTML pages, XUL files, and js/jsm files from bootstrapped add-ons: Bootstrapped Extensions :: Localization (L10n)
  • XUL school localization tutorial: DTD/Entities method and Properties method
  • Localizing an extension

Document Tags and Contributors

Tags: 
  • Add-on SDK
  • Localization
 Contributors to this page: ThomasCharles94, wbamberg, Romaric, freaktechnik, Sebastianz, chrisdavidmills, maybe, ravinsinghd, Noitidart, laedit, evold
 Last updated by: ThomasCharles94, Dec 4, 2016, 5:54:47 AM
See also
  1. WebExtensions
  2. Getting started
    1. What are WebExtensions?
    2. Your first WebExtension
    3. Your second WebExtension
    4. Anatomy of a WebExtension
    5. Example WebExtensions
  3. How to
    1. Intercept HTTP requests
    2. Modify a web page
    3. Add a button to the toolbar
    4. Implement a settings page
  4. Concepts
    1. Using the JavaScript APIs
    2. User interface components
    3. Content scripts
    4. Match patterns
    5. Internationalization
    6. Content Security Policy
    7. Native messaging
  5. Porting
    1. Porting a Google Chrome extension
    2. Porting a legacy Firefox add-on
    3. Embedded WebExtensions
    4. Comparison with the Add-on SDK
    5. Comparison with XUL/XPCOM extensions
    6. Chrome incompatibilities
  6. Firefox workflow
    1. Temporary Installation in Firefox
    2. Debugging
    3. Getting started with web-ext
    4. web-ext command reference
    5. WebExtensions and the Add-on ID
    6. Publishing your WebExtension
  7. JavaScript APIs
    1. Browser support for JavaScript APIs
    2. alarms
    3. bookmarks
    4. browserAction
    5. browsingData
    6. commands
    7. contextMenus
    8. contextualIdentities
    9. cookies
    10. downloads
    11. events
    12. extension
    13. extensionTypes
    14. history
    15. i18n
    16. identity
    17. idle
    18. management
    19. notifications
    20. omnibox
    21. pageAction
    22. runtime
    23. sessions
    24. sidebarAction
    25. storage
    26. tabs
    27. topSites
    28. webNavigation
    29. webRequest
    30. windows
  8. Manifest keys
    1. applications
    2. author
    3. background
    4. browser_action
    5. chrome_url_overrides
    6. commands
    7. content_scripts
    8. content_security_policy
    9. default_locale
    10. description
    11. developer
    12. homepage_url
    13. icons
    14. manifest_version
    15. name
    16. omnibox
    17. options_ui
    18. page_action
    19. permissions
    20. short_name
    21. sidebar_action
    22. version
    23. web_accessible_resources
  9. Add-on SDK
  10. Getting started
    1. Installation
    2. Getting started
    3. Troubleshooting
  11. High-Level APIs
    1. addon-page
    2. base64
    3. clipboard
    4. context-menu
    5. hotkeys
    6. indexed-db
    7. l10n
    8. notifications
    9. page-mod
    10. page-worker
    11. panel
    12. passwords
    13. private-browsing
    14. querystring
    15. request
    16. selection
    17. self
    18. simple-prefs
    19. simple-storage
    20. system
    21. tabs
    22. timers
    23. ui
    24. url
    25. webextension
    26. widget
    27. windows
  12. Low-Level APIs
    1. /loader
    2. chrome
    3. console/plain-text
    4. console/traceback
    5. content/content
    6. content/loader
    7. content/mod
    8. content/symbiont
    9. content/worker
    10. core/heritage
    11. core/namespace
    12. core/promise
    13. dev/panel
    14. event/core
    15. event/target
    16. frame/hidden-frame
    17. frame/utils
    18. fs/path
    19. io/byte-streams
    20. io/file
    21. io/text-streams
    22. lang/functional
    23. lang/type
    24. loader/cuddlefish
    25. loader/sandbox
    26. net/url
    27. net/xhr
    28. places/bookmarks
    29. places/favicon
    30. places/history
    31. platform/xpcom
    32. preferences/event-target
    33. preferences/service
    34. remote/child
    35. remote/parent
    36. stylesheet/style
    37. stylesheet/utils
    38. system/child_process
    39. system/environment
    40. system/events
    41. system/runtime
    42. system/unload
    43. system/xul-app
    44. tabs/utils
    45. test/assert
    46. test/harness
    47. test/httpd
    48. test/runner
    49. test/utils
    50. ui/button/action
    51. ui/button/toggle
    52. ui/frame
    53. ui/id
    54. ui/sidebar
    55. ui/toolbar
    56. util/array
    57. util/collection
    58. util/deprecate
    59. util/list
    60. util/match-pattern
    61. util/object
    62. util/uuid
    63. window/utils
  13. Firefox for Android
  14. Getting started
    1. Walkthrough
    2. Debugging
    3. Code snippets
  15. APIs
    1. Accounts.jsm
    2. BrowserApp
    3. HelperApps.jsm
    4. Home.jsm
    5. HomeProvider.jsm
    6. JavaAddonManager.jsm
    7. NativeWindow
    8. Notifications.jsm
    9. PageActions.jsm
    10. Prompt.jsm
    11. RuntimePermissions.jsm
    12. Snackbars.jsm
    13. Sound.jsm
    14. Tab
  16. Legacy
  17. Restartless extensions
    1. Overview
  18. Overlay extensions
    1. Overview
  19. Themes
  20. Lightweight themes
    1. Overview
  21. Complete themes
    1. Overview
  22. Publishing add-ons
  23. Guides
    1. Signing and distribution overview
    2. Submit an add-on
    3. Review policies
    4. Developer agreement
    5. Featured add-ons
    6. Contact addons.mozilla.org
  24. Community and support
  25. Channels
    1. Add-ons blog
    2. Add-on forums
    3. Stack Overflow
    4. Development newsgroup
    5. IRC Channel