Bootstrapping a new locale

  • Revision slug: Bootstrapping_a_New_Locale
  • Revision title: Bootstrapping a new locale
  • Revision id: 78178
  • Created:
  • Creator: sethb@mozilla.com
  • Is current revision? No
  • Comment 1 words added, 2 words removed

Revision Content

In Mozilla, we use the the Mercurial version control system (Hg) to help manage our localizations. When a localization team becomes "official" 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 path on your terminal.  (You should "cd" to the directory before beginning.) 

In the path, type the following command:

$hg clone http://hg.mozilla.org/releases/mozilla-x.x.x/

Where "x.x.x" is the existing release branch version.  For instance, for Firefox 3.6, we use ~/mozilla-1.9.2/

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 just 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.
mkdir -p ab-CD/browser/installer ab-CD/browser/profile/chrome ab-CD/browser/searchplugins ab-CD/browser/updater ab-CD/toolkit
cp mozilla-1.9.x/browser/locales/en-US/ ab-CD/browser
cp mozilla-1.9.x/dom/locales/en-US/ ab-CD/dom
cp mozilla-1.9.x/editor/locales/en-US/ ab-CD/editor
cp mozilla-1.9.x/extensions/reporter/locales/en-US/chrome ab-CD/extensions
cp mozilla-1.9.x/netwerk/locales/en-US/ ab-CD/netwerk
cp mozilla-1.9.x/other-licenses/branding/firefox/locales/en-US/ ab-CD/other-licenses
cp mozilla-1.9.x/security/manager/locales/en-US/ ab-CD/security
cp 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                   pageInfo.properties aboutPrivateBrowsing.dtd    pageReportFirstTime.dtd
aboutRobots.dtd            places aboutSessionRestore.dtd                 preferences aboutSupport.dtd                    quitDialog.properties
baseMenuOverlay.dtd        safeMode.dtd browser.dtd                       safebrowsing browser.properties                 sanitize.dtd
credits.dtd                search.properties engineManager.dtd            searchbar.dtd engineManager.properties          setDesktopBackground.dtd
feeds                      shellservice.properties history                sidebar migration                               tabbrowser.dtd
openLocation.dtd           tabbrowser.properties openLocation.properties

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:

mozilla-1.9.x/browser/locales/en-US/ 
mozilla-1.9.x/dom/locales/en-US/ 
mozilla-1.9.x/netwerk/locales/en-US/
mozilla-1.9.x/other-licenses/branding/firefox/locales/en-US 
mozilla-1.9.x/security/manager/locales/en-US/ 
mozilla-1.9.x/toolkit/locales/en-US/

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

~/ab-CD/browser/ 
~/ab-CD/dom/ 
~/ab-CD/netwerk/ 
~/ab-CD/other-licenses/branding/firefox/ 
~/ab-CD/security/manager/
~/ab-CD/toolkit/ 

Translating

To start editing, you will need a text editing application like Text Wrangler.  After you have downloaded your editor of choice, type the following command in the same path from above (~/ab-CD/browser/chrome/browser)

$open aboutCertError.dtd -a [your text editing application's name like TextWrangler]

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:

$<!-- LOCALIZATION NOTES... -->

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 (i.e., "the content within the quotation marks").  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]/browser/locales/en-US/

Recommended Order of Localization

The following "phase list" provides a very rough guide on where to start and how to proceed through localizing.

http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phaselist?view= markup

with a description of the phases here:

http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phases?view= markup

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 lcoalizers comfortable with the Hg commands that allow for pulling, cloning, 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 interesting in starting a localization.  The l10n-drivers will help set up an experimental Hg repository in Bit Bucket.

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

$  https://bitbucket.org/mozillal10n/ab-CD/overview/

