Localizing with Narro

  • Revision slug: Localizing_with_Narro
  • Revision title: Localizing with Narro
  • Revision id: 7818
  • Created:
  • Creator: jbeatty
  • Is current revision? No
  • Comment 389 words added, 251 words removed

Revision Content

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.

To learn about updates and changes to the Narro project, visit the Narro project blog and web-based tool site.

 

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.

  1. Contact the Mozilla l10n drivers using the dev-l10n mailing list to ask if your localization effort already exists.
  2. 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
    • language
    • a bribe. Baked goods are always a good bribe :-)
  3. After doing this, you should receive the maintenance rights (i.e., export, import, and approval permissions) for the new localization.
  4. After receiving these rights, log out and log in again to activate them.

The image below is the screen you will see once you log in to activate your maintenance rights.

manage a locale.png

Import

NOTE: If you are joining an existing locale, feel free to skip this step. That is, unless you're interested in learning about how the import utility works. In that case, we won't stop you.

User account created; check. Locale created by global administrator; check. Activated maintenance rights for your new locale; check. Congratulations, you're now ready to import your Firefox project's source files! 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! You only have to manually import your source files once and then never 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 of untranslated strings the very next day. Now, let's go over how to set up your project's import utility.

  1. You will see a list of inactive project links with various names (e.g., Firefox Aurora, Firefox Release, etc.). Click on the link of the project you wish to activate. In this case, we will click on Firefox Aurora.
  2. By default you are taken to the Project Overview tab. Navigate to the Import tag to find the import utility.
  3. Once there, you will find these import sections:
    • Texts - for importing source files (en_US)
    • Translations - for importing already translated project files (xx_XX)
    • Options - checkboxes for configuring your import
    • Operation log - description of the import function as it is being executed.
  4. For now, we're going to focus only on the Texts and Options section. In the Texts section you will see the default location of the nightly updated source files for your project. Make sure that all the checkboxes in Options are unchecked for this first import.
  5. Click on the Import button. The Operation log will display a message once the import has completed successfully.

The image below is what you should see upon completing the import.

Import.png

Now you are ready to begin translating your project!

 

Translation

With the new locale established in Narro, you can now start translating online in Narro. One quick way to start is to click on the Translate tab and you will be taken to a screen with sets of untranslated content. A fresh import of Firefox Aurora (as of Firefox 7) contains 5,671 English strings.

Ironically, when you first begin translating, you will see the first few entries of the region.properties file that should not be translated using Narro. You will encounter some of these entries as you proceed through the translation. A good guideline to help you distinguish between translatable and non-translatable strings is to see if the entry can be categorized as either of the following:

  • If it is a product name, do not translate.
  • Any entries of pure code (e.g., %s), do not translate.

Anything that does not fall into these categories is translatable. Advance forward to translatable entries to begin translating. 

Texts.png

For the purpose of this document, we'll actually start by finding stings from two different types of files (DTD and property files). We'll make changes to those entries so that you can see the change in your UI.

 

Example 1: The DTD file searchbar.dtd

Narro allows you to 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... You can easily find this string in the browser UI by clicking on the drop-down arrow in the search box in the upper-right corner of your browser. Take a look at the image below. At the bottom of the list of search engines that appears, you'll see Manage Search Engines...

Add %S.png

Here is how you can use Narro to translate the Manage Search Engines... element:

  1. Navigate to the Translate tab in the Firefox Aurora project.
  2. Enter the string "Manage Search Engines..." in the Search for field and click Search.

After entering the string and clicking on "search", Narro presents the string you searched for. 

Manage Search Engines.png

  1. Click on the text box underneath the search result. This will expand the text box and highlight it in green to display the active entry.
  2. Enter in the translation and press save.

In the example below, you will see that the Manage Search Engines... element has been translated to MANAGE SEARCH ENGINES.

You will also note that there are two additional strings below the save icon. These are matches from previous translations and other translations that members of your community may have provided. The green and red boxes to the right allow you to approve or remove a translation for the active entry. Approved translations are entered into the translation memory. We do not recommend approving translations until they are in their final state. For the purposes of our example, saving your string by clicking on the save icon is enough.

approved translation.png

As you translate these types of DTD files, you can periodically export an .xpi file (also known as a language pack) that you can install on Firefox. We will discuss how to do that in a later section. 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. You can easily find this string 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. Take a look at the image below. There you'll see Add %S, where %S is replaced with the name of the site.

Add %S.png

Translating the strings from property files is exactly the same as translating those from DTD files. For this particular example, simply refer to the steps from example one, replacing the "Manage Search Engines..." string with the "Add %S" string. Just as with the DTD file, you can periodically export an .xpi file that you can install on Firefox to see your saved, translated strings.

