Your Search Results

    Getting started with app localization

    This guide explains how an app developer can localize an Open Web App. It only covers localizing the app's static HTML: additional guides cover how to localize strings in JavaScript and how to interact with the Transifex service, which connects app developers and translators.

    To follow this guide, you'll need to understand the basics of open web app development and how to load an app using WebIDE.

    The TranslationTester example app

    The app we'll use as an example is a version of the "Translation Tester", written by Robert Nyman. It just displays a quotation:

    If you want to follow along, you can clone this GitHub repository which contains the initial version of the app and the final localized version as well.

    The localization procedure

    We'll localize the strings that appear in the app's HTML as well as the name and description in the app manifest. The process will take four steps:

    • mark up the HTML: add a new attribute to each string in the HTML that will need localization
    • create translations: create a file for each language we need to support that contains the translated strings
    • include "l10n.js": include a JavaScript library in the app, that inserts the correct strings into the HTML
    • update "manifest.webapp": add the translations for "name" and "description" to the app manifest

    Here's screencast showing the complete process:

    Mark up the HTML

    You'll need to add a new attribute to every element in your HTML whose content needs to be translated. The name of the attribute is data-l10n-id, and its value is an identifier for the string. This identifier is used as a key to look up the correct translation of the string:

    <p data-l10n-id="winter-is-coming">Winter is coming</p>

    The localization system will replace the text contents of this node with the translated string for the current locale.

    In the TranslationTester there are two localizable strings, both in the app's index.html file. With the new attribute added, the <body> should look like this:

        <section role="region">
                <h1 data-l10n-id="app-heading">TranslationTester</h1>
        <div id="main">
                <p data-l10n-id="winter-is-coming">Winter is coming</p>
        <script type="text/javascript" src="js/base.js"></script>

    Create translations

    Next, create a new directory in your app's root named locales, and a directory under there for each language you need to support. Then in each of those directories, create a file called

    In this example we'll support two languages, English (en) and Spanish (es). The directory structure should look like this:

    • TranslationTester
      • css
      • fonts
      • images
      • index.html
      • js
      • locales
        • en
        • es
      • manifest.webapp

    The files contain the translations of strings that appear in the app's HTML and JavaScript. Each line is the translation of a single string in name=value format:

    • name is an identifier for this string, matching the value for a data-l10n-id attribute in the app's HTML
    • value is the translation of the string in this particular language.

    The under en will look like this:

    app-heading = TranslationTester
    winter-is-coming = Winter is coming

    The under es will look like this:

    app-heading = Tester Traducción
    winter-is-coming = Se acerca el invierno

    Usually, the app developer won't create the contents of a translator will create it, given the set of string identifiers and their value in the original language. For more on this, see the article on working with Transifex.

    Create locales.ini

    Next, create a new file in the locales directory called locales.ini. This file tells the app:

    • which locale is the default, in case the app does not support the current device language
    • which other locales the app supports
    • for each supported locale, where in the app the translated strings can be found

    It's organized as a collection of @import statements, each of which is labeled with the name of the language in square brackets. We indicate the default language by making its import statement the first line in the file and omitting its language label.

    In this case we want to make English the default, declare support for Spanish, and point the app to our files for each language. So the locales.ini file looks like this:

    @import url(en/
    @import url(es/

    We need to include this file in the app by adding a line like this in the <head> section of index.html:

    <link rel="resource" type="application/l10n" href="locales/locales.ini" />

    Add l10n.js

    To find nodes in the HTML marked with data-l10n-id and replace their contents with values from, we'll use a JavaScript library written by a Mozilla engineer, which we can copy from GitHub. Save this file as l10n.js alongside your other JavaScript files, and include it in the app by adding a line like this in the <head> section of index.html:

    <script src="js/l10n.js"></script>

    At this point we've finished localizing the app's HTML.

    Update manifest.webapp

    To localize the app's name and description, we need to update the manifest.webapp file. We'll add two new keys:

    • default_locale: this is assigned a language code which will be the default. When the device is set to this language or any language not explicitly supported by the app, the name and description already specified in the manifest will be used
    • locales: this contains one property for each supported language apart from the default, listing the values to be used for name and description in that language

    In this case we want to make English (en) the default, and support Spanish (es) as well, so we'll add the following lines to manifest.webapp:

    "default_locale": "en",
    "locales": {
      "es": {
        "name" : "Probador de traducción",
        "description" : "Para ayudar con la localización"
    If you work with a translator using the Transifex service, you'll probably keep the translations of name and description in separate files called, stored alongside your files.

    That's the last step. You can see what the app should look like now by downloading the final version.

    Test it out/How to view different locales

    Finally, test that the localization worked. Using a real Firefox OS device or the Simulator, change the device language to Spanish using one of these options:

    To view your app with a different locale, change the language in Firefox or Firefox OS:

    All platforms
    Set the desired locale to test in JavaScript, e.g: document.webL10n.setLanguage("es");
    Firefox OS (or Firefox OS Simulator via WebIDE)
    Language setting in the Settings app
    Choose language under Preferences > Content > Languages. More information in Set content language in Firefox

    In WebIDE or in Firefox, install or update the app, and open it. The strings it contains should now appear in Spanish:

    Note that because the strings in the app are replaced on page load, they're not dynamically updated when you change the language. You have to restart the app for the language change to be reflected in the app's interface.

    What's next?

    Localizing strings in JavaScript

    Most web apps will need to work with localizable strings in JavaScript as well as HTML. Read about how to localize strings in JavaScript.

    Working with translators

    Most of the time, app developers don't translate strings themselves: they work with translators who are fluent in the target language. The developer supplies a set of string identifiers and their value in the source language, and the translator then supplies the translations.

    We're working with Transifex to put app developers in touch with translators. Read about how to use the Transifex service to connect with translators.

    Document Tags and Contributors

    Contributors to this page: wbamberg, robertnyman, jryans, dalex, chrisdavidmills
    Last updated by: wbamberg,