(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 http://bitbucket.org/mozillal10n/ab-CD/ ...
$ 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 http://bitbucket.org/mozillal10n/ab-CD/

Prefer SSH?

$ hg clone ssh://hg@bitbucket.org/mozillal10n/ab-CD/
$ hg push ssh://hg@bitbucket.org/mozillal10n/ab-CD/

As you begin to move through your translations, you should "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/browser/
$ hg push http://bitbucket.org/mozillal10n/ab-CD/

Revision Source

<p>In Mozilla, we use the the Mercurial version control system (Hg) to help manage our localizations. When a localization team becomes "official" 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.</p>
<h2>Installing Mercurial</h2>
<p>Depending on your operating system, you will need to install the correct version of Hg on your machine.  <a href="/en/Installing_Mercurial" title="https://developer.mozilla.org/en/Installing_Mercurial">This document</a> will give you the basic information on how to do that.</p>
<h2>Install the compare-locales utility</h2>
<p>The next step is to install <code>compare-locales</code>.</p>
<pre>sudo easy_install compare-locales
</pre>
<p>This will download and install the utility.</p>
<h2>Clone the source code</h2>
<p>The next step is to <a class="internal" href="../../../../En/Developer_Guide/Source_Code/Mercurial" rel="internal">download a copy of the source code</a> to your local system, using Mercurial.  You will need to "hg clone" the existing release branch for Mozilla<br>
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 path on your terminal.  (You should "cd" to the directory before beginning.) </p>
<p>In the path, type the following command:</p>
<pre>$hg clone http://hg.mozilla.org/releases/mozilla-x.x.x/</pre>
<p>Where "x.x.x" is the existing release branch version.  For instance, for Firefox 3.6, we use ~/mozilla-1.9.2/</p>
<p>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 <a href="../../../../En/Developer_Guide/Source_Code/Getting_comm-central" rel="internal">getting the source-code of the comm-central repository</a>.</p><h2>Create a bare-bones localization</h2>
<p>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 <a class="external" href="http://www.w3.org/WAI/ER/IG/ert/iso639.htm" title="http://www.w3.org/WAI/ER/IG/ert/iso639.htm">ISO 639 language code</a>, and CD is the <a class="external" href="http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm" title="http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm">ISO 3166 country code</a>.  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.</p>
<p>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.</p>
<div class="warning"><strong>Warning:</strong> Don't just 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.</div>
<pre>mkdir -p ab-CD/browser/installer ab-CD/browser/profile/chrome ab-CD/browser/searchplugins ab-CD/browser/updater ab-CD/toolkit
cp mozilla-1.9.x/browser/locales/en-US/ ab-CD/browser
cp mozilla-1.9.x/dom/locales/en-US/ ab-CD/dom
cp mozilla-1.9.x/editor/locales/en-US/ ab-CD/editor
cp mozilla-1.9.x/extensions/reporter/locales/en-US/chrome ab-CD/extensions
cp mozilla-1.9.x/netwerk/locales/en-US/ ab-CD/netwerk
cp mozilla-1.9.x/other-licenses/branding/firefox/locales/en-US/ ab-CD/other-licenses
cp mozilla-1.9.x/security/manager/locales/en-US/ ab-CD/security
cp mozilla-1.9.x/toolkit/locales/en-US/ ab-CD/toolkit</pre>
<h2>Getting started</h2>
<p>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:</p>
<pre>$cd [ab-CD]/browser/chrome/browser</pre>
<p>To see what is contained in "browser" type</p>
<pre>$ls</pre>
<p>And, you should see the following output from your terminal:</p>
<pre>aboutCertError.dtd         pageInfo.dtd aboutDialog.dtd                   pageInfo.properties aboutPrivateBrowsing.dtd    pageReportFirstTime.dtd
aboutRobots.dtd            places aboutSessionRestore.dtd                 preferences aboutSupport.dtd                    quitDialog.properties
baseMenuOverlay.dtd        safeMode.dtd browser.dtd                       safebrowsing browser.properties                 sanitize.dtd
credits.dtd                search.properties engineManager.dtd            searchbar.dtd engineManager.properties          setDesktopBackground.dtd
feeds                      shellservice.properties history                sidebar migration                               tabbrowser.dtd
openLocation.dtd           tabbrowser.properties openLocation.properties</pre>
<p>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.</p>
<h2>Directories to localize</h2>
<p>If you're starting from scratch, you should have just downloaded:</p>
<pre>mozilla-1.9.x/browser/locales/en-US/ 
mozilla-1.9.x/dom/locales/en-US/ 
mozilla-1.9.x/netwerk/locales/en-US/
mozilla-1.9.x/other-licenses/branding/firefox/locales/en-US 
mozilla-1.9.x/security/manager/locales/en-US/ 
mozilla-1.9.x/toolkit/locales/en-US/</pre>
<p>And then copied them so that the files for localization end up in the following directories:</p>
<pre>~/ab-CD/browser/ 
~/ab-CD/dom/ 
~/ab-CD/netwerk/ 
~/ab-CD/other-licenses/branding/firefox/ 
~/ab-CD/security/manager/
~/ab-CD/toolkit/ </pre><h2>Translating</h2>
<p>To start editing, you will need a text editing application like <a class=" external" href="http://www.barebones.com/products/TextWrangler/" title="http://www.barebones.com/products/TextWrangler/">Text Wrangler</a>.  After you have downloaded your editor of choice, type the following command in the same path from above (~/ab-CD/browser/chrome/browser)</p>
<pre>$open aboutCertError.dtd -a [your text editing application's name like TextWrangler]</pre>
<p>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:</p>
<pre>$&lt;!-- LOCALIZATION NOTES... --&gt;</pre>
<p>After the localization notes, you will see a list of &lt;!ENTITY&gt; strings like the following:</p>
<pre>$&lt;!ENTITY certerror.pagetitle  "Untrusted Connection"&gt;</pre>
<p>You should go through each entity, translating  the value in the parameters (i.e., "the content within the quotation marks").  Once you have translated all the &lt;!ENTITY&gt; 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]/browser/locales/en-US/</p><h2>Recommended Order of Localization</h2>
<p>The following "phase list" provides a very rough guide on where to start and how to proceed through localizing.</p>
<p><a href="/http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phaselist?view= markup" title="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phaselist?view= markup">http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phaselist?view= markup</a></p>
<p>with a description of the phases here:</p>
<p><a href="/http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phases?view= markup" title="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phases?view= markup">http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/phases?view= markup</a></p>
<p>Land your translated files one by one, making sure it follows the *mozilla-1.9.2* structure.  This will familiarize you with our "Hg"<br>
commands and will get us something that we can import easily when you are done.</p>
<h2>Working with Bit Bucket</h2>
<p>Before a team becomes official, we like to get the lcoalizers comfortable with the Hg commands that allow for pulling, cloning, and pushing work to an experimental repository.  We use a web service called <a class=" external" href="http://www.bitbucket.org" title="http://www.bitbucket.org/">Bit Bucket</a> to start the learning process.</p>
<p>To begin, contact the l10n-drivers to let them know that you are interesting in starting a localization.  The l10n-drivers will help set up an experimental Hg repository in Bit Bucket.</p>
<p>After your new Bit Bucket repository is created by the l10n-drivers, pleae visit the URL for your repo.  You can do this by entering the following URL into your browser:</p>
<pre>$  https://bitbucket.org/mozillal10n/ab-CD/overview/</pre>
<p>(where ab-CD will be replaced by your locale code)</p>
<p>At that main page of your newly created Bit Bucket repo, you'll see the Hg commands,</p>
<pre style="margin-left: 40px;">$ hg clone http://bitbucket.org/mozillal10n/ab-CD/ ...
$ hg pull -u # to pull changes and update 
$ hg push # to push changes to this repo
</pre>
<p style="margin-left: 40px;"><em>Import existing data?</em></p>
<pre style="margin-left: 40px;">$ cd /path/to/existing/hg/repo/ 
$ hg push http://bitbucket.org/mozillal10n/ab-CD/</pre>
<p style="margin-left: 40px;"><em>Prefer SSH?</em></p>
<pre style="margin-left: 40px;">$ hg clone ssh://hg@bitbucket.org/mozillal10n/ab-CD/
$ hg push ssh://hg@bitbucket.org/mozillal10n/ab-CD/</pre>
<p>As you begin to move through your translations, you should "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 </p>
<pre style="margin-left: 40px;">$ cd ~/ab-CD/browser/
$ hg push http://bitbucket.org/mozillal10n/ab-CD/
</pre>
Revert to this revision