|
|
| Line 1: |
Line 1: |
| MozillaTranslator is a tool to translate programs in the Mozilla family. | | 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.24 version is available from the following Sourceforge page: [http://sourceforge.net/project/showfiles.php?group_id=18842 MT downloads page]. | | If you are looking for the newest version the MozillaTranslator tool, the latest 5.25 version is available from the following Sourceforge page: [http://sourceforge.net/project/showfiles.php?group_id=18842 MT downloads page]. |
|
| |
|
| For developers, its source code is available through [http://sourceforge.net/projects/moztrans/ 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). | | For developers, its source code is available through [http://sourceforge.net/projects/moztrans/ 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). |
| Line 9: |
Line 9: |
| * Product: Mozilla Localizations | | * Product: Mozilla Localizations |
| * Component: MozillaTranslator | | * Component: MozillaTranslator |
| | |
| | '''NOTE''': The project is being migrated to Kenai.com (more details soon). The repository will be migrated to Mercurial and the bug tracking system will be based there (using BugZilla). |
|
| |
|
| MozillaTranslator is written in Java. This means: | | MozillaTranslator is written in Java. This means: |
|
| |
|
| * that it will work on any platform that supports Java (Windows/Linux/Mac/Solaris etc.), and | | * that it will work on any platform that supports Java (Windows/Linux/Mac/Solaris etc.), and |
| * that you need to make sure you have [http://www.java.com Java] 1.5 or above installed on your system. | | * that you need to make sure you have [http://www.java.com Java] 1.6 or above installed on your system. |
|
| |
|
| ==How to Use== | | ==How to Use== |
| ===Current PDF manual=== | | ===Current PDF manual=== |
| You can get the current, up to date manual as a [[media:mt-userguide.pdf|PDF]]. Wherever the PDF manual and this wiki page differs, the PDF version should be taken as the normative one. | | You can get the current, up to date manual as a [[media:mt-userguide.pdf|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:
| |
| # 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.
| |
| # Extract the language pack (normally called langenus.xpi) from the installer, as described [[L10n:Localizing Overview|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.<br>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:
| |
| <ol>
| |
| <li> 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.</li>
| |
| <li>Click OK.</li>
| |
| </ol>
| |
|
| |
| 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 [[#The (yet to be titled) Edit Image Dialog|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 [[#The Edit Phrase Dialog|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 [http://www.mozilla.org/projects/l10n/mlp_tools.html#texteditors 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:
| |
| #Select an image file from the left pane.
| |
| #In the right pane you will see the text "Binary files cannot be translated" in the Text: Original column. Select this line.
| |
| #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:
| |
| #Get the language pack .jar files, just as you would for a new translation, as explained in the beginning of this article.
| |
| #From the File menu, select Manage Products.
| |
| #From the Manage products window, select the product you are upgrading and click the Edit button.
| |
| #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.
| |
| #When you are done, click OK, and Exit at the Manage products window.
| |
| #From the File menu, select Update Product.
| |
| #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:
| |
| #From the Export menu, select Export partial glossary.
| |
| #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.
| |
| #Press OK.
| |
|
| |
| The receiving member will have to import the partial component, like so:
| |
| #From the Import menu, select Import partial glossary.
| |
| #In the Import subcomponent window, select the folder you expect to receive.
| |
| #Enter the path to the sub-component file.
| |
| #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 [[#Creating a new Product|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:
| | ===Overview of workflow=== |
| *'''Locale''': your locale, in ab-CD format.
| | MT uses ''products'' as groups of localization files with a common root directory (for instance, you may have a product for Thunderbird, other for SeaMonkey, other for Dom, other for Toolkit, etc.). |
| *'''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 update your repository copy using your favorite repository tool, and then update the product(s) in MT This will remove obsolete strings and files from the internal ''database'' of MT, and will present you with a list of new and updated strings. |
|
| |
|
| 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.
| | '''Hint''': if you are starting a new localization, ALL strings will be marked as new or updated. MT puts a ''fuzzy'' flag (actually, it is more a kind of 'To Do' or 'Pending' flag) and saves it in its database. You can save your work in progress and reopen it later, selecting 'View Fuzzy' option in Edit menu, to continue working. |
|
| |
|
| 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.
| | After translating those strings (if using the Edit Phrase dialog, you can get translation suggestions for strings having an original text equal to existing translations), you can run some automated tests to detect typical errors. After that, you export either the whole product or indvididual files. |
|
| |
|
| '''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.
| | Finally, you commit your changes outside of MT, using your favorite repository tools. |
|
| |
|
| ==Recipes== | | ==Recipes== |
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.25 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
NOTE: The project is being migrated to Kenai.com (more details soon). The repository will be migrated to Mercurial and the bug tracking system will be based there (using BugZilla).
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.6 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.
Overview of workflow
MT uses products as groups of localization files with a common root directory (for instance, you may have a product for Thunderbird, other for SeaMonkey, other for Dom, other for Toolkit, etc.).
You update your repository copy using your favorite repository tool, and then update the product(s) in MT This will remove obsolete strings and files from the internal database of MT, and will present you with a list of new and updated strings.
Hint: if you are starting a new localization, ALL strings will be marked as new or updated. MT puts a fuzzy flag (actually, it is more a kind of 'To Do' or 'Pending' flag) and saves it in its database. You can save your work in progress and reopen it later, selecting 'View Fuzzy' option in Edit menu, to continue working.
After translating those strings (if using the Edit Phrase dialog, you can get translation suggestions for strings having an original text equal to existing translations), you can run some automated tests to detect typical errors. After that, you export either the whole product or indvididual files.
Finally, you commit your changes outside of MT, using your favorite repository tools.
Recipes
Introduction
We aim to put here some recipes that may be useful at a certain moment for MT users, but that, due to its temporary nature, don't fit in the user manual.
Migrating contents when the directory structure changes
Overall, if you are a good MT user and you do things like:
- checking "Keep Original" flags for strings not needing translation, instead of just leaving the translation empty,
- struggling to get empty lists when running "Untranslated strings" and "View Fuzzy" if you are up to date in localization,
- regularly run QA checks and try to minimize them.
you will always do better if you can export a partial glossary and reimport it as needed. See the following example.
Let's assume you have a Firefox product in MT with the directory layout present in language packs, as you probably would need for a initial localization. The directory structure will look like this:
(ab-CD JAR root)
locale
|-- branding
| |-- brand.dtd
| `-- brand.properties
|-- browser
| |-- aboutDialog.dtd
.
.
|-- browser-region
| `-- region.properties
`-- ab-CD
|-- alerts
| `-- notificationNames.properties
|-- autoconfig
| `-- autoconfig.properties
|-- cookie
| |-- cookieAcceptDialog.dtd
| `-- cookieAcceptDialog.properties
|-- global
| |-- about.dtd
| |-- appPicker.dtd
.
.
but in the CVS and mozilla-central repositories the locale part looks like this:
toolkit
|-- locales
| |-- en-US
| | |-- chrome
| | | |-- alerts
| | | | `-- notificationNames.properties
| | | |-- autoconfig
| | | | `-- autoconfig.properties
| | | |-- cookie
| | | | |-- cookieAcceptDialog.dtd
| | | | `-- cookieAcceptDialog.properties
| | | |-- global
| | | | |-- about.dtd
| | | | |-- appPicker.dtd
.
.
browser
|-- locales
| |-- en-US
| | |-- README.txt
| | |-- chrome
| | | |-- branding
| | | | |-- brand.dtd
| | | | `-- brand.properties
| | | |-- browser
| | | | |-- aboutDialog.dtd
As you see, there is link point, usually at chrome (in CVS & mozilla-central), sometimes in a deeper point. For instance, toolkit/locales/en-US/chrome in mozilla-central matches locale/en-US and browser/locales/en-US/chrome matches locale/browser.
So, what you have to do is export partial glossaries in each link point of the old product and import them in the corresponding link point of the new point. Your Keep Original and Fuzzy flags will be honored for each string.
There will be some exceptions. Files hanging directly from the Platform neutral platform can't be part of a partial glossary (because they are not components), and Platform neutral itself can't be selected either, since it is not a component, but a platform. For these few files, you will have to export them individually and reimport them.
If you are a not so good MT user, however, you can just create a new product (or several ones; see next recipe to know why), run File -> Update on them (you'll get a list of all the strings in the ) and then run Edit -> Autotranslate. Most of the strings will be automatically filled, although if you do this you should review them, because for en-US strings with several possible translations, MT will choose one of them, which could not be the one you want.
From CVS to Mercurial in MT
So, you have a Firefox product in MT with a Platform neutral and, inside it, several directories (components in MT terminology) more or less like the second sample above, checked out from CVS. Now, you want to start working directly on mozilla-central (and l10n-central). What should you do?
The first thing to do, once you have your Mercurial local repository up and working, is create a new product... or more. With good oldie CVS, you could checkout just the locale content and, even more, you could checkout just the locale directories you were interested in. With Mercurial, partial checkouts are not possible, so you have your own Mozilla repository full copy (there are alternate solutions; read on).
A bit of history on MT
MT has been evolving from long ago, when L10n were done always on shipped en-US JARs and when Mozilla Suite had five L10n JARs: ab-CD.jar, ab-win.jar, ab-mac.jar, ab-unix.jar and CD.jar. MT thus referred to ab-CD.jar contents as Platform neutral platform, CD.jar as region platform (or regional files) and the other three as Windows platform, Mac platform and Unix platform. This JAR structure is now used just by SeaMonkey 1.1.x.
When Mozilla L10n switched to Source L10n, one of the many problems that MT had to solve were how to fit a directory structure in what had been designed for five JARs, and the patch consisted of providing a read from dir instead of JAR and put everything inside Platform neutral.
That has worked well (OK, more or less) :-) as long as you could instruct MT to use just one root L10n directory, but this is no longer the case with Mercurial.
MT could be changed for a MT product to have a list of root directories instead of just one, and maybe someday it will do, but it will probably won't happen before SeaMonkey 1.1.x dies (and SeaMonkey 2.0 finally conquer the web, if I may add). ;-)
Enough chatting, what's next?
Anyway, we need to workaround the full-fledged repository problem. These are your options:
- create one product for each root directories. This means browser, extensions/reporter, dom, netwer, security and toolkit. Besides that, you will need to create one tiny product for other-licenses/branding/firefox. For each one of the above, the root directory will be .../locales/en-US.
- FrenchMozilla has just announced they are providing an en-US only Mercurial repository comprising both mozilla-central and comm-central. If you are happy with a non-official solution (it's not like if they were third-party, they are your french equals!) ;-) you have a pretty easy and comfortable solution.
- if you are using a filesystem with symbolic links support (i.e., Linux or Mac), you can create symbolic links in a separate directory so it contains just the locale part. Thanks to Alexandru Szasz, from Narro, for this inspiration. See this example for browser.
For the last two options, you should be able to adjust your current MT product paths so you can keep using it just like with CVS. Keep in mind that MT doesn't really know if you are using CVS, SVN or Mercurial. It is just instructed to read directory subtrees and ignore "CVS" and ".svn" directories it finds.
If you have opted for the first solution, you will find yourself with some new products completely untranslated (once you Update each of them). To migrate the existing translation in the old product, you need to export partial glossaries from the old product, selecting the link origin (see the previous section) and importing them into the link target.
Defining symbolic links for browser
This is an example just for browser, without shared components, but it should suffice to get the idea.
; Asumming we are in a directory containing mozilla-central/
$ mkdir locale-only
$ cd locale-only
$ mkdir -p browser extensions/reporter other-licenses/branding/firefox/
$ cd browser; ln -s ../../mozilla-central/browser/locales/; cd ..
$ cd extensions/reporter; ln -s ../../../mozilla-central/extensions/reporter/locales/; cd ../..
$ cd other-licenses/branding/firefox/; ln -s ../../../../mozilla-central/other-licenses/branding/firefox/locales/; cd ../../..