Localizing Open Web Apps

The purpose of this documentation is to make it as easy and clear as possible to quickly make sure your Open Web Apps are localized and ready to add more languages swiftly. If you want a blueprint app with localization support already implemented, please look at the TranslationTester below.

How the localization works

  • All localizations are available in a locales directory, organized by each language code
  • A locales.ini file imports them
  • An included l10n.js JavaScript file applies the current user locale's translation to respective element through their data-l10n-id attribute

Prepare your app for localization

There are 3 steps that you need to do to have your app support localization, divided up into different areas:

  1. Create files and translations for your desired languages
  2. Include files in your app
  3. HTML code changes

1. Create files and translations for desired languages

  1. Create a locales directory in the root of your app
  2. Create a directory in the locales directory for each language with its language code, e.g. en-US
  3. Create two files in each of your language directories: app.properties and manifest.properties. app.properties will have all the translations for your app's content, manifest.properties will have the translation for the name and description of your app
  4. Create a locales.ini file within the locales directory, importing the languages your app supports, e.g:
    @import url(en-US/app.properties)
  5. Open manifest.webapp in the root of your app and add your languages in the locales directive, e.g:

     "en-US": {
         "name": "Translation Tester",
         "description": "This is a testing app for Firefox OS translations"

2. Include files in your app

In your index.html file, or any page showing content in your app, you need to put references to two files:

  • l10n.js, which you can get in the Gaia source code
  • locales.ini, which you created above in the locales directory

Include them like this:

<!DOCTYPE html>
    <meta charset="utf-8">    
    <title>My amazing app</title>
    <!-- Localization -->
    <link rel="resource" type="application/l10n" href="locales/locales.ini" />
    <script src="js/l10n.js"></script>

3. HTML code changes

For each element that you want to have a translated text for, add the data-l10n-id attribute:

<p data-l10n-id="winter-for-real">Winter for real</p>

The value chosen for the data-l10n-id attribute needs to correspond to the same value in the app.properties file for each language, e.g: winter-for-real = Winter for real in the locales/en-US/app.properties file:

winter-for-real = Winter for real

How to view different locales

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


To give you a quick start in adding localization to your app, we have created a blueprint app called TranslationTester that you are free to copy/fork and use.

If you go to https://robnyman.github.io/TranslationTester/ in your web browser or add it as an app in WebIDE (Tools > Web Developer > WebIDE in Firefox) you can test it out right away.

If you plan on testing in WebIDE, these are your two options:

Getting help with translations

Optionally, you can set up your project for localization at Transifex to accept and import translations from other people. More on that in App Localization with Transifex.

Document Tags and Contributors

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