Localizing without a specialized tool

  • Revision slug: Localizing_without_a_specialized_tool
  • Revision title: Localizing without a specialized tool
  • Revision id: 66008
  • Created:
  • Creator: sethb@mozilla.com
  • Is current revision? No
  • Comment no wording changes

Revision Content

From the Create a New Localization document, an interested localizer can follow a technical step-by-step process that starts the localization process by focusing on how to localize two of the primary types of localization files (DTD and property) used in the Mozilla source code.  With that document, users can see immediately two localized files in their user interface by following closely and carefully the steps to create a language pack or a binary file that is ready for installation.  Repeating the process allows a localizer to create a testable package to see his or her work as they progress to a final version.

If you choose to localize Mozilla with nothing more than a text editing application and not a specialized tool, this document (along with Create a New Localization) will enable you to learn just what needs to be done.

Before we start, did you make sure to install Mercurial and confirm that you have set up the proper build environment on your local machine?  You cannot begin localizing Mozilla file by file without a specialized tool without going through the Create a New Localization page.

Getting Started with Compare-Locales

You are going to need to create the structure of your localization, where, one-by-one, each of the files needing localization will be copied.  This directory structure needs to mimic the same as the en-US source files concerning localization. You will use a tool called compare-locales to do the comparison between your locale's files and the en-US reference.

First, install compare-locales. You can follow more detailed guidelines on compare-locale's page, but running the following command from the command line should be enough:

$ sudo easy_install -U compare-locales

To start, be sure to open your command line interface and change your directory to where you are keeping your localization files, the en-US sources

$ cd /path/to/your/working/directory  

Now, you will need run compare locales and save the output in a text file on your Desktop so you can review it as you go.  To do this, enter the following commands, keeping sure to change "path/to/mozilla-1.9.2", "path/to/l10n_base/", and "ab-CD", where l10n_base is where you store the locales you are working on and "ab-CD" is the actual locale code of your locale.

$ compare-locales path/to/mozilla-1.9.2/.../l10n.ini pathto/l10n_base/ ab-CD
$ compare-locales mozilla-1.9.2/browser/locales/l10n.ini l10n-mozilla-1.9.2 ab-CD > ~/Desktop/ab-CD.compare

Open the ab-CD.compare file that is on your desktop.  You should see something like this:

ab-CD
  browser
    chrome
      browser
        .DS_Store
            // add and localize this file
        aboutCertError.dtd
            // add and localize this file
        aboutDialog.dtd
            +aboutLink
            +aboutLink.accesskey
            +aboutVersion
            +closeCmdGNOME.accesskey
            +closeCmdGNOME.label
            +copyright
            +copyright.accesskey
            +copyrightGNOME.accesskey
            +copyrightInfo1
            +copyrightInfo2
            +licenseLink
            +licenseLinkText
        aboutPrivateBrowsing.dtd
            // add and localize this file
        aboutRobots.dtd
            // add and localize this file
        ...
        ...
        ...
ab-CD:
unchanged: 2
changed: 3
missingInFiles: 6117
missing: 13
0% of entries changed

The beauty of the compare-locales output is that it tells you all the missing files and which files you need to add and localize.  This will be your guide to localize Firefox.

Localizing Step-by-Step

DTD files

In order to provide an example that can be viewed quickly in your UI, we'll start by translating a DTD file (often called an entity) named searchbar.dtd that contains the string "Manage Search Engines...".  "Manage Search Engines..." can easily be found in the Firefox browser UI by clicking on the drop-down arrow in the search box in the upper-right corner of your browser.  At the bottom of the list of search engines that appears, you'll see, "Manage Search Engines...".

To start, make sure you are in

/path/to/your/working/directory/ab-CD

And then, type the command

mkdir /browser/chrome/browser

Now, copy the file by typing

cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/searchbar.dtd ab-CD/browser/chrome/browser/searchbar.dtd

Open the file in your ab-CD directory and translate the words inside the quotation marks.  Be sure to only translate what is in the quotation marks.

<!ENTITY cmd_engineManager.label        "Manage Search Engines...">

Property Files