Export

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.

export.png

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.

xpi.png

 

Final Export

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.

Revision Source

<p>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.</p>
<p>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.</p>
<p>To learn about updates and changes to the Narro project, visit the Narro <a class="external" href="http://narro-project.blogspot.com/" title="http://narro-project.blogspot.com/">project blog</a> and <a class="link-https" href="https://l10n.mozilla.org/narro/" title="https://l10n.mozilla.org/narro/">web-based tool</a> site.</p>
<p> </p>
<h2>Registering with Narro</h2>
<p>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.</p>
<p>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.</p>
<ol> <li>Contact the Mozilla l10n drivers using the <a href="/mailto:dev-l10n@lists.mozilla.org" title="mailto:dev-l10n@lists.mozilla.org">dev-l10n mailing list</a> to ask if your localization effort already exists.</li> <li>If no volunteer effort exists, email the same <a href="/mailto:dev-l10n@lists.mozilla.org" title="mailto:dev-l10n@lists.mozilla.org">dev-l10n mailing list</a> and ask the Narro global administrator to start a new localization in Narro for your locale. In your email, please provide <ul> <li>your user name</li> <li>language</li> <li>a bribe. Baked goods are always a good bribe :-)</li> </ul> </li> <li>After doing this, you should receive the maintenance rights (i.e., export, import, and approval permissions) for the new localization.</li> <li>After receiving these rights, log out and log in again to activate them.</li>
</ol>
<p>The image below is the screen you will see once you log in to activate your maintenance rights.</p>
<p><img alt="manage a locale.png" class="internal default" src="/@api/deki/files/5836/=manage_a_locale.png" style="width: 1063px; height: 582px;"></p>
<h2>Import</h2>
<p><u>NOTE</u>: If you are joining an existing locale, feel free to skip this step. That is, unless you're interested in learning about how the import utility works. In that case, we won't stop you.</p>
<p>User account created; check. Locale created by global administrator; check. Activated maintenance rights for your new locale; check. Congratulations, you're now ready to import your Firefox project's source files! The import utility, found under the <strong>Import</strong> 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! You only have to manually import your source files once and then never 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 of untranslated strings the very next day. Now, let's go over how to set up your project's import utility.</p>
<ol> <li>You will see a list of inactive project links with various names (e.g., <strong>Firefox Aurora</strong>, <strong>Firefox Release</strong>, etc.). Click on the link of the project you wish to activate. In this case, we will click on <strong>Firefox Aurora</strong>.</li> <li>By default you are taken to the <strong>Project Overview</strong> tab. Navigate to the <strong>Import</strong> tag to find the import utility.</li> <li>Once there, you will find these import sections: <ul> <li><strong>Texts</strong> - for importing source files (en_US)</li> <li><strong>Translations</strong> - for importing already translated project files (xx_XX)</li> <li><strong>Options</strong> - checkboxes for configuring your import</li> <li><strong>Operation log</strong> - description of the import function as it is being executed.</li> </ul> </li> <li style="margin-left: ;">For now, we're going to focus only on the <strong>Texts</strong> and <strong>Options</strong> section. In the <strong>Texts</strong> section you will see the default location of the nightly updated source files for your project. Make sure that all the checkboxes in <strong>Options</strong> are unchecked for this first import.</li> <li style="margin-left: ;">Click on the <strong>Import</strong> button. The <strong>Operation log</strong> will display a message once the import has completed successfully.</li>
</ol>
<p style="margin-left: ;">The image below is what you should see upon completing the import.</p>
<p><img alt="Import.png" class="internal default" src="/@api/deki/files/5828/=Import.png" style="width: 1074px; height: 582px;"></p>
<p>Now you are ready to begin translating your project!</p>
<p> </p>
<h2>Translation</h2>
<p>With the new locale established in Narro, you can now start translating online in Narro. One quick way to start is to click on the <strong>Translate</strong> tab and you will be taken to a screen with sets of untranslated content. A fresh import of Firefox Aurora (as of Firefox 7) contains 5,671 English strings.</p>
<p>Ironically, when you first begin translating, you will see the first few entries of the <code>region.properties</code> file that <em>should not be translated</em> using Narro. You will encounter some of these entries as you proceed through the translation. A good guideline to help you distinguish between translatable and non-translatable strings is to see if the entry can be categorized as either of the following:</p>
<ul> <li>If it is a product name, do not translate.</li> <li>Any entries of pure code (e.g., <code>%s</code>), do not translate.</li>
</ul>
<p>Anything that does not fall into these categories is translatable. Advance forward to translatable entries to begin translating. </p>
<p><a href="/@api/deki/files/5832/=Texts.png" title="Texts.png"><img alt="Texts.png" class="internal default" src="/@api/deki/files/5832/=Texts.png" style="width: 1050px; height: 577px;"></a></p>
<p>For the purpose of this document, we'll actually start by finding stings from two different types of files (DTD and property files). We'll make changes to those entries so that you can see the change in your UI.</p>
<p> </p>
<h3>Example 1: The DTD file <code>searchbar.dtd</code></h3>
<p>Narro allows you to search for particular strings. For this example, we'll search for the DTD file (often called an entity) named <code>searchbar.dtd</code> that contains the string <strong>Manage Search Engines...</strong> You can easily find this string in the browser UI by clicking on the drop-down arrow in the search box in the upper-right corner of your browser. Take a look at the image below. At the bottom of the list of search engines that appears, you'll see <strong>Manage Search Engines...</strong></p>
<p><img alt="Add %S.png" class="internal default" src="/@api/deki/files/5837/=Add_%252525S.png"></p>
<p>Here is how you can use Narro to translate the <strong>Manage Search Engines...</strong> element:</p>
<ol> <li>Navigate to the <strong>Translate</strong> tab in the Firefox Aurora project.</li> <li>Enter the string "Manage Search Engines..." in the <strong>Search for</strong> field and click <strong>Search</strong>.</li>
</ol>
<p>After entering the string and clicking on "search", Narro presents the string you searched for. </p>
<p><img alt="Manage Search Engines.png" class="internal default" src="/@api/deki/files/5833/=Manage_Search_Engines.png" style="width: 1063px; height: 240px;"></p>
<ol start="3"> <li>Click on the text box underneath the search result. This will expand the text box and highlight it in green to display the active entry.</li> <li>Enter in the translation and press save.</li>
</ol>
<p>In the example below, you will see that the <strong>Manage Search Engines...</strong> element has been translated to <strong>MANAGE SEARCH ENGINES</strong>.</p>
<p>You will also note that there are two additional strings below the save icon. These are matches from previous translations and other translations that members of your community may have provided. The green and red boxes to the right allow you to approve or remove a translation for the active entry. Approved translations are entered into the translation memory. We <em>do not</em> recommend approving translations until they are in their final state. For the purposes of our example, saving your string by clicking on the save icon is enough.</p>
<p><img alt="approved translation.png" class="internal default" src="/@api/deki/files/5831/=approved_translation.png" style="width: 1067px; height: 332px;"></p>
<p>As you translate these types of DTD files, you can periodically export an <code>.xpi</code> file (also known as a language pack) that you can install on Firefox. We will discuss how to do that in a later section. 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.</p>
<p> </p>
<h3>Example 2: The property file <code>search.properties</code></h3>
<p>The property file <code>search.properties</code> contains the string <strong>Add <code>%S</code></strong>. You can easily find this string in the browser UI by visiting a website that provides a search plugin (like <a href="/" title="http://developer.mozilla.org/"><code>http://developer.mozilla.org/</code></a>) and clicking on the drop-down arrow in the search box in the upper-right corner of your browser. Take a look at the image below. There you'll see <strong>Add <code>%S</code></strong>, where <strong><code>%S</code></strong> is replaced with the name of the site.</p>
<p><img alt="Add %S.png" class="internal default" src="/@api/deki/files/5837/=Add_%252525S.png" style=""></p>
<p>Translating the strings from property files is exactly the same as translating those from DTD files. For this particular example, simply refer to the steps from example one, replacing the "Manage Search Engines..." string with the "Add <code>%S</code>" string. Just as with the DTD file, you can periodically export an <code>.xpi</code> file that you can install on Firefox to see your saved, translated strings.</p>
<h2>Export</h2>
<p>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.</p>
<p><img alt="export.png" class="internal default" src="/@api/deki/files/5834/=export.png" style="width: 1099px; height: 298px;"></p>
<p>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, <strong>do not <em>"Hg Push"</em> from an export</strong>.  This is only a testable local build.</p>
<p> </p>
<h2>Testing Your Locale</h2>
<p>In order to test, you need to be able to change the locale of your browser to see your work.  Install either the <a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/356" title="https://addons.mozilla.org/en-US/firefox/addon/356">Locale Switcher</a> or the <a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/1333" title="https://addons.mozilla.org/en-US/firefox/addon/1333">Quick Locale Switcher</a> 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. </p>
<p>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.</p>
<p><img alt="xpi.png" class="internal default" src="/@api/deki/files/5835/=xpi.png" style="width: 1098px; height: 298px;"></p>
<p> </p>
<h2>Final Export</h2>
<p>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.</p>
Revert to this revision