Localizing with Narro

  • Revision slug: Localizing_with_Narro
  • Revision title: Localizing with Narro
  • Revision id: 7838
  • Created:
  • Creator: jbeatty
  • Is current revision? No
  • Comment 5 words added

Revision Content

Narro is a handy web-based translation tool for translating 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 your translations for testing 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. Below you'll find a list of tools that are prerequisite to localizing with Narro.

 

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, we'll call our new locale X-testing. 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 the following information:
    • your user name
    • language
    • a bribe. Baked goods are always a good bribe :-)

      Alternately, if a volunteer effort does already exist, get in touch with your l10n community and ask them about how you can get involved!

  1. After doing this, you should receive the maintenance rights (i.e., export, import, and approval permissions) for the new localization.
  2. 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:
    • 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 Translations and Options section. In the Translations 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 that 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 them 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 field and click Search.

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 your 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 your translation. These are matches from previous translations that members of your community may have provided. The arrows on the right allow you to vote on a translation for the active string. Those that are voted to the top of the list are entered into the translation memory.

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.

 

Exporting an .xpi language pack

Congratulations! Now that you've translated and saved some strings, let's export your translated strings for you to see your translations in your Firefox Aurora browser. The export utility in the Export tab gives you a few different options for export. Some options are meant for testing your translations, others are meant for your final approved translations that will be incorporated into the next Firefox release. For our example, we're going to concentrate on exporting your translations in an .xpi language pack.

  1. Navigate to the Export tab. The image below illustrates what you'll see once you're there.

export.png

  1. Select the Approved suggestion option from the Export translations using: drop down menu.
  2. Click on the Export button.
  3. Once the status bar is complete, you will see .zip, .html, and .xpi hyperlinks appear. Click on the .xpi link to save it to your disk.

An .xpi language pack is built every time you export your translation. All untranslated strings are exported with en-US strings as part of your language pack. This allows you to test your work-in-progress as you go so you can see your work!

When exporting files, the Mozilla source code structure is preserved. 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. 

Warning: Do not use the hg push command from an export as this is only a testable local build.

To learn how to test your freshly exported language pack, visit the Testing your language pack topic on the Create a new localization wiki page.

Final Export

Once you've completed your translation, tested it, and reviewed it, it will be time to produce your final export (in .zip format) for submission to Mozilla. To do this, send an email to either the dev-l10n mailing list or the Narro global admin asking for assistance.

Please note that the Mozilla l10n-drivers have produced the l10n dashboard to track the release progress for all Mozilla localizations. The dashboard is based on a powerful tool called Compare-Locales. Should you choose to use Narro for your localization, be aware that Narro invalidates the dashboards project tracking accuracy because of the way that Narro manages its strings and exports.

 

Back: Quick Start Guide

Revision Source

<p>Narro is a handy web-based translation tool for translating 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 your translations for testing 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. Below you'll find a list of tools that are prerequisite to localizing with Narro.</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, we'll call our new locale X-testing. 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 the following information: <ul> <li>your user name</li> <li>language</li> <li>a bribe. Baked goods are always a good bribe :-)</li> </ul> </li>
</ol>
<p>      Alternately, if a volunteer effort <em>does</em> already exist, get in touch with your <a class="link-https" href="https://wiki.mozilla.org/Category:L10n_Teams" title="https://wiki.mozilla.org/Category:L10n_Teams">l10n community</a> and ask them about how you can get involved!</p>
<ol start="3"> <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><a href="/@api/deki/files/5949/=manage_a_locale.png" title="manage a locale.png"><img alt="manage a locale.png" class="internal default" src="/@api/deki/files/5949/=manage_a_locale.png" style="width: 1063px; height: 545px;"></a></p>
<h2>Import</h2>
<div class="note">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.</div>
<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>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>Translations</strong> and <strong>Options</strong> section. In the <strong>Translations</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><a href="/@api/deki/files/5950/=Import.png" title="Import.png"><img alt="Import.png" class="internal default" src="/@api/deki/files/5950/=Import.png" style="width: 1063px; height: 514px;"></a></p>
<p>Now you are ready to begin translating your project!</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 that 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/5951/=Texts.png" title="Texts.png"><img alt="Texts.png" class="internal default" src="/@api/deki/files/5951/=Texts.png" style="width: 1063px; height: 567px;"></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 them 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</strong> field and click <strong>Search</strong>.</li>
</ol>
<p><a href="/@api/deki/files/5953/=Manage_Search_Engines.png" title="Manage Search Engines.png"><img alt="Manage Search Engines.png" class="internal default" src="/@api/deki/files/5953/=Manage_Search_Engines.png" style="width: 1063px; height: 482px;"></a></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 your translation and press <strong>Save</strong>.</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 your translation. These are matches from previous translations that members of your community may have provided. The arrows on the right allow you to vote on a translation for the active string. Those that are voted to the top of the list are entered into the translation memory.</p>
<p><a href="/@api/deki/files/5954/=approved_translation.png" title="approved translation.png"><img alt="approved translation.png" class="internal default" src="/@api/deki/files/5954/=approved_translation.png" style="width: 1063px; height: 141px;"></a></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 <em>MANAGE SEARCH ENGINES</em> 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 <strong>Manage Search Engines...</strong> string with the <strong>Add <code>%S</code></strong> 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>
<p> </p>
<h2>Exporting an <code>.xpi</code> language pack</h2>
<p>Congratulations! Now that you've translated and saved some strings, let's export your translated strings for you to see your translations in your Firefox Aurora browser. The export utility in the <strong>Export</strong> tab gives you a few different options for export. Some options are meant for testing your translations, others are meant for your final approved translations that will be incorporated into the next Firefox release. For our example, we're going to concentrate on exporting your translations in an <code>.xpi</code> language pack.</p>
<ol> <li>Navigate to the <strong>Export</strong> tab. The image below illustrates what you'll see once you're there.</li>
</ol>
<p><a href="/@api/deki/files/5955/=export.png" title="export.png"><img alt="export.png" class="internal default" src="/@api/deki/files/5955/=export.png" style="width: 1063px; height: 216px;"></a></p>
<ol start="2"> <li>Select the <strong>Approved suggestion</strong> option from the <strong>Export translations using:</strong> drop down menu.</li> <li>Click on the <strong>Export</strong> button.</li> <li>Once the status bar is complete, you will see <code>.zip</code>, <code>.html</code>, and <code>.xpi</code> hyperlinks appear. Click on the <code>.xpi</code> link to save it to your disk.</li>
</ol>
<p>An <code>.xpi</code> language pack is built every time you export your translation. All untranslated strings are exported with en-US strings as part of your language pack. This allows you to test your work-in-progress as you go so you can see your work!</p>
<p>When exporting files, the Mozilla source code structure is preserved. At any point during your translation efforts, you can export the <code>en-US.zip</code> package if you want to see the Firefox source code structure of the files with en-US strings. </p>
<div class="warning">Warning: Do not use the <code>hg push</code> command from an export as this is only a testable local build.</div>
<p class="warning">To learn how to test your freshly exported language pack, visit the <a href="/en/Create_a_new_localization#Testing_your_language_pack" title="https://developer.mozilla.org/en/Create_a_new_localization#Testing_your_language_pack">Testing your language pack</a> topic on the <a href="/en/Create_a_new_localization" title="https://developer.mozilla.org/en/Create_a_new_localization">Create a new localization</a> wiki page.</p>
<h2>Final Export</h2>
<p>Once you've completed your translation, <a class="link-https" href="https://wiki.mozilla.org/L10n:Becoming_an_Official_Localization#Preparation" title="https://wiki.mozilla.org/L10n:Becoming_an_Official_Localization#Preparation">tested it, and reviewed it</a>, it will be time to produce your final export (in .zip format) for submission to Mozilla. To do this, send an email to either the <a class="link-mailto" href="mailto:/mailto%3Adev-l10n@lists.mozilla.org" title="https://developer.mozilla.org/mailto%3Adev-l10n@lists.mozilla.org">dev-l10n mailing list</a> or the Narro global admin asking for assistance.</p>
<div class="note">Please note that the Mozilla l10n-drivers have produced the <a class="link-https" href="https://l10n-stage-sj.mozilla.org/dashboard/" title="https://l10n-stage-sj.mozilla.org/dashboard/">l10n dashboard</a> to track the release progress for all Mozilla localizations. The dashboard is based on a powerful tool called <a href="/en/Compare-locales" title="https://developer.mozilla.org/en/Compare-locales">Compare-Locales</a>. Should you choose to use Narro for your localization, be aware that Narro invalidates the dashboards project tracking accuracy because of the way that Narro manages its strings and exports.</div>
<p> </p>
<p><a href="/en/Localization_Quick_Start_Guide:_Translation" title="Localization Quick Start Guide: Translation">Back: Quick Start Guide</a></p>
Revert to this revision