Bootstrapping a new locale

(see also

The documentation here is no longer being maintained and is inaccurate. L10n documentation has moved to . To learn how to bootstrap a new locale for Mozilla projects, please see those documents.

In Mozilla, we use the the Mercurial version control system (Hg) to help manage our localizations. When a localization team is registered and your Hg repository is set up for a locale, you can then clone the existing Mozilla release branch (i.e. where active development of the upcoming release of Firefox occurs) and then begin the necessary work for translation.  Hg allows localizers to work locally on their machines and then "push" changes to their official Mozilla repository.

Installing Mercurial

Depending on your operating system, you will need to install the correct version of Hg on your machine.  This document will give you the basic information on how to do that.

Install the compare-locales utility

The next step is to install compare-locales.

$ sudo easy_install compare-locales

This will download and install the utility.

Clone the source code

The next step is to download a copy of the source code to your local system, using Mercurial.  You will need to "hg clone" the existing release branch for Mozilla
so you have all the files locally for you to begin localization.  Make sure to have the directory where you intend to work as the current path on your terminal.  (You should "cd" to the directory before beginning.) 

In the terminal, type the following command:

$ hg clone

Where "x.x.x" is the existing release branch version.  For instance, for Firefox 3.6, we use mozilla-1.9.2. Refer to L10n:Branches for the list of all branches.

If you are interested in localizing Thunderbird 3, SeaMonkey 2 or other Mozilla projects based on Gecko 1.9.1 you'll need to follow the instructions on getting the source-code of the comm-central repository.

Create a bare-bones localization

Next, create a base localization.  This is done by cloning the en-US (United States English) files into your localization.  First, you should specify your locale's language identifier in ab-CD format, where "ab" is the ISO 639 language code, and CD is the ISO 3166 country code.  The "-CD" part is only necessary to differentiate between versions of a language that are subtly different from country to country, such as in "en-US" and "en-GB" for United States English and British English.

Before you run the copy commands, you need to make the locale directory at the same level as the mozilla-1.9.x/ you just cloned from above.  Navigate to that level making sure you are *not* inside mozilla-1.9.x/ and then run the following commands.

Warning: Don't copy and paste these commands; you need to replace "ab-CD" with your language identifier first and 1.9.x with the most current release branch.  For instance, Firefox 3.6 is released from the 1.9.2 branch.
from now on may be needs some corrections, (see expected structure below $cd ab-CD/browser/chrome/browser)
may be needs $cp -R mozilla-1.9.x/browser/locales/en-US/ ab-CD and then $mv ab-CD/en-US  ab-CD/browser and the same for the others
the commands seems symbolic and not real ... see also structure expected more below. 
/editor/ is in 1.9.2 ?  netwerk not error ?

mkdir -p ab-CD/browser/installer ab-CD/browser/profile/chrome ab-CD/browser/searchplugins ab-CD/browser/updater ab-CD/toolkit
cp -R mozilla-1.9.x/browser/locales/en-US/ ab-CD/browser
cp -R mozilla-1.9.x/dom/locales/en-US/ ab-CD/dom
cp -R mozilla-1.9.x/editor/locales/en-US/ ab-CD/editor
cp -R mozilla-1.9.x/extensions/reporter/locales/en-US/chrome ab-CD/extensions
cp -R mozilla-1.9.x/netwerk/locales/en-US/ ab-CD/netwerk
cp -R mozilla-1.9.x/other-licenses/branding/firefox/locales/en-US/ ab-CD/other-licenses
cp -R mozilla-1.9.x/security/manager/locales/en-US/ ab-CD/security
cp -R mozilla-1.9.x/toolkit/locales/en-US/ ab-CD/toolkit

Getting started

Change your directory to the new working directory so you are in the ~/[your working directory]/[ab-CD]/ path and can start localizing. We'll first navigate to the directory called "browser" by running the following commands one after the other from your command line:

$ cd [ab-CD]/browser/chrome/browser

To see what is contained in "browser" type

$ ls

And, you should see the following output from your terminal:

aboutCertError.dtd         pageInfo.dtd aboutDialog.dtd          aboutPrivateBrowsing.dtd    pageReportFirstTime.dtd
aboutRobots.dtd            places aboutSessionRestore.dtd                 preferences aboutSupport.dtd          
baseMenuOverlay.dtd        safeMode.dtd browser.dtd                       safebrowsing                 sanitize.dtd
credits.dtd       engineManager.dtd            searchbar.dtd          setDesktopBackground.dtd
feeds             history                sidebar migration                               tabbrowser.dtd

As a localizer, you are responsible for localizing each of the ".dtd" and ".properties" in *all* of the sub-directories found in your ab-CD directory.

Directories to localize

If you're starting from scratch, you should have just downloaded:


And then copied them so that the files for localization end up in the following directories:



To start editing, you will need a text editing application. You can choose to use:

(Read more about tools at L10n:Tools.)

After you have downloaded your editor of choice, type the following command in the same path from above (~/ab-CD/browser/chrome/browser)

$ edit ab-CD/browser/chrome/browser/aboutCertError.dtd

Read the top of the file to get any context on how to translate contained in the notes written by the developers or l10n-drivers.  Localization notes will look like this:


After the localization notes, you will see a list of <!ENTITY> strings like the following:

<!ENTITY certerror.pagetitle  "Untrusted Connection">

You should go through each entity, translating  the value in the parameters (e.g. Untrusted Connection in the example above), like so (example for Polish):

<!ENTITY certerror.pagetitle  "Niezaufane połączenie">

Once you have translated all the <!ENTITY> strings in this file, you should save your work and open the next .dtd or .property file.  You will need to go through each and every file to in every directory in ab-CD.

For recommended order of localization, refer to the localization "phase list" which provides a very rough guide on where to start and in what order to proceed through translation.

Land your translated files one by one, making sure it follows the *mozilla-1.9.2* structure.  This will familiarize you with our "Hg"
commands and will get us something that we can import easily when you are done.

Working with Bit Bucket

Before a team becomes official, we like to get the localizers comfortable with the Hg commands that allow for cloning, pulling, committing, and pushing work to an experimental repository.  We use a web service called Bit Bucket to start the learning process.

To begin, contact the l10n-drivers to let them know that you are interested in starting a localization.  The l10n-drivers will help set up an experimental Hg repository in Bit Bucket. You will need to create an account so you can access the service.  Once you have that account, send the l10n-drivers the details to be added as a "writer".  With that level of authority, you will be able to push and pull and manage the repository remotely.  It will be just like working on Hg with Mozilla, yet you will use the Bit Bucket platform to start.

After your new Bit Bucket repository is created by the l10n-drivers, please visit the URL for your repo.  You can do this by entering the following URL into your browser:


(where ab-CD will be replaced by your locale code)

At that main page of your newly created Bit Bucket repo, you'll see the Hg commands,

$ hg clone ...
$ hg pull -u # to pull changes and update 
$ hg push # to push changes to this repo

Import existing data?

$ cd /path/to/existing/hg/repo/ 
$ hg push

Prefer SSH?

$ hg clone ssh://
$ hg push ssh://

As you begin to move through your translations, you should "commit" the changes locally and "push" your work to this experimental respository.  For instance, if you have finished translating all the .dtd and .property files in your ~/ab-CD/browser/ directory, then you should

$ cd ~/ab-CD/
$ hg status
$ hg commit -m "Translated browser/"
$ hg push

Note that due to the distributed nature of Hg, hg commit saves the changes locally, i.e. in the Hg repository on your computer. You can see the history of commits with hg log. After doing hg commit, you still need to send the changes to BitBucket. This is why you need to do hg push, which sends the already made commits to the remote repository ( in the example above).

After you have committed and pushed your initial translation, email the l10n-drivers team to let us know it's ready.

Set up for building

The next step is to create a .mozconfig file with the compile options for the localized build of Firefox, and to set up the object directory for the localized build.

cd mozilla-1.9.1
echo "mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/../fx-ab-DC" > .mozconfig
echo "ac_add_options --with-l10n-base=../" >> .mozconfig
echo "ac_add_options --disable-compile-environment" >> .mozconfig
echo "ac_add_options --enable-application=browser" >> .mozconfig
make -f configure

Create a language pack

First, we'll create a build directory. This sounds worse than it is, you won't need to actually build, but we'll need to setup something that looks like it. You're still in the l10n directory, right? We'll create build right next to it. The name of that directory doesn't really matter, so no reason to change it.

mkdir ../build
cd ../build

Now we'll set up a not-so-compile environment by calling configure. If you just checked out the localizable parts of en-US above, it will create a plethora of warnings No such file or directory, but no errors.

../mozilla/configure --disable-compile-environment --enable-application=browser

Whenever you need a build directory, these are the steps that you need to do to initialize it. If you're downloading a new release of Firefox from CVS, you might want to run configure again, too.

Now we can actually create the language pack,

make -C browser/locales langpack-en-X-dude

You should find your newly created language pack in dist/install.

ls dist/install

You can open that file in Firefox and check it out. You have to set your selected language still. You can either use the Locale Switcher extension, or set it in about:config. Set the general.useragent.locale to your language code, in this case, en-X-dude, and restart Firefox once more.