Localizing with Koala

Introduction

This tutorial will guide you through making a couple of changes to Firefox's user interface using Koala, an add-on for Komodo Edit created to help localizing Mozilla.

For the purposes of this tutorial, the locale code that we will use will be called "x-testing". In a real-life situation, that would become for example "de" (for German) or "es-ES" (for Spanish in Spain). Translating to x-testing will basically consist of converting any strings to uppercase, for example "File" in original version (en-US) will become "FILE" in x-testing.

We will translate a small piece of the UI found in the search bar. The search bar is next to the right of the location bar, and by default points to the Google search. If you click on the highlighted arrow pointing down while reading this tutorial on MDC, you will see two string that need to be translated:

• Add "MDC Search"
• Manage Search Engines...

There is also a tooltip that appears when you hover over the magnifying glass icon on the right side of the bar.

Requirements

• Mercurial,
• Linux, Windows or Mac OS X.

Instructions

Preparation

1. Install Komodo Edit.
2. Install Koala extension.
   1. Go to Tools > Add-ons.
   2. Search for "Koala".
   3. Click Add to Komodo Edit...
      
   4. Restart Komodo when the installation is complete.
   5. You should see a new button in Komodo's toolbar, with two options: Startpage and Management.
      
      Before you can use them, you need to create a new Koala project.

Creating a new project

1. Create a new Koala project by going to File > New > New Project From Template...
   1. Choose "koala" in the Categories list.
   2. Choose "koala" in the Templates list.
   3. Choose a name for your project (e.g. l10n.kpf).
   4. Choose the directory in which the project will live in (e.g. C:\mozilla\l10n on Windows, /home/user/mozilla/l10n on Linux or /Users/user/mozilla/l10n on Mac OS X).
      1. Due to a bug in Koala (bug 21930), it is recommended that you don't choose a path that contains spaces (like <strike>C:\Documents and Settings\user\...</strike>).
   5. Click "Open" to create the project.
   6. Koala will check for Mercurial. Make sure that your Mercurial installation is in your system's $PATH.
   7. Setup wizard will open.

Configure the Application