The property file "search.properties" contains the string "Add %S".  This string can easily be found in the browser UI by visiting a website that provides a search plugin (like http://developer.mozilla.org/) and clicking on the drop-down arrow in the search box in the upper-right corner of your browser.  At the second to bottom of the list of search engines that appears, you'll see, "Add %S", where %S is replaced by the name of the site.

Again, to start, make sure you are in

/path/to/your/working/directory/ab-CD

Now, step back out to the broader directory that contains both your working directory and the en-US source code.  You can do this by typing:

cd ../../  

where each ".." represents the prior sub directory before the main directory where you want to be.  You can always check the path by typing

pwd

Once you are in the main directory with both en-US source and the working directory, copy the file by typing

cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/search.properties l10n-mozilla-1.9.2/ab-CD/browser/chrome/browser/search.properties

Open that file and translate the strings that follow the "=".  For instance, enter the proper translation for the line "Add %S"

cmd_addFoundEngine=Add "%S"

With these two string examples translated, you can now test your work to see immediately where you have translated.  Click to see how to build and .XPI file to test your work.

Going one-by-one

With your compare-locales output open for review, we will start with the first file with "// add and localize this file" note.  You should see

 // add and localize this file
        aboutCertError.dtd

Notice from the compare-locales output that this file is located in the directory /browser/chrome/browser.  You will want to copy this file from the en-US sources into the proper ab-CD directory. To do this, you first need to create the directory structure and then copy the file into it.  Type the command

pwd

Again, make sure you are in

/path/to/your/working/directory/ab-CD

And then type the command

mkdir /browser/chrome/browser

Now, copy the file by typing

cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/aboutCertError.dtd ab-CD/browser/chrome/browser/aboutCertError.dtd

You should now see the aboutCertError.dtd file in that newly created directory.  Your compare locales output follows the exact nested source structure.  Each time you see a directory or set of sub-directories, you will need to run the mkdir command inside your locale directory and then copy the .dtd or property files into that directory.

Translating

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:

<!-- 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 (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.

Recommended order of localization

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.

Revision Source

<p>From the <a href="/User:stasm/Create_a_new_localization" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization">Create a New Localization</a> document, an interested localizer can follow a technical step-by-step process that starts the localization process by focusing on how to localize two of the primary types of localization files (DTD and property) used in the Mozilla source code.  With that document, users can see immediately two localized files in their user interface by following closely and carefully the steps to <a href="/User:stasm/Create_a_new_localization#Creating_a_langpack" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization#Creating_a_langpack">create a language pack</a> or <a href="/User:stasm/Create_a_new_localization#Repacking_the_binary" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization#Repacking_the_binary">a binary file</a> that is ready for installation.  Repeating the process allows a localizer to create a testable package to see his or her work as they progress to a final version.</p>
<p>If you choose to localize Mozilla with nothing more than a text editing application and not a specialized tool, this document (along with <a href="/User:stasm/Create_a_new_localization" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization">Create a New Localization</a>) will enable you to learn just what needs to be done.</p>
<p>Before we start, did you make sure to <a href="/User:stasm/Create_a_new_localization#Install_Mercurial_on_Windows" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization#Install_Mercurial_on_Windows">install Mercurial</a> and confirm that you have <a href="/User:stasm/Create_a_new_localization#System_environment_requirements" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization#System_environment_requirements">set up the proper build environment</a> on your local machine?  You cannot begin localizing Mozilla file by file without a specialized tool without going through the <a href="/User:stasm/Create_a_new_localization" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization">Create a New Localization</a> page.</p>
<h2>Getting Started with Compare-Locales</h2>
<p>You are going to need to create the structure of your localization, where, one-by-one, each of the files needing localization will be copied.  This directory structure needs to mimic the same as the en-US source files concerning localization. You will use a tool called compare-locales to do the comparison between your locale's files and the en-US reference.</p>
<p>First, install compare-locales. You can follow <a href="/en/compare-locales" title="en/compare-locales">more detailed guidelines on compare-locale's page</a>, but running the following command from the command line should be enough:</p>
<pre>$ sudo easy_install -U compare-locales
</pre>
<p>To start, be sure to open your command line interface and change your directory to where you are keeping your localization files, the en-US sources</p>
<pre>$ cd /path/to/your/working/directory  </pre>
<p>Now, you will need run compare locales and save the output in a text file on your Desktop so you can review it as you go.  To do this, enter the following commands, keeping sure to change "path/to/mozilla-1.9.2", "path/to/l10n_base/", and "ab-CD", where l10n_base is where you store the locales you are working on and "ab-CD" is the actual locale code of your locale.</p>
<pre>$ compare-locales path/to/mozilla-1.9.2/.../l10n.ini pathto/l10n_base/ ab-CD
$ compare-locales mozilla-1.9.2/browser/locales/l10n.ini l10n-mozilla-1.9.2 ab-CD &gt; ~/Desktop/ab-CD.compare
</pre>
<p>Open the ab-CD.compare file that is on your desktop.  You should see something like this:</p>
<pre>ab-CD
  browser
    chrome
      browser
        .DS_Store
            // add and localize this file
        aboutCertError.dtd
            // add and localize this file
        aboutDialog.dtd
            +aboutLink
            +aboutLink.accesskey
            +aboutVersion
            +closeCmdGNOME.accesskey
            +closeCmdGNOME.label
            +copyright
            +copyright.accesskey
            +copyrightGNOME.accesskey
            +copyrightInfo1
            +copyrightInfo2
            +licenseLink
            +licenseLinkText
        aboutPrivateBrowsing.dtd
            // add and localize this file
        aboutRobots.dtd
            // add and localize this file
        ...
        ...
        ...
ab-CD:
unchanged: 2
changed: 3
missingInFiles: 6117
missing: 13
0% of entries changed
</pre>
<p>The beauty of the compare-locales output is that it tells you all the missing files and which files you need to add and localize.  This will be your guide to localize Firefox.</p><h2>Localizing Step-by-Step</h2>
<h3>DTD files</h3>
<p>In order to provide an example that can be viewed quickly in your UI, we'll start by translating a DTD file (often called an entity) named <em> searchbar.dtd</em> that contains the string "Manage Search Engines...".  "Manage Search Engines..." can easily be found in the Firefox browser UI by clicking on the drop-down arrow in the search box in the upper-right corner of your browser.  At the bottom of the list of search engines that appears, you'll see, "Manage Search Engines...".</p>
<p><img alt="" class="internal" src="/@api/deki/files/4018/=Manage_Search_Engines....png" style="width: 268px; height: 308px;"></p>
<p>To start, make sure you are in</p>
<pre>/path/to/your/working/directory/ab-CD</pre>
<p>And then, type the command</p>
<pre>mkdir /browser/chrome/browser</pre>
<p>Now, copy the file by typing</p>
<pre>cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/searchbar.dtd ab-CD/browser/chrome/browser/searchbar.dtd</pre>
<p>Open the file in your ab-CD directory and translate the words inside the quotation marks.  Be sure to only translate what is in the quotation marks.</p>
<pre><code>&lt;!ENTITY cmd_engineManager.label        "Manage Search Engines..."&gt;</code>
</pre>
<h3>Property Files</h3>
<p>The property file "search.properties" contains the string "Add %S".  This string can easily be found in the browser UI by visiting a website that provides a search plugin (like <a class=" external" href="http://developer.mozilla.org/" rel="external
nofollow" target="_blank" title="http://developer.mozilla.org/">http://developer.mozilla.org/</a>) and clicking on the drop-down arrow in the search box in the upper-right corner of your browser.  At the second to bottom of the list of search engines that appears, you'll see, "Add %S", where %S is replaced by the name of the site.</p>
<p><img alt="" class="internal" src="/@api/deki/files/4019/=Add_%2525S.png" style="width: 259px; height: 279px;"></p>
<p>Again, to start, make sure you are in</p>
<pre>/path/to/your/working/directory/ab-CD
</pre>
<p>Now, step back out to the broader directory that contains both your working directory and the en-US source code.  You can do this by typing:</p>
<pre>cd ../../  
</pre>
<p>where each ".." represents the prior sub directory before the main directory where you want to be.  You can always check the path by typing</p>
<pre>pwd
</pre>
<p>Once you are in the main directory with both en-US source and the working directory, copy the file by typing</p>
<pre>cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/search.properties l10n-mozilla-1.9.2/ab-CD/browser/chrome/browser/search.properties</pre>
<p>Open that file and translate the strings that follow the "=".  For instance, enter the proper translation for the line "Add %S"</p>
<pre>cmd_addFoundEngine=Add "%S"
</pre>
<p>With these two string examples translated, you can now test your work to see immediately where you have translated.  <a href="/User:stasm/Create_a_new_localization#Creating_a_langpack" title="https://developer.mozilla.org/User:stasm/Create_a_new_localization#Creating_a_langpack">Click to see how to build and .XPI file to test your work</a>.</p><h3>Going one-by-one</h3>
<p>With your compare-locales output open for review, we will start with the first file with "// add and localize this file" note.  You should see</p>
<pre> // add and localize this file
        aboutCertError.dtd
</pre>
<p>Notice from the compare-locales output that this file is located in the directory /browser/chrome/browser.  You will want to copy this file from the en-US sources into the proper ab-CD directory. To do this, you first need to create the directory structure and then copy the file into it.  Type the command</p>
<pre>pwd
</pre>
<p>Again, make sure you are in</p>
<pre>/path/to/your/working/directory/ab-CD</pre>
<p>And then type the command</p>
<pre>mkdir /browser/chrome/browser
</pre>
<p>Now, copy the file by typing</p>
<pre>cp -R mozilla-1.9.2/browser/locales/en-US/chrome/browser/aboutCertError.dtd ab-CD/browser/chrome/browser/aboutCertError.dtd</pre>
<p>You should now see the aboutCertError.dtd file in that newly created directory.  Your compare locales output follows the exact nested source structure.  Each time you see a directory or set of sub-directories, you will need to run the mkdir command inside your locale directory and then copy the .dtd or property files into that directory.</p><h2>Translating</h2>
<p>To start editing, you will need a text editing application. You can choose to use:</p>
<ul> <li><a class=" external" href="http://notepad-plus.sourceforge.net/uk/site.htm" title="http://notepad-plus.sourceforge.net/uk/site.htm">Notepad++</a> or <a class=" external" href="http://www.flos-freeware.ch/notepad2.html" title="http://www.flos-freeware.ch/notepad2.html">Notepad2</a> on Windows,</li> <li><a class=" external" href="http://en.wikipedia.org/wiki/Vim_%28text_editor%29" title="http://en.wikipedia.org/wiki/Vim_(text_editor)">vim</a>, <a class=" external" href="http://projects.gnome.org/gedit/" title="http://projects.gnome.org/gedit/">gedit</a> or <a class="    external" href="http://www.kate-editor.org/kate" title="http://www.kate-editor.org/kate">Kate</a> on GNU/Linux,</li> <li><a class=" external" href="http://www.barebones.com/products/TextWrangler/" title="http://www.barebones.com/products/TextWrangler/">TextWrangler</a> on Mac OS X.</li>
</ul>
<p><span style="font-size: x-small;">(Read more about tools at </span><a class=" link-https" href="https://wiki.mozilla.org/L10n:Tools" title="https://wiki.mozilla.org/L10n:Tools"><span style="font-size: x-small;">L10n:Tools</span></a><span style="font-size: x-small;">.)</span></p>
<p>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>$ edit ab-CD/browser/chrome/browser/aboutCertError.dtd</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 <code>&lt;!ENTITY&gt;</code> 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 (e.g. <code>Untrusted Connection</code> in the example above), like so (example for Polish):</p>
<pre>&lt;!ENTITY certerror.pagetitle  "Niezaufane połączenie"&gt;</pre>
<p>Once you have translated all the <code>&lt;!ENTITY&gt;</code> 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.</p>
<h2>Recommended order of localization</h2>
<p>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.</p>
<ul> <li><a class=" external" href="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/" title="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/">The localization phase lists</a> (Firefox 3.5: <a class=" external" href="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/ff35.phaselist?view=markup" title="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/ff35.phaselist?view=markup">ff35.phaselist</a>, Firefox 3.6: <a class=" external" href="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/ff36.phaselist?view=markup" title="http://zaf.svn.sourceforge.net/viewvc/zaf/trunk/po/fftb/ff36.phaselist?view=markup">ff36.phaselist</a>).</li> <li><a class=" external" 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">Description of phases.</a></li>
</ul>
<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>
Revert to this revision