Localising the Lizard
Pages: 1, 2, 3
DTD entities
Entities in XUL are based on the same principle as is common in other XML languages. They are used as a method to reference data that has been abstracted from the content. One common motivation for using entities is for data re-use. This occurs in XUL files, but the main reason for entities is to keep separate the text contained in interface widgets such as buttons and menu items. This ensures that the actual content can remain untouched during the localisation process.
Here is a sample XUL window with a couple of menu items and a "Greetings World" display. View the full code for the file here -- note that some of the lines below may wrap in this view.
<!DOCTYPE window SYSTEM "chrome://navigator/locale/greeting.dtd">
<window id="greeting-window" title="&windowTitle.label;"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
onload = "Startup()"
align="vertical">
<menubar id="main-menubar">
<!-- File menu -->
<menu id="fileMenu" value="&fileMenu.label;"
accesskey="&filemenu.accesskey;">
<menupopup>
<menuitem value="&openmenuitem.label;"
accesskey="&fileopen.accesskey;" oncommand="Open()"/>
<menuitem value="&closemenuitem.label;"
accesskey="&fileclose.accesskey;" oncommand="Close()"/>
</menupopup>
</menu>
<iframe src="chrome://navigator/locale/greetings.html" />
</window>
You'll notice that the entities are referenced using the syntax &text; and that every identifier has to begin with an ampersand (&) and end with a semi-colon (;). How is the DTD file accessed? It is associated with your XUL in the Doctype declaration. If you have a small application, the DTD files can reside in the same folder as your XUL files, but it's good practice to put them into their own locale directory within your chrome structure. Here is the DTD file for the "Greetings" window.
English DTD |
German DTD, using entity references |
|
|
So to translate your XUL interface strings, you change the text that corresponds to your entity reference. Depending on the size of your application, this can be a straightforward or long-winded process. I will talk about tools later that automate the process if you have many files. If you are translating an existing language and not creating from scratch, it is a good idea not to overwrite this base language. Even if not used, it will enable another language version of your Mozilla software to be used at a later stage if needed.
 |
 |
Localised English Greetings window. |
Localised German Greetings window. |
String bundles
String bundles are ASCII text files that contain text that is accessed
in JavaScript and C++ files. They commonly reside in the locale directory with the DTDs. You can set up your string bundle through an XPCOM
component (nsIStringBundleService), which can be set up in your JavaScript. I'd advise you to have a look at that file if you want to find out how to set up the XPCOM component. If you don't fancy doing that yourself, Mozilla has some common utility functions that do it for you. So
all you have to do is include the following file in your script:
<script type="JavaScript" src="chrome://global/content/strres.js"></script>
Then set up your bundle as follows:
var bundle = srGetStrBundle("chrome://mypackage/locale/mypackage.properties");
And the last step in the process, getting at the strings:
var greeting = bundle.GetStringFromName( "hello" );
This would retrieve the string corresponding to "hello" in your bundle file. There is an alternative method using an XBL binding. There is a binding element called <stringbundle>. It would be included in your XUL file like:
<stringbundle id="historyBundle" src="chrome://mypackage/locale/mypackage.properties"/>
Then the bundle can be accessed as follows.
var bundle = document.getElementById("stringBundle");
var greeting = bundle.getString("hello");
The advantage of this approach is that there is no overhead of including another JavaScript in your XUL file, plus the fact that the binding can be cached for quick access.
Other file types
In addition to the XUL, JavaScript, and C++ files, there may be some other files that you need to translate. In Mozilla, these include HTML files and RDF files. An example of an HTML file would be the "About Mozilla" page. Open up your Mozilla browser and type about: in the location bar. HTML files are a useful way of presenting information about your package or application, and localisation of this information can be important.
RDF is used in Mozilla as a way of accessing and storing metadata or dynamic data. The sidebar contains tabs for accessing commonly used features of the browser, such as searching and bookmarks. The notation used in the RDF is similar to the XUL entities, but in this instance they are contained inline in the file. Here are the Inline entities taken from 'panels.rdf' in Mozilla distribution:
<!DOCTYPE RDF
[
<!ENTITY sidebar.panel.whats-related "What's Related">
<!ENTITY sidebar.panel.search "Search">
<!ENTITY sidebar.panel.tinderbox "Tinderbox">
<!ENTITY sidebar.nc-panel.stocks "Stocks">
<!ENTITY sidebar.panel.client-bookmarks "Bookmarks">
]
>
If you go about translating the whole Mozilla application, you'll find that there are some words or phrases that will remain untouched. These will include terms that are used for branding, or universal terms of web browsing such as "Bookmarks," "Tasks," and "Tools." In some instances, the choice to translate some of these terms is purely subjective.
