How to Localize a Mozilla Extension?
This document is written for non-techies. Its goal is for everyone to understand Mozilla extension localization without having to read other articles. So, if you don't understand something, it's likely not your fault, and please send your question to the author Daniel Wang
Understanding .xpi Install Package
An .xpi install package is actually a normal zip file. After you decompress it you should see an install.js install file and other resource files. Resource files may appear in two forms, 1) a compressed zip archive with .jar file extension, or 2) uncompressed files in their original forms.
Example 1 of extension.xpi Uncompressed
install.js extension.jar
Example 2 of extension.xpi Uncompressed
install.js
resources/
+- content/
| +- content.rdf
| +- extension.xul
| +- extension.js
| +- ..
|
+- locale/
+- en-US/
+- content.rdf
+- extension.dtd
+- extension.properties
+- ...
Under the locale folder, you will see other sub-folders named after
ISO language codes, e.g. en-US (English US). For French, the code is
fr-FR
. We are primarily interested in files in these language folders.
These files and install.js are all text files, and they
can be read and modified using Unicode editors. Things
you need to do for localization will be explained in the next few sections.
Adding a Language Pack into a Extension
To add a language pack in your language, first copy the en-US
folder and name it after your language code, e.g. fr-FR.
Open the contents.rdf text file in your new language folder.
Change all instances of en-US
to your language code, for example
<RDF:Seq about="urn:mozilla:locale:root"> <RDF:li resource="urn:mozilla:locale:en-US"/> </RDF:Seq>
is changed to
<RDF:Seq about="urn:mozilla:locale:root"> <RDF:li resource="urn:mozilla:locale:fr-FR"/> </RDF:Seq>
Next, open the install.js text file, and search for lines like the following
(hint: look for the worden-US
):
var returnval = registerChrome(LOCALE | DELAYED_CHROME, calendarLocale, "en-US/");
Make a copy of this line below, and change en-US
to your language code, e.g.
var returnval = registerChrome(LOCALE | DELAYED_CHROME, calendarLocale, "en-US/"); var returnval = registerChrome(LOCALE | DELAYED_CHROME, calendarLocale, "fr-FR/");
Now, re-package the extension into an .xpi file.
Note that the file directory hiearchy should be the same before and after
the re-packaging. For example, if your .jar file had the
following hiearchy:
content/
locale/
it should not change to
extension/ +- content/ +- locale/
Finally, drag the .xpi file to Mozilla to (re)install the extension. If installation is successful, then you have applied the above changes correctly.
Choosing the Right Text Editor
To edit your language files, you need the proper editor. Mozilla has some special formatting requirements, so your editor should have at least the following:
- Support for UTF-8 file
- Can choose to leave out the Unicode signature, BOM (Byte Order Mark, U+FEFF)
- Support escaped Unicode (\uXXXX).
Unfortunately, Notepad on Windows 2000 or XP does not support the second item, so you need some other editor. Here are some suggestions:
- UniRed: freeware, easy to use
- SC UniPad: the trial version has limit on file size, and it is quite expensive. Good features all around, but may not be a good choice.
For using these editors, read Mozilla Localization Tools.
Editing Language Files
Now you have a language pack, but it still displays English. The next step is translating the UI text to your language. To translate an extension, you can change the original files, repackage, and then reinstall, but that is probably too troublesome to many. I recommend that you directly modify the files Mozilla saved on installation. These files can be found under the chrome sub-directory in the Mozilla installation directory, and they should appear the same way as their original compressed or uncompressed form. For example, they may be C:\Program Files\Internet\Mozilla1.6\chrome\chatzilla.jar or
C:\Program Files\Internet\Mozilla1.6\chrome\calendar\ +- content +- locale | +- en-US | +- fr-FR +- skin
(Note, extension may also be installed into your profile.)
To avoid file access conflict, you should exit Mozilla first before re-saving files. In addition, changes may take effect after a Mozilla restart. (Although you still need to restart Mozilla, you at least avoid having to repackaging the .xpi file and reinstalling.)
In your language folder, you will find one or more .dtd files which define UI text. You should see lines like the following:
<!ENTITY alarm.units.hours "Hours" >
What in the quotes are UI text. Just translate them into your language, for example,
<!ENTITY alarm.units.hours "Heures" >
When you save .dtd files, save them in the UTF-8 format. Note that .dtd files cannot have BOM signature.
In your language folders, you may also see some .properties
files. These files are for dialog text and text that change dynamically. The text format is
escaped Unicode (e.g. é
is saved as \u00e9
).
You will see lines like the following:
Cancelled=Cancelled
The text after the equal sign is the UI text. Translate it, e.g.
Cancelled=Annulé
(or)
Cancelled=Annul\u00e9
After you have translated .dtd and .properties files, you are done. Remember to send your work (e.g. the locale/fr-FR/ part) to the author of the extension so everyone can use it.
Editing the install.js File
Some extension install files may ask the user where to install the extension (Mozilla install directory or profile), or they may have other dialogs. To help users speaking your language, you may translate the dialog text. When you save the install.js file, save it in the escaped Unicode format.
If you translate the install file, you may need to contact the extension author to see if s/he will create a package using your translated install file or if you need to host the package on your own site.
Important Notes
- Remember to change content.rdf (e.g. change
en-US
tofr-FR
) - .dtd files are in the UTF-8 format. Remember they cannot have BOM.
- Text in .properties files are in the \uXXXX format.
- Remember to regularly check settings of the file format
- When Mozilla has problem starting up, it won't tell you what the problem is (e.g. you don't know if the file format is wrong or if you have a syntax error), so remember to test your work in Mozilla regularly.
- When you install the extension for the first time, you are recommended to back up the c:/program file/mozilla.org/mozilla/chrome/installed-chrome.txt file. If you have problem installing the extension, you can just restore the installed-chrome.txt file and not reinstall Mozilla.