1. Choose "Firefox" as the application.
2. Version: 3.6.
3. Appname: browser.
4. Included locale: en-US (this is the original locale you're translating from).
5. Leave Location empty for now.
6. Check the "Mercurial" checkbox.
   1. Note that you don't have to edit the Location field, it automatically fills in when you check the "Mercurial" checkbox: "C:\mozilla\l10n\application\Firefox\3.6".
   2. URL: http://hg.mozilla.org/releases/mozilla-1.9.2.
   3. Branch: default.
   4. Revision: leave empty.
7. Click "OK".
8. Koala will now try to clone the en-US source repository from http://hg.mozilla.org/releases/mozilla-1.9.2. It's almost 1 GB worth of download, so it may take a while. Click "OK".
   
   

   On Windows, if Koala doesn't clone the repositories, you'll need to do it manually. The easy way involves opening the console and issuing the following commands:

   C:\Users\stas> cd C:\mozilla\l10n\application\Firefox
   C:\mozilla\l10n\application\Firefox> rmdir 3.6
   C:\mozilla\l10n\application\Firefox> hg clone http://hg.mozilla.org/releases/mozilla-1.9.2 3.6
   requesting all changes
   adding changesets
   adding manifests
   adding file changes
   added 33099 changesets with 158636 changes to 50664 files (+9 heads)
   updating working directory
   40357 files updated, 0 files merged, 0 files removed, 0 files unresolved

Configure the Locale

1. Locale ID: x-testing (put your locale's code)
2. Version: 3.6
3. Location: choose the folder where you want to keep the localized files or leave empty for now
4. Check "Mercurial" if you wish to use Mercurial to keep the revision history of your files (very recommended)
   1. Existing localizations: URL: if you're editing an existing localization or you already have a repository set up (either on hg.mozilla.org or BitBucket), type the URL of the remote repository, e.g. http://bitbucket.org/mozillal10n/x-testing or http://hg.mozilla.org/releases/l10n-....9.2/x-testing.
   2. New localizations: URL:
      1. If you already have a repository set up by l10n-drivers (on  BitBucket), type the URL of the remote repository, e.g. http://bitbucket.org/mozillal10n/x-testing.
      2. If you're starting a new localization, you may not have a remote repository set up yet. It is still recommended to use Mercurial locally to version your local files. Just type a single dot (".") in the URL field to enable Mercurial support in Koala.
   3. Branch: default.
   4. Revision: leave empty.
   5. User: type your name and your e-mail address in the form: "Firstname Lastname <me@example.com>" (be sure to type the wrapping quotes: "")
   6. Note that you no longer have to edit the location now, it automatically fills in when you check the "Mercurial" checkbox (e.g. "C:\mozilla\l10n\locale\x-testing\3.6"
5. If you enabled Mercurial (recommended), Koala will ask you if you wish to clone the remote repository. Click "OK" (even if you're creating a new localization and there is no remote repository).
   1. Existing localizations: if Koala fails to clone the remote repository, you will need to do it manually. Just open the console and issue the following commands:
      

      C:\Users\stas> cd C:\mozilla\l10n\locale\x-testing
      C:\mozilla\l10n\locale\x-testing> rmdir 3.6
      C:\mozilla\l10n\locale\x-testing> hg clone http://hg.mozilla.org/releases/l10n-mozilla-1.9.2/x-testing 3.6

   2. New localizations:
      1. If you have the BitBucket repository already set up by l10n-drivers, the steps are the same as above. Just hg clone from the right BitBucket URL. For example:
         

         C:\Users\stas> cd C:\mozilla\l10n\locale\x-testing
         C:\mozilla\l10n\locale\x-testing> rmdir 3.6
         C:\mozilla\l10n\locale\x-testing> hg clone http://bitbucket.org/mozillal10n/x-testing 3.6

      2. Otherwise, it's a good idea to create your local repository in order to be able to track changes you make to the localization files. To do this, open the console and type:
         

         C:\Users\stas> cd C:\mozilla\l10n\locale\x-testing\3.6
         C:\mozilla\l10n\locale\x-testing\3.6> hg init

6. You should now see the the Koala's starpage in Komodo. You are ready to start localizing Firefox!
   

Comparing and translating

Now that we have set up Koala to localize Firefox from en-US into x-testing, we can start translating the localization files. Koala features a very handy tool called compare-locales, which compares the files from en-US with your files in x-testing and gives you statistics about new, changed, missing and obsolete files and strings. Let's see how that works.

Running a comparison

1. Open Koala's start page.
2. Select Firefox (3.6) in Application column.
3. Select en-US (included) in Original Locale column.
4. Select x-testing (3.6) in User Locale column.
   The buttons on the right become active.
   
5. Click "Compare".
   A dialog will appear letting you know that Koala is comparing en-US with x-testing.
   
   
6. When the comparison is done, you should see a new line in "Last used compares" section of Koala's startpage. It's a handy shortcut to run the comparison in the future.
   
7. If the sidebar with the results of the comparison doesn't show up automatically:
   1. Open the Projects sidebar by choosing View > Tabs & Sidebars > Projects from the menu.
   2. Switch to "Koala file view" in the sidebar (choose it from the list that appears when you click on the arrow pointing down situated next to the sidebar's [x] button).
      
8. You should now see the results of the comparison in the "Koala file view" sidebar.
   

Translating files

Let's translate the searchbar-related strings mentioned in the beginning of this document. They can be found in two files, inside the browser/chrome/browser directory:

• searchbar.dtd,
• search.properties.

The difference between DTD and .properties files in the moment when they are used by the application. DTD's files are read by the XML parser, which goes through the XUL files used in Mozilla to create the interface when it launches. The .properties files are used in the JavaScript code while the application is already running. That's why the string "Add %s..." (where %s is replaced by the search engine's name, like 'MDC Search') is found in search.properties file. It has to be generated every time the user switches between pages. On the other hand, "Manage Search Engines..." is generated only once, on start-up, and doesn't need to change. Therefore, it is located in searchbar.dtd file.

Let's translate these strings now.

1. Type "search" in Koala file view sidebar filter field and click "Search". This will filter the list of files down to the files with "search" in the name.
2. Right-click searchbar.dtd file in the sidebar and choose "open file".
3. This file does not yet exist in your locale file structure, so Koala will ask if you want to create it. Click "OK".
   
4. When the file is created and opens in a new tab, right-click searchEndCap.label in the sidebar (it's listed under the searchbar.dtd file) and choose "add entity". We're starting by the second entity in this file on purpose, you'll see in a moment how Koala nicely handles entity order.
    
5. The entity was added to the file and the English string is automatically highlighted, so that you can translate it right away. This entity is used in the tooltip that appears when you hover over the magnifying glass icon in the search bar.
   
6. Once you translated the searchEndCap.label entity, add the other one from this file, i.e. cmd_engineManager.label. You can right-click it and choose "add entity" as you did previously, or just double-click the entity name to add it to the file.
   
7. Note how Koala is smart enough to insert this entity before searchEndCap.label. This is helpful for keeping the localization files clean and tidy at all times. The string to translated is selected so that you can translate it without any further clicking.
   
8. When you are done with translating the cmd_engineManager.label entity, save the file.
9. Now let's create the other file. Double-click on search.properties and click "OK" when Koala asks if you want to create this file.
10. From the sidebar, add the cmd_addFoundEngine string to the newly-created search.properties file in your locale file structure.
    
11. Translate the cmd_addFoundEngine string. Notice that the .properties files have a different syntax than the DTD files. They're just a simple key=value mapping.
    
12. Save the file to save your work.

Re-running the comparison

A common scheme of working with the compare-locales tools (included in Koala) is to incrementally translate and commit the files and then re-run comparison to see what is left to be translated. To make sure you're always translating the most recent en-US reference, you should update the source repository before you start working.

1. Open Koala's start page.
2. In "Last used compares" click "Update repo" to update the en-US repository to the most recent version. Or, you can select Firefox (3.6), en-US (included) and x-testing (3.6) in the "Open" section below, and click "Update repos" on the right. Koala will re-run the comparison of your local localization files with the newest en-US reference and display the results in the sidebar on the left.
3. Filter the files list in the sidebar to only display files containing "search" in their name.
4. You'll see that search.properties is now marked as "modified" (before it was "added) and the entity counts have changed. Also, searchbar.dtd is no longer displayed in the "compare" view, as it has been completely translated.
   
   Here's a quick summary of what the output of the comparison means:
   • files:
     • "unmodified" - the file is completely translated.
     • "added" - the file need to be added to the locale's file structure (it is present in en-US, but not in the locale files).
     • "modified" - the file needs to be modified (it is present in both en-US and the locale files, but the locale's version is outdated).
     • "removed" - the file needs to be deleted from locale's file structure (it is no longer present in en-US). Before you delete it entirely, check if the same file hasn't been added elsewhere in the en-US file structure! It may happen that a pair of files from which one is "added" and the other one is "removed" is actually the same file which has been moved from one directory to a different one.
   • strings:
     • +5 means that there are 5 missing strings in the locale's file compared to the en-US reference. You will need to add them to your locale's file.
     • -3 would mean that there are 3 obsolete strings in this file which needs to be removed. The file, however, is still used and shouldn't be deleted.
5. To see the results of the comparison for locale's all files (including searchbar.dtd), switch to "locale files" view in the "Koala file view" sidebar.
   
6. You're now looking at your locale's file structure and can see that searchbar.dtd is "unmodified" with 2 translated entities (0 missing, 0 obsolete), whereas search.properties is "modified" with 1 translated entity (6 total minus 5 missing, 0 obsolete).
   
7. Click on any of the files to see more detail, including the exact list of missing (green "+" icon), obsolete and translated (white circle icon) entities.
   

Now that you've translated these 3 strings, let's commit your work to the local hg repository that you created in the "Creating a new project" section.

Committing your work

Hopefully by now, you have translated 3 strings in the following 2 files:

• searchbar.dtd:

  • cmd_engineManager.label
  • searchEndCap.label

• search.properties:

  • cmd_addFoundEngine

It's time to put these files under Mercurial's version control system. This will allow you to track changes, export them to remote repositories (first on BitBucket, later on hg.mozilla.org) and revert files to earlier versions in case of errors. Version control systems add a lot of transparency to your work and allow others to get involved easily, so it's best to commit often (e.g. after you finish translating every file, or even more frequently).

Koala supports Mercurial and allows you to add and commit files automatically from Komodo. For the purposes of this tutorial, we will switch to the command line every now and then to see what Koala does behind the scenes. Normally though, you don't have to use the command line to commit your work.

Assuming that your locale files are in C:\mozilla\l10n\locale\x-testing\3.6 which is where the local Mercurial repository was created (see Creating a new project section), you should be able to successfully issue "hg cmd" commands in that directory (where "cmd" might be "status", "log", "commit" etc.). For example, try issuing "hg status" inside C:\mozilla\l10n\locale\x-testing\3.6:

C:\mozilla\l10n\locale\x-testing\3.6> hg status
? browser\chrome\browser\search.properties
? browser\chrome\browser\searchbar.dtd

The question marks ("?") in front of the file names indicate that the files are not tracked by Mercurial in this repository (yet). To start tracking them, you will need to "hg add" them. This can be done from Koala. Once you "hg add" every new file in the repository that you want to track in Mercurial, you will need to "hg commit" these new files so as to create a new revision in the repository's history. This process need to be repeated for every new file that you add. Also, removing files works in a similar manner: not only do you have to delete the file, but also you need to tell Mercurial to stop tracking the file with "hg remove". See "hg help add", "hg help remove" and "hg help addremove" for more details.

Let's now add and commit these two files from Koala.

1. In the "locale files" view in the sidebar, right click on search.properties and choose "add file to repository". This will execute "hg add" on this file in the background.
   
2. Koala will show you a message if the "hg add" was successful.
   
3. Instead of adding single files, you can also add an entire folder. Since we still need to add searchbar.dtd, let's simply add the entire browser/chrome/browser folder now. Right-click on the folder and choose "add folder to repository".
   
   The files have been added to the repository. If you switch to the command line and issue "hg status" again, you should now see that the files are scheduled for addition on the next commit (which is indicated by the letter "A" standing in front of each new file):
   

   C:\mozilla\l10n\locale\x-testing\3.6> hg status
   A browser\chrome\browser\search.properties
   A browser\chrome\browser\searchbar.dtd

4. You now have to commit the new files to the repository. Right-click on the browser/chrome/browser folder in the sidebar and choose "commit folder". (You could also commit each file individually if you felt like it.)
   
5. Koala will ask you to type in a commit message. It is a good practice to be descriptive about the changes you made in this revision. A good way of doing that is to ask yourself a question: "If I was a new person to this project and new nothing about the work already done in this repository, would this message help me understand what changes were made in this revision?". Type a good commit message and click "OK".
   
6. Koala will execute "hg commit" in the background and will let you know that the files were successfully committed.
   
   If you now go to the command line, "hg status" will not display anything (because there are no uncommitted changes in the repository). If you run "hg log" however, you will see you first commit in the repository's revision history:
   

   C:\mozilla\l10n\locale\x-testing\3.6> hg log
   changeset:   0:7c543e8f3a6a
   tag:         tip
   user:        Stas Malolepszy <stas@mozilla.com>
   date:        Mon Nov 23 18:08:25 2009 +0100
   summary:     Added search bar strings

Congratulations! You just made you first commit to the local repository. The last step of this tutorial will be to send (or "push") the changes you just made to a remote repository. Please read on.