Localizing with Narro

  • Revision slug: Localizing_with_Narro
  • Revision title: Localizing with Narro
  • Revision id: 7814
  • Created:
  • Creator: jbeatty
  • Is current revision? No
  • Comment one or more formatting changes

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.

 

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

Texts.png

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. 

Manage Search Engines.png

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".

approved translation.png

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.

 

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.

 

 

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> </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 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 <em>should not be translated</em> 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.  </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 two different types of strings (DTD and property files) and make changes to those so you can see the change immediately in your UI.</p>
<p> </p>
<h3>Example 1: The DTD File, "searchbar.dtd"</h3>
<p>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...".</p>
<p><img alt="" class="internal" src="/@api/deki/files/3929/=Manage_Search_Engines....png" style="width: 268px; height: 308px;"></p>
<p>Back to Narro.  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>
<p>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".</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 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.</p>
<p> </p>
<h3>Example 2: The Property File, "search.properties"</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 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.</p>
<p><img alt="" class="internal" src="/@api/deki/files/3931/=Add_%2525S.png" style="width: 259px; height: 279px;"></p>
<p>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.</p>
<p> </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> </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