This article needs a technical review. How you can help.

In this guide, we'll show you how easy it can be to localize Firefox OS, specifically the Gaia interface and apps. We'll start by helping you set up your computer, walk you through how to localize Gaia strings, and finally how to perform l10n testing on your work.

Note: This is a guide for localizers wanting to help localize Firefox OS. Developers wanting to write localizable apps should start with Localizing Firefox OS Apps, and then check out L10n best practices.

Gathering your tools

In order to be able to get Gaia's source files and test your localization on your desktop, you'll need to make sure your desktop has the following utilities and languages installed on it:

GNU make
make is a useful little tool for creating builds from source code. It will come in handy when you're ready to test your l10n work on your desktop. Downloading and installing make is easy and can be done directly from GNU's website. If you are using OS X, you'll need to install XCode and XCode's Command line tools from the App Store.
git is the version control system used to store the actively developed Gaia source code. Downloading and installing git is easy and can be done directly from their website.
Python is a programming language that will also help you with creating Firefox OS builds for l10n testing. Downloading and installing Python is easy and can be done directly from their website.
Mercurial (hg)
Mercurial (hg) is another version control system that houses stable versions of Gaia used for l10n, as well as locale repositories. Downloading and installing Mercurial is easy and can be done directly from their website.
compare-locales is a Python script that helps localizers to evaluate their work and seperate new content to localize from already localized material (called a diff). Downloading and installing compare-locales is easy and can be done directly from the compare-locales wiki page. Please note that this is only necessary if you are localizing Gaia using only the command line or a text editor. If you are using a tool like Pootle, Transifex, or Pontoon, you do not need this.

Setting up a local repo

Once you've made sure to download and install the software from the list above, it's time to get the source and localized strings onto your desktop.

  1. In your command line utility, navigate to the location where you will store the Gaia source and localized strings.
  2. Using hg, clone the en-US repo into the default location by entering the first command seen below.
    hg clone
  3. Now clone your locale's repo using a command with the below structure. As an example, the second line provides an example of cloning the traditional Chinese repo into a suitable directory.
    hg clone
    hg clone B2G/gaia/locales/zh-TW
  4. Now run the following command:
    LOCALE_BASEDIR=locales/ LOCALES_FILE=locales/languages_mine.json make

locale files should be listed in the languages_mine.json file, which will adopt a structure something like this:

  "en-US" : "English (US)",
  "fr" : "Français (fr)"

In this file you should have a list of strings ready for you to translate! Please note that if you're starting a new localization of Firefox OS, you do not need to create a diff as all strings are new strings to be translated.

Note: Refer to this gist for a locale build automation script.


Translating Gaia strings

The workflow for translating Gaia strings largely depends upon the tools you're using to translate. This part of the process is similar to the regular translation phase for other Mozilla products. The Translation Phase page of the Localization Quick Start Guide contains a list of all the tools used to translate strings within Mozilla products along with tutorials on how to translate with those tools. This page will be useful to you whether you're part of a l10n team trying to decide what tool to use to translate Gaia strings or you're looking for the right tutorial for the tool your team currently uses.

L10n testing for Firefox OS

There are two main methods for performing l10n testing on Firefox OS: desktop builds and mobile builds. Currently, the desktop method is the most widely used method for l10n testing.

Desktop l10n testing

  1. Download and install the latest boot2gecko nightly desktop build — download the package that corresponds to your operating system. Look for the packages that contain the word localizer in them. This indicates that the build has all of the locales listed on languages-all.json enabled.
  2. Clone the latest version of Gaia by navigating to the directory on your desktop where you would like it to download and entering this command in the command line utility: git clone git://
  3. If your team is localizing Firefox OS for the first time, you'll need to enable your locale. If not, grab yourself a drink while everyone else enables their locale.
    1. While in the command line, navigate inside your gaia clone and run this command to clone your locale's repo: hg clone ssh://
    2. Open the languages.json file located in the shared/resources directory in the gaia repository you just cloned.
    3. Add your locale information according to this format: "en-US" : "English (US)", and save the file.
    4. Finally, run the command: make multilocale This enables your locale on your desktop build.
  4. Create your Gaia profile by running this command: DEBUG=1 make -C gaia profile
  5. Finally, you can run Firefox OS with your locale profile and begin testing. Do this by entering this command: b2g/b2g -profile gaia/profile. If you're using OS X, run this command: /Applications/ -profile gaia/profile
  6. To update your desktop builds, simply navigate to your Gaia repo clone and enter this command: git pull

Mobile l10n testing

This section will grow as more devices that support Firefox OS become available to localizers.

What to look for when l10n testing

Localization testing for a mobile operating system has some similarites to localization testing for a desktop application. Here are some guidelines on what to look for when performing localization testing on your work:

  1. See if your translations fit inside UI text elements.
  2. Ensure that the tone, style, and terminology are consistant throughout the entire product.
  3. Look for untranslated English strings in the UI. These may be hard-coded into Gaia or they may caused by element ID errors.
  4. Make sure that time and dates display according your regions standards.

Finding localization-specific bugs

Here are some links to bugzilla in order to give you examples of bugs that have been encountered while using the phones. This will give you an idea of where to look at for bugs as well as an example in filing these kinds of bugs.

General rules when filing a Localization bug:

  • if the bug is specific to the language, then file under the Mozilla Localization (under Other Products) and cc the localizer. Don't forget to flag your bug with the appropriate tracking flag
  • if it's not specific to the language, file under FirefoxOS Product, and cc the localizer. Don't forget to flag your bug with the appropriate tracking flag
  • If you are in doubt, file under FirefoxOS Product, and cc the localizer. Don't forget to flag your bug with the appropriate tracking flag

For those of you who use Moztrap, looking at the existing test cases under the FirefoxOS "localization" tags and seeing if you can pass the tests on your device is also a good way to test Firefox OS localizations.

What's next?

Now you're ready to start localizing! So open up your favorite l10n tool and go for it! As always, if you have questions that are not covered in this document, please send them to the newsgroup.

Document Tags and Contributors

 Contributors to this page: Superluk, chrisdavidmills, xfq, SunboX, AxelHecht, delphine, jbeatty
 Last updated by: Superluk,