Narro is a handy web-based translation tool that is available to localizers to translate a multitude of Mozilla projects. With Narro, you can translate Mozilla applications online, export files in a zip archive, or generate a .XPI file that can be installed locally for testing. After you have set up a project once, Narro uses translation memory (TM) from your translations to leverage your translated content. The TM feature lets you focus on the new, untranslated strings with each new Mozilla project release and not on re-translating strings from previously translated versions.
This document will walk you through the process of setting up a new locale and project in Narro. Using Firefox as an example, we will cover how to start a new project in Narro, how to use Narro to translate the application, and how to export and see your translations in a local build of Firefox.
Registering with Narro
Before you can do anything else in Narro, you need to set up your user account. Clicking the link in the top right corner of the Narro homepage will lead to you where you can register your user account. Once you've registered and logged in, you will see all of the different locales available to work on in the drop down menu in the top right corner.
For our purposes, let's call our new locale X-testing. Since we're interested in starting a new localization and you clearly won't find it listed in the menu, perform the following steps to set up your new localization.
- Contact the Mozilla l10n drivers using the dev-l10n mailing list to ask if your localization effort already exists.
- If no volunteer effort exists, email the same dev-l10n mailing list and ask the Narro global administrator to start a new localization in Narro for your locale. In your email, please provide
- your user name
- one interesting thing about you. We do, after all, want to get to know you :-)
- After doing this, you should receive the maintenance rights (i.e., export, import, and approval permissions) for the new localization.
- After receiving these rights, log out and log in again to activate them.
User account set up; check. Locale set up by global administrator; check. Activated maintenance rights for your new locale; check. Congratulations, you're now ready to import Firefox source files for translation! The import utility found under the Import tab of your Firefox project will provide you with several options for importing files for translation. The great thing about this utility is that it is completely automated! One only have to manually import your source files once and then never really have to worry about it again. The import utility imports files nightly so that if a string was added or changed one day, you'll see it in your list uf untranslated strings the very next day. Now, let's go over how to set up your project's import utility.
The first step is to import the project you want to translate by accessing the "Manage" link in your project list. If you don't see the link, it means you don't have permissions. (Email the mailing list or Narro global admin from above to gain access to the manage link.)
Although the Narro installation has nightly updated files of both en-US and your locale, it is up to you to import it. If the projects were imported automatically, it would have to be for all languages. Narro is not used by all languages, so this would lead to any interested end-users translating in languages that are not maintained in Narro.
With the new locale established in Narro, you can start translating online in Narro. One quick way to start is to click on the "Texts" link and you will be taken to a link that shows the sets of texts that need translation. At the time of writing this document, a fresh import of Firefox contained 5,395 strings needing translation. Ironically, in the screen shot below, you will see the first entries of the "region.properties" file that should not be translated using Narro. You'll want to move to the first string needing translation. Advance forward to page 2 to begin translating texts. There begins the UI strings that need translation.
For the purpose of this document, we'll actually start by finding two different types of strings (DTD and property files) and make changes to those so you can see the change immediately in your UI.
Example 1: The DTD File, "searchbar.dtd"
With Narro, you can search for particular strings. For this example, we'll search for the DTD file (often called an entity) named searchbar.dtd that contains the string "Manage Search Engines..." by typing that string into the search box. "Manage Search Engines..." can easily be found in the 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...".
Back to Narro. After entering the string and clicking on "search", Narro presents the string you searched for.
Clicking on the dark gray text box under "Translated text" opens a new screen where you can enter in the translation of that text. Enter in the translation and press save. In the example below, you will see that the "Manage Search Engines..." string has been translated to "MANAGE SEARCH ENGINES".
As you translate these types of DTD files, you can periodically save your work and export an ".xpi" (also known as a language pack) file that you can install on Firefox. We discuss that below. Next time you install the testable language pack, you'll see the "Manage Search Engines..." string translated in the UI of your local version of Firefox.
Example 2: The Property File, "search.properties"
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.
For this example, we'll search for the string "Add %S" by typing that into the search box. Just like above, you can click on the dark gray text box under "Translated text". This opens a new screen where you can enter in the translation of "Add %S". Enter in the translation and press save. Once again, as you translate these types of property files, you can periodically save your work, export an .xpi, and then install that new language pack add-on for testing as you go.
After you have done some work and you are ready for testing, navigate to the "Manage" link and click on it. Scroll down to the section "Export project". Make sure to leave "Copy unhandled files" as checked. This tells Narro to leave alone all the files that are not handled by the translation interface (like .txt, .rdf, .xml files) and copies them directly to your structure. Leave "Export archive format" as zip. When exporting files as a zip file, the same source structure as Mozilla code is preserved. Also, keep "Export translations using:" set at "Approved Suggestion". Click "Export" and, once the status bar is complete, you will see a .zip hyperlink appear that will allow you to save the file locally to your disk.
At any point during your translation efforts, you can export the en-US.zip package if you want to see the Firefox source code structure of the files with en-US strings. However, do not "Hg Push" from an export. This is only a testable local build.
Testing Your Locale
In order to test, you need to be able to change the locale of your browser to see your work. Install either the Locale Switcher or the Quick Locale Switcher add-on. This will allow you to shift between the present UI of your Firefox browser and the testable .xpi export from Narro. This is a requirement for locale testing with Narro. Be sure to change to the testable language by reading just how to do so from the instructions of the add-on.
Every time you export the translation, an .xpi is built. At export, any untranslated strings will get exported with en-US strings instead. This allows you to test your work-in-progress as you go so you can see your work! Visit Projects page and you will see an .xpi you can install for the latest nightly branch. To install this .xpi, click on the link and Firefox will prompt you to install the newly created .xpi (aka an "add-on" or "language pack"). You will need to restart your browser to install the .xpi.
When finished, you will need to send an email to dev-l10n mailing list or to the Narro admin asking for assistance on the export from Narro in order to participate in the Mozilla release. Please note that the Mozilla l10n-drivers have produced the "l10n dashboard" based on a powerful tool called "Compare-Locales". Because of the way that Narro manages its strings and exports, it invalidates the accuracy of the compare-locales output.