L10n:MozillaTranslator

MozillaTranslator is a tool to translate programs in the Mozilla family.

If you are looking for the newest version the MozillaTranslator tool, the latest 5.23 version is available from the following Sourceforge page: MT downloads page.

For developers, its source code is available through MT Sourceforge page (you no longer have to look into the "newsrc" directory for "current" code; instead, the CVS root includes both NetBeans project files and source code, so you'll have to checkout from CVS root).

You can check MT open bugs at Bugzilla@Mozilla. Look for open bugs with:

• Product: Mozilla Localizations
• Component: MozillaTranslator

MozillaTranslator is written in Java. This means:

• that it will work on any platform that supports Java (Windows/Linux/Mac/Solaris etc.), and
• that you need to make sure you have Java 1.5 or above installed on your system.

How to Use

Current PDF manual

You can get the current, up to date manual as a PDF. Wherever the PDF manual and this wiki page differs, the PDF version should be taken as the normative one.

Creating a new Product

The first thing you need to do is to create a new product. First, obtain the .jar files that include the en-US language pack. There are several ways to do that:

1. If you have an installed copy of the program you want to translate, open the installation directory of the program. Under a folder named 'chrome' there, you will find a file named en-US.jar (or something similar), and possibly also en-win.jar, en-mac.jar, en-unix.jar and US.jar.
2. Extract the language pack (normally called langenus.xpi) from the installer, as described here. Then use a Zip utility to open it and extract the files mentioned in (1) from it. Similarly, extract the region pack (exists in Mozilla Suite) named regus.xpi and extract US.jar from it.

From the File menu select Manage Products, and in the window that opens, press the Add button.

• Name: Give a meaningful name to this product.
• Jar file: Enter the path to the en-US.jar file you extracted earlier.
• Platforms: Click the Add button to add files for each platform, if applicable.
  • Name: Platform name. Enter a descriptive name.
  • Jar file: Path to the .jar file for this platform.
  • Type: Select the platform for which this .jar file is intended for.
    Repeat theses steps for each supported platform.
• Jar file (regional): Enter the path to US.jar.
• Custom Files: You may add additional files to the language pack, such as local search engines or a localized bookmarks file. This part doesn't always work.

Click OK to close the window. You should see the new product in the previous window. Click Exit to close it.

Now, from the File menu select Update Product. From the new window, select the product you have just created, and click OK. You will see the Show which columns window. It is best to select Key, Text: Original, Text: Translated, and Keep original. Enter your locale code at the bottom, and click OK. You will see the complete list of strings that need to be translated.

Importing Existing Translation

If you have access to a translation of an earlier version of the program than the one you are working on, you can import it and use the parts of it that are still relevant. Follow these steps:

1. From the Import menu, select Import Translation.
   • selected: Select the product and the component that you are importing.
   • File: The path to the .jar file that includes the translation of the selected component.
   • Locale: Enter your locale, in a ab-CD format.
2. Click OK.

Repeat these steps for every component of the product.

Translating the Strings

The translation work is done at the Chrome view. From the Edit menu, select Chrome view. In the Show which columns window, select the columns as above, and click OK.

The Chrome view is split in two: the left pane shows the products tree. Under Root, you will see a branch for each product you added. Under each product, there is a branch for each component: Platform Neutral, Regional files, the platform-specific branches, and the Custom files. Under each component, there is a branch for every folder (and sub-branches for sub-folders) in the corresponding .jar file. Under each folder branch, there is one branch called MT_default, which contains the files in that folder. Any additional sub-folders will be listed along side MT_default. To start working on a file, select it with the mouse. The strings in that file will appear in the right pane.

The right pane contains the content of the files. for DTD and Properties files, this content will be the strings of that file. If you selected the Text: Translated column in the Show which column dialog, you can select the cell in the table and start writing the translation.

Image files (.png or .gif) may be edited with the Edit Image dialog.

If you select another file type from the left pane, such as HTML, RDF, and others, the right pane will show one row, with the text "Use the edit dialog" in the Text: Original column. you may select it and edit it with the Edit Phrase dialog, but it's much easier to extract the file from the original jar file with a Zip program and edit it with an external Unicode editor.

Tip: If you leave a string untranslated, the original string will be used in the exported language pack.

Tip:Keys that end with "accesskey" represent shortcut keys, that allow accessing menus and buttons with the Alt+[key] combination. Keys that end with "commandkey" represent shortcut keys that allow quick access to features with the Ctrl+[key] combination.

Tip: Checking the Keep column for a string, if selected, will keep the original string in the exported language pack, overriding the translated string.

You can sort the strings table by one of the columns, by clicking on the column header to sort in descending order, or shift+click for ascending order.

To save the work you did, select Save Glossary from the File menu.

The Edit Phrase Dialog

If a string is too long, it might be difficult to edit it in the chrome view table. In this case, you can click the Edit selected phrase button at the top-left corner of the Chrome view window (or select Edit selected phrase from the Edit menu, or just press Alt+E) to open the Edit Phrase dialog. This dialog has two tabs:

• The Basic tab is divided to two: the top half contains the original string, and the bottom half contains the translated string, if there is a translation. If there is no translation yet, it will be empty. between the two halves, there are three buttons and a checkbox.
  • Copy copies the original string to the translated string, and replaces it.
  • Reset undoes any changes made to the translated string since this window was opened.
  • Clear clears the translated string box.
  • Keep Original should check the box in the Keep column in the table, but it doesn't, because of a bug. Just ignore it.
• The Advanced tab contains extended information about the current string.
  • Information contains information about the string location: product, component, folder, file, etc.
  • Original contains information about the Control and Alt access keys of the current string, if such exist. Since the format for the these keys is not standard throughout the language files, sometimes MT fails to detect these values.
  • Translation contains the same information about the corresponding translated text. It also allows adding a comment to this string, and set it's status. This is useful for collaboration between several translation team members, or to make a note for yourself for later reference.

At the bottom of this window there are three buttons.

• Close: Save any changes and close the window.
• Previous/Next: Save any changes and move to the previous or next string, if one exists.

The (yet to be titled) Edit Image Dialog

Images (.gif or .png extension), such as those under the help/images/ branch of Mozilla Suite, can also be "translated". Sometimes images are screenshots that contain text, and you would like it to be the text of your translation instead of the English text. Or, if you are translating to a Right-To-Left language, such as Hebrew, Arabic or Persian, the program layout is reversed and looks different from the original layout. In those cases, you can import your own images to replace the original images included in the language pack. Follow these steps:

1. Select an image file from the left pane.
2. In the right pane you will see the text "Binary files cannot be translated" in the Text: Original column. Select this line.
3. Click the Edit Image file button from the top-left corner of the Chrome view window.

The (yet to be titled) window is divided to two:

• The upper half contains the original image. The Save button allows you to export the image to a file you can edit with an external image manipulation program.
• The lower half may contain a "translated" image, if such exist, or the text "No picture Loaded" if non exists. If no image is loaded as a translation, the original image will be used in the language pack. This half contains these buttons:
  • Load: allows loading an image from disk. This image will be used in the exported language pack, instead of the original image. Pay attention to have the replacement image at the same size and format of the original one. A different size may cause layout problems when the image is displayed. A different format will require you to change the reference to the image in the document that displays it. Mozilla supports PNG, GIF, JPG, ICO, BMP formats.
  • Save: allows exporting the translated image to a file on disk.
  • Clear: clears the translated image(?).
  • Reset: restores the image that was loaded when the window was opened(?).

When you are done, click OK to accept the changes, or Cancel to cancel them.

Migrating to a Newer Program Version

When a new version of the program you are translating comes out, you don't have to start the translation from scratch. MozillaTranslator allows you to migrate your translation to the new version. It will also tell you which new strings were added, and which were changed, since the last version. Here's how:

1. Get the language pack .jar files, just as you would for a new translation, as explained in the beginning of this article.
2. From the File menu, select Manage Products.
3. From the Manage products window, select the product you are upgrading and click the Edit button.
4. Update the pathes to the .jar files of the new version. If applicable, don't forget to update the paths of the platform-specific files, by selecting the platform name and clicking the Edit button.
5. When you are done, click OK, and Exit at the Manage products window.
6. From the File menu, select Update Product.
7. In the Update product window, select the product you are upgrading and click OK. You will see the Show which column dialog. Select the columns you want to display and click OK.

Now you will see a list of all the strings that have been added or changed since the last version. Translate or correct the translation of the strings, and when you are done, close the window.

To save the changes, select Save Glossary from the File menu.

Collaborating with Other Team Members

Often, the localization effort is made by several members of a localization team. MozillaTranslator allows you to easily share the work between team members.

First, decide which member will be the coordinator. This member will distribute segments of the language pack to other members, and later integrate the translated work back to the master copy.

Next, each member must set up MozillaTranslator on his or her computer, as described above. The only exception is, that members don't have to import any translation of a previous version you might have. It is enough for the coordinator to have such a translation, if one exists.

To distribute the translation, follow these steps:

1. From the Export menu, select Export partial glossary.
2. In the Export Subcomponent dialog, select a folder from the product you are working on, and enter the path to the exported file. Press the Choose button to select a folder on your disk.
3. Press OK.

The receiving member will have to import the partial component, like so:

1. From the Import menu, select Import partial glossary.
2. In the Import subcomponent window, select the folder you expect to receive.
3. Enter the path to the sub-component file.
4. Press OK.

Once the partial translation is imported, the team member may translate it. When you are done, export the component you have been working on in the same manner as described above, and send it to the coordinator. The coordinator, in turn, should import the translated subcomponent in the same way, and that's it.

Migrating from One Product to Another

MozillaTranslator allows you to migrate an existing translation from one product to another. For example, you might want to migrate your translation of the Mozilla Suite Mail & News component to Mozilla Thunderbird, or migrate Mozilla Suite to SeaMonkey.

First, make sure you have both the source product and the target product loaded in MozillaTranslator, as explained above. Then select Migrate product from the Advanced menu. In the Migrate product window, select the source product at the top, and target product at the bottom. Make sure your locale is entered at the locale field, and click Ok.

You should now be able to see the migrated translation in the Chrome view window.

Note: Images may not be transferred in the migration process. If images are not transferred, you will have to manually export them from the originating product (or obtain them otherwise) using the Export > Export File menu, and import them to the target product using the Import > Import File menu.

Exporting a Language Pack

The most important part of the translation, is of course creating an installable language pack, or a language .jar file you can pack with a localized installer of the program. This is done from the Export menu.

To export a language pack that you can install on a Mozilla Suite or SeaMonkey, select XPI install from the Export menu. In the Export XPI window, enter these values:

• Locale: your locale, in ab-CD format.
• File: complete path, including file name, to the file that will be generated.
• display name: this is the name that will be displayed in the language pack selection window of Mozilla Suite or SeaMonkey. This field is not used in other Mozilla products.
• Author: author of the language pack. That will be you, of course. However, this field is not displayed to the user, and is only saved internally in the language pack files.
• Preview URL: irrelevant. Can be left empty.

Select the product and components to include in the language pack, and click OK.

You might want to change the display name for the region pack, or you'll see the language name in the region selection window instead of the region name. This is done by editing the /global-region/content.rdf file in the region file (CD.jar). Applicable to Mozilla Suite and SeaMonkey only.

To export just the .jar file(s), select Jar file from the Export menu. In the Export Jar dialog enter the details as described above for the Export XPI window, select the product and component from the Export drop-down list, and click OK.

Warning: There is a bug in the jar export mechanism, that causes the content.rdf files to miss the version number. You must manually extract them and edit them to add the correct version number, or they won't be recognized as compatible with the program you are translating, and won't work.

Menu Items

File

Manage Products

opens the Manage Products dialog, where you can add a new product, edit the properties of an existing product, or remove a product from the glossary. When you are done, click the Exit button.

Update product

Select this menu item to make the changes made in the Manage Product dialog take effect. In the Update product dialog, select a product from the list and click OK.

You can also use this dialog if you replaced the source language .jar file with a newer one, e.g. when a new version of the product is released.

Save glossary

Saves the translation to a file in the MozillaTranslator folder. This is not the file of the language pack; it is used to save your work between sessions, and in order to prevent data loss in case of a crash, system halt, etc.

No indication is given as to the status of the saving process.

Save Settings

Saves the settings defined in the Settings menu item. No indication is given as to the status of the saving process.

Export

XPI Install

Use this menu item to export your language pack to an installable XPI package. In the Export XPI dialog, set the following fields:

• Locale: your locale, in ab-CD format.
• File: full path to the package you want to create. This setting determines the name and location of the language pack that will be created.
• display Name: the name that will be displayed to the user in the language selection dialog of Mozilla Suite/SeaMonkey. This name will also be shown as the name of the region pack, if you include it, so you will have to manually edit the region pack's name: after you export the language pack, extract the region pack .jar file from the XPI, extract the file contents.rdf and change the value of the chrome:displayName attribute of the RDF:Description tag to something like "<country-name> Region".
• Author: your name. This will be recorded in the language pack files, and will not be visible to users.
• Preview URL: this value will be recorded in the language pack files, but has no use today.
• Select platforms and regions: check the components you want to include in the package.

Press OK to create the language pack, or Cancel to cancel the operation.

Jar file

This one has a little bug in the generated contents.rdf files, where the version is missing.