Mozilla localization quick guide |
|
Mozilla Localization Project Staff |
MLP [Localization Project home] | [Localization docs] | [Quick guide]
Introduction |
This document shows a step by step approach for the localization of Mozilla, directly manipulating its resource files. This document is mainly focused in giving a general idea of the typical structure of the localizable resources of Mozilla.
There are also specific tools available, created with the aim of a simpler (automatic) management of these resources. This hides many tedious technical details from the localizer. In any case, this document can help to give an insight on how to directly access the resources and solve possible problems.
Most of the localizable resources in Mozilla are externalized into files in the following directories:
- chrome files
in [install-dir]/chrome/{en-US.jar, en-mac.jar, en-unix.jar,
en-win.jar}:
switchable UI resources. - regional contents in [install-dir]/chrome/US.jar :
switchable regional specific external references. The localization process for these files closely follows the procedure for chrome files. See "Regional Content Bundling" for details. - profile defaults (optional)
in [install-dir]/defaults/profile/[region-locale-code]/* :
files to be copied into new user profile directory. They're selected according to the currently active regional contents.
Chrome files |
In Mozilla, most UI resources are located in the chrome/ folder of the install directory. The original localizable files are packaged as:
- en-US.jar: contains nearly all the UI language resources.
- en-win.jar (for Windows): contains all the Windows specific UI resources. Similarly, for Unix and MacOS, there are en-unix.jar and en-mac.jar.
- US.jar: contains all the regional contents (URLs) resources.
Starting from this material, let's try to obtain a copy of the same resources localized in the wanted locale language:
- To work on the resources they contain, extract them with a
conventional zip archiver utility
into an empty directory, preserving the directory structure.
- Rename the en-US/ folder to your
locale code, and the
US/ folder to your
region code.
- Replace inside all the contents.rdf files "en-US" with your
locale code, and (only
for files from US.jar) "US" with your
region code.
Then modify all the values assigned to the following properties to a relevant new value:Property name Meaning displayName String the user will see in the user interface, as selectable language or Content/regional pack. (E.g. UI language: "Italian"; Content pack: "Italy Region") author Name of the localizer(s). name Locale/region code. localeVersion Mozilla version string of the target localized release. (E.g. "1.3b" or "1.0.2" for Mozilla version 1.3 beta or 1.0.2) previewURL (OPTIONAL) URL to a 355x85 pixel image with a preview of the localized program.
You'll find out that you need to work on some different file types. Let's see how to work on them type by type.
DTD files (*.dtd) — Text files UTF-8 encoded.
A DTD file contains a list of entities that need to be localized. The entities here defined are then used inside the user interface XUL files. An entity declaration looks like this:
- <!ENTITY openCmd.label "Open Web Location...">
Above, the entity with name/key "openCmd.label", has been assigned the value "Open Web Location...". The entity value is what needs to be localized. Usually the entity name (e.g. "openCmd.label") is self-explanatory: this one is the label of the Open menu command. If this is not enough, the author of the file adds a comment for the localizer. Comments referring to a particular entity are placed right above the entity declaration as:
- <!-- LOCALIZATION NOTE (entity_name): comments -->
For example,
-
8<!-- LOCALIZATION NOTE throbber.url: DONT_TRANSLATE -->
9<!ENTITY throbber.url "http://www.mozilla.org">
Note that these documents are UTF-8 encoded. Hence, you'll either need a text editor able to save the file in UTF-8 once modified, or you will be required to convert it back to UTF-8 after. If you skip this passage, you won't be able to correctly show characters different from the conventional ASCII ones ( a-z , A-Z , 0-9 , !"#$%&'()*+,-./ :;<=>?@ _` {|}~ ), like diacritics or eastern scripts.
Also remember you can't directly use the & < " % characters in your strings. Instead, substitute one of their predefined entities inside the string.
Property files (*.properties) — Text files escaped Unicode encoded.
As the name says, in these files a number of JavaScript properties (think about them as variables) are assigned with a string value. String resources in property files appear in the form:
- property_name = Text Text Text
- 25
#-----------------------------------------------------------
26 # LOCALIZATION NOTE InstallFile:...
27 #-----------------------------------------------------------
28 InstallFile=Installing: %s
29 ReplaceFile=Replacing: %s RDF data source files, (*.rdf) — Text files UTF-8 encoded, if not otherwise specified.
These rdf files control locale-specific UI menu hierarchy declarations:
- communicator/taskbar.rdf — describes the Taskbar menu (not longer visible in mozilla.org recent builds).
- global/builtinURLs.rdf — describes the URLs associated to various menu items scattered across toplevel menus, such as "Help", "View|Set Language/Region >".
The string at the right side of the equal symbol is what needs to be localized. Again, localization notes and comments are often useful to explain what the string's usage in the UI is or a particular behavior the localizer should follow working on them:
As for the DTD files above, the same considerations apply about the
file encoding. Mozilla will expect these files escaped Unicode
encoded.
Remember to avoid the direct usage of backslash, single or double quotes
in your strings. Use one of their substitutes
instead. Don't break these strings on multiple lines.
Many strings contains strange symbols like %s or $1%s. They will be substituted at runtime by relevant words. Place them in your strings as makes sense in the whole sentence, typing them exactly as found originally.
Now let's see how to proceed with our work:
The next step is of course localize the string contained throughout the numerous dtd and property files. Note that the global/ folder and the files right below the communicator/ one contain strings reused multiple times across the various applications.
Many command strings (especially menu items strings) have an associated "AccessKey" and "CommandKey", with the same name. The value assigned is a single letter.
AccessKeys are the main key string letter underlined in the UI, which will enable the activation of its associated function through an Alt+[letter] keypress. Accesskeys underline the relevant menu item letter in a case sensitive way.
CommandKeys, for the same menu action, enable a Ctrl/Cmd+[letter] key sequence, application wide.
Both AccessKeys and CommandKeys work with Latin (occidental) letters only.The contents of en-mac.jar, en-unix.jar, and en-win.jar are operative system specific. They contain the common menu items (such as File, Undo, Redo..) and their keyboard shortcuts. They have to follow each system's conventions.
Archive back all your work inside new jar files. You can create them as conventional zip files, with a .jar extension. The jar files take their names from the locale code you've been registered under.
Download from your Mozilla release folder the langenus.xpi installable package, inside WINDOWS-XPI/ (right click on its name, and use Save target as...).
Unpack it using a zip archiver utility, modify the localizable fields in the install.js file, and use it as template for your own installable language pack.
Profile Defaults |
Location: defaults/profile/[region-locale-code]
Contains the user profile template files, copied as defaults during profile creation to a new profile folder:
- bookmarks.html -- default bookmarks.
- localstore.rdf -- define default windows settings.
- mimeTypes.rdf -- define recognized file mime types for the Helper Apps.
- search.rdf -- define the default search engines.
- panels.rdf -- define the default panels in the Sidebar.
- chrome/userContent.css -- example of user defined default styles for HTML documents.
- chrome/userChrome.css -- example of user defined default styles for user interface.