by Tao Cheng

XUL, pronounced as /zool/, stands for "XML-based User Interface Language", is a cross platform way of describing user interface. It is used to construct the graphical user interface for the Mozilla browser client. Ideally, XUL documents are internationalization friendly since it is XML-based and all XML processors must support Unicode encoding (the UTF-8 and UTF-16 encoding of 10646). In reality, a typical XUL file may contain standard XML (eXtensible Markup Language) elements, XUL specific elements, style information (currently Cascading Style Sheets), HTML (HyperText Markup Language), and JavaScript functions. With such great variety of source types, localization enabling of XUL documents becomes quite a challenge.

This paper gives a brief introduction to the concept of XUL and then examines the principles, including adoption of Unicode (UTF-8) as the standard document encoding, of seeking localization solutions. After that, it dissects the components of a XUL document and identifies resources to be localized. It then recommends a set of XUL coding style guidelines to ensure the localizability of XUL documents.

While the localizability solutions proposed are for XUL, most of them can be applied to general Web document authoring for customization.

XUL is an XML-based user interface description language. Mozilla developers invented it to describe graphical user interface uniformly across platforms.

The best way to understand XUL is by going through a real example. In this section, the author uses a sample XUL document, "openLocation.xul", listed in Appendix A, for the purpose of illustrations. This XUL document describes a dialog window that prompts the user to enter a URL to be loaded in the browser window.

A typical XUL document contains the following types of data:

• XML declarations and elements. XUL is XML. It follows standard XML syntax for element type declaration. Mozilla intends to support standard XML syntax recommended by XML spec. 1.0. For example,

• UI elements and tags. Since the purpose of XUL is to describe graphical user interface, the majority of the XUL specific elements are UI primitives and controls. Examples of these range from primitive UI controls, such as menus and command buttons, to more comprehensive composite widgets, such as Tree widget, ComboBox, and File Picker.

• HTML markups. As with XML documents, HTML tags can be used to mark up content data in XUL documents. HTML markups live in HTML namespace and prefixed with "html:" to distinguish them from general XML markups. For example,

1. </html:table>

• Style and layout. XML, as well as XUL, syntax does not bear any display or layout semantics; instead, a style sheet is utilized for such purpose. As of now, CSS (Cascading Style Sheets) is the supported method of specifying display style and layout geometry of XUL-based graphical user interface. Line 2 in the example below associates the CSS style sheet, "xul.css", with this XUL document.

• Script functions. A graphical user interface must provide a mechanism for event-handling and user interaction. Like HTML forms, scripting languages such as JavaScript are used to serve such purpose. The JavaScript file, "openLocation.js", referenced in the following code segment, contains all JavaScript functions needed to process events occurring in this window. The source listing of "openLocation.js" can be found in Appendix B.

• Chrome URLs. Chrome, in the XUL world, is the top level window which contains groups of UI elements of various types. Examples of chrome are the browser window and dialog windows. The chrome obtains its UI description from four types of providers: the content provider, the skin provider, the platform provider, and the locale provider. While the content provider provides the skeleton, i.e., the menus, command buttons, and etc., the skin provider supplies the look-and-feel of the chrome. Similarly, the platform provider gives platform dependent UI description and the locale provider offers the language and culture sensitive resources.

Finally, the dialog constructed from the XUL file, "openLocation.xul", is shown in Figure 1.

Examining the ingredients and structure of a XUL file, there are several advantages:

• Scriptable. Changing UI without recompilation. Applications development cycle is dramatically reduced. The browser client acts as an interpreter. An embedded user agent loads a XUL stream and builds the user interface on the fly. The UI controls and user interaction can be modified statically or dynamically.

• Cross-platform. The underlying XUL parser and interpreter are developed in a cross-platform fashion. The same XUL stream can be shared independent of Operating systems and Window systems. While Mozilla officially supports Linux (Unix), Win32, and Mac, it also provides a set of guidelines for porting Mozilla onto other Operating systems and Window systems.

• Customizable. With the introduction of "Configurable Chrome", all components of the chrome can be configured either statically in the chrome registry or dynamically on the fly. The chrome registry is stored in RDF format and can be edited by plain text editor or runtime JavaScript functions.

Consisting of such great variety of ingredients, XUL localization becomes a challenging task. Historically, we encountered some difficulties in localizing Web-based documents:

• Locale sensitive data is hard to separate from the rest of the document. Localizable resources reside in the same file with language and culture neutral data. Localizing Web-based documents often means going through the whole set of document to identify and translate localizable resources.

• Markup tags are often translated or damaged in the process of localization. Validating the localization results is difficult, if not impossible.

It is the desire of the Mozilla Internationalization group to address these issues in the XUL world.

Before embarking on the solution-seeking journey, let’s layout a set of criteria we intend to meet:

• Standard Compliant. We shall avoid re-inventing the wheel. Both existing internationalization solutions and new proposals shall be taken into consideration. We will weight in standard compliance in the decision making process against proprietary approaches.

• Simple. The localizability solution shall be easy to implement, and will integrate seamlessly with core development. A localizability solution often needs the support from peer development groups. Should localization enabling become a burden or even hinder the development process, the proposed solution would less likely be accepted by supporting module owners.

• Leveragible. Leveraging can be defined as taking the localization results of previous releases for the use of the current release. A full-scale localization of a huge software product is not only time-consuming but also costly. It requires collaborative effort from localization engineers, translation vendors, and internationalization QA throughout the whole process. It is neither economic nor efficient to repeat the whole process from scratch for each release. Leveraging also helps improve the consistency of translation between releases.

• Portable. The final solution will be achievable on all platforms including Unix, Windows, Mac, and others. We do not want a solution for one platform and another solution for the other platform. The majority of Mozilla modules are platform-independent, so will be the localizability solution.

• Extensible. Technology evolves. A solution adopted now might not be valid in the future, however, we want it to be flexible enough for future extension.

• Separable. To simplify the localization task, localizable resources shall be placed into external files so that the translators can concentrate on localization instead of language or culture neutral resources.

• Consistent. If possible, we shall seek a scheme that will work across modules instead of within the XUL component only. We don't want to have distinguished solutions for different modules.

• Dynamic binding. Some of the resources requiring translation may be dynamic, usually because they require string composition, e.g., "Installing item 5 of 10".

• Validatable. The result of localization shall be easily validated. Translators need to be able to verify the result as they progress.

• Parseable. It should be possible to unambiguously and automatically determine which embedded items contain localizable text, and which items need not be localized.

• Invisible (Internationalization). As much as possible, the standard tools that create English UI should emit files that are ready to be localized, without requiring additional processing. We want to make the localizability solution a part of the standard XUL authoring process instead of internationalization specific action. Localizability shall not be the only reason we adopt the solution.

• Efficient. The implementation of the solution shall not cause any noticeable performance degradation or memory bloat.

While it might not be feasible to find a solution that satisfies all the criteria, they shall be used as the factors in decision making.

Localizability enabling requires the participation of various groups in product development. While it is the Internationalization and Localization groups that drive the effort, co-operation from the rest of the groups is essential to the success of the process. In this section, the author will present all the solutions proposed by developers from interested groups. Each will contain descriptions, samples, and analysis of pros and cons.

5.1 Proposed solutions

In the process of seeking localizability solutions, four approaches are proposed and reviewed. While varying in how to identify and represent locale sensitive resources, they all attempt to isolate localizable resources from language and culture neutral data.

1. "XUL + Language-specific DTD".

• In this approach, we declare general (text) entities for all locale sensitive resources in an external DTD (Document Type Definition) subset and use XML entity reference, "&entity;", to reference them.

• Already standard compliant; no new syntax names or tags need to be introduced.

• Text replacement can be in either content or attribute values (but not in the attribute names).

• The language-specific DTD file is not a flat file. We need a DTD parser to extract entity values into a flat file for localizers.

• Two file formats to deal with, the DTD file and the property file, from which other client modules retrieve the locale sensitive resource strings [1].

• Hard to group text entity by resource types. The entity name alone does not provide any resource type information which could be used as a localization note to the translators.

• In switching languages, we need to tear down the chrome window, reload the XUL and its DTD (probably from a remote host), and reconstruct the DOM tree (the whole chrome). This could be a very expensive operation for a low-end client machine fetching XUL components from a remote host.

1. "Resource ID + String Resource Manager".

• In XUL file, assign a widget ID, e.g. widgetID, to each UI element and a resource tag, e.g. resTag, to each localizable attribute of the widget. Then, during widget initialization, call a C function, said gettext(widgetID, resTag, default_string), to retrieve the resource from a Java-like property file. For example, a label widget can be described as <label widgetID="345" text="label string"/> in a XUL file. Then, the function call to retrieve localized text will be gettext(345, RES_TEXT, "label string").

• The English version of property file will be automatically generated during XUL to DOM conversion. The front-end developers can easily update a UI element's attribute/resource without leaving the XUL file.

• All localizable resources are uniquely identified by the combination of widget ID and resource tag.

• In function "gettext()", if the property file does not exist or the combination of widget ID and resource tag does not resolve to a resource string, the "default_string" will be returned instead.

• Core development work will not be blocked by gettext() implementation. However, we shall request the UI developers to put localization notes, and comments in the property file.

• The property file is a flat file in clear text; it is easy to localize and leverage.

• Consistent with the scheme the rest of the client modules use; only one file format to deal with.

• Resources are grouped by widgets. This also makes the property file more readable.

• Easy to leverage. All resources are uniquely identified and ready for comparison.

• Need to treat content data as the text resource of a label widget so they can be identified and modified by application code.

• Implementation work needed to automatically bind localizable resources to widgets. However we can reduce extra work by binding the resources during widget initialization. We need to bind the UI attributes specified in XUL to the real widgets anyway.

• Need to ensure the uniqueness of the widget ID within and across XUL. However, the application developers need to have a way to uniquely identify a widget in chrome anyway.

• Localizable resource strings are duplicated twice: once in XUL and again in property file.

• Technical difficulty: once XUL has been converted to a DOM tree, the content can't be changed any more.

1. XPointer and XLink.

• Since it is all written in plain XML there is no need to create custom file types. Thus this system can accept anything the parser can handle. It maintains the name value paring essential for localization. It allows us to add localization and developer notes to the object (e.g. button) and the localized text separately, but maintain a direct link between the two. The text is pulled into the UI elements when the XUL file is parsed. This also addresses the goal of separating markup, style and content.

• This does not leave us with a flat file solution. However, the file containing the text to be localized is of such a simple format that writing a tool to parse it is a trivial exercise. We will need some form of tool to convert native encoding to Unicode character references.

• There are 4 files to track! Actually the language specific DTD is complete and valid as is, so it could easily be declared inline in the language specific XML file. The link-attributes have been entitized and could conceivably be inherited from a higher level DTD.

• In reloading downloadable chrome, not all related files can be destroyed and rebuilt by the client.

1. "@resourceID"

• If all this worked, we'd be free to add localizable text anywhere without constraining the element and attribute structure. Content data could be uniquely identified and externalized.

• The entity solution, "XUL + Language-specific DTD", is more XML compliant and less work to implement.

5.2 The final decision - "XUL + Language-specific DTD".

All proposed solutions except (a), "XUL + Language-specific DTD", are filtered out due to the technical difficulties or drawbacks highlighted by bold face in their "cons" lists. It turns out that the DTD solution also satisfies the majority of our criteria. One obvious advantage of the DTD solution is that it is an application of the standard feature recommended in XML specification 1.0. It’s easy to convince the XML parser developers to support this feature. For the same reason, XUL writers are more likely to adopt this strategy due to its standard compliance.

Now that we have a solution for localizing XUL, the next step is to identify what resources are localizable. The rule of thumb is- "all resources that contribute to the appearance of the chrome are localizable". Let’s take a close look at them.

• Widget resources

• All texts in the graphical user interface are localizable. Examples include menu label strings, dialog and windows title strings, tooltip strings, status text, etc.

• URLs to localizable images. While some icon images in one culture are popularly used, they might not be appropriate in other cultures. We need the ability to customize them to fit local cultures. Note that it is the URL to the image that we will localize instead of the image data itself.

• Content data. This includes both plain text and HTML tagged data.

• Style information such as font, size, and color, may need to be localized. For example, while color white is the symbol of purity in one culture, it is a color of sorrow and sadness in another.

• The geometric layout. We may (rarely we hope) need to modify the layout. For example, some English radio buttons are laid out horizontally, but their German version could make them too wide. Under such circumstance, we might want to arrange them vertically.

Now that we have the knowledge of how and what to localize, we need a set of XUL authoring guidelines to ensure that XUL files are localizable. Although, localizability is the main goal here, most of the guidelines are considered good XML authoring practices for ensuring portability and customizability.

• Convert HTML files to XUL files. All UI descriptions written in HTML shall be converted into XUL. Currently, we do not have a clean way of localizing HTML files. XUL is our UI description language. In addition, there are certain XUL specific features, such as XUL fragments, which are supported in XUL content model only.

• The XML declaration. All XML declarations shall contain the following information:

• Version number. Version number indicates that this XML document conforms to a particular version of XML specification. It is provided as a means to allow the possibility of automatic version recognition, should it become necessary. Processors may signal an error if they receive documents labeled with versions they do not support [4].

• UTF-8 encoding. Wherever applicable, the recommended encoding of the content data and attribute values is UTF-8. In Mozilla, when such information is not specified, UTF-8 is the default encoding of all XML, XUL, and RDF documents. There are a couple of reasons we adopt UTF-8:

• According to XML specification 1.0, all XML parsers must support UTF-8 encoding. Using UTF-8 guarantees our document encoding is portable across user agents (parsers).

• Multi-lingual display is a requirement of the Mozilla browser and Unicode encoding covers all the languages we support.

• Style sheet. An XML file must have a style sheet associated with it, otherwise, it won't know how to display the document. Note that, as suggested below in "Configurable Chrome", chrome type URLs shall be used to reference the style sheet.

• Namespace. In XUL documents, namespace shall default to "xul" and be declared in the root element. Other namespace referenced shall be declared before use and preferably in the root element of the document. See the sample XUL declaration below for illustration.

• Case sensitivity. Be aware that XML is case sensitive. In compliance with XHTML working draft [5], all element and attribute names shall be in lower case.

• Chrome URLs. All resource references in XUL shall use the chrome type URLs instead of hardwired URLs. The rules are:

• Place all platform and language neutral files in content/ and skin/ directories.

• Place all locale and platform sensitive files under their specific sub-directories such as "navigator/locale/en" and "navigator/platform/unix". Note that all languages and platforms are treated equally and stored in their respective sub-directories. Candidates of such files are platform-specific style sheets and language-specific DTD files.

• JavaScript functions. JavaScript code shall be moved out of XUL. That is, instead of writing them inline as

We move them into a foo.js file and declare its URI in this fashion:

<html:script src="foo.js" encoding="UTF-8" />

(Refer to http://www.w3.org/TR/REC-html40/interact/scripts.html#edef-SCRIPT

for the official specification of this syntax)

The advantages of this are:

• Legibility. The main purpose of the XUL is to describe the UI content. As style information shall be in style sheet, JavaScript code shall be in *.js as well to keep the main XUL file clean. In some XUL files, JavaScript code takes up 20-25% of the length of the file. Often times, we need to go to the very bottom of the file to find the UI descriptions.

• Maintainability. By putting JavaScript code in external files, we can isolate the function declaration in a separate file. The developer does not need to touch the main XUL to change its runtime behavior.

• Flexibility. Since the JavaScript code is in an external file, customization can be achieved by switching the JS file. With chrome registry, developers, content providers, or even the end users will be able to edit the registry table to use a customized JS code for their browser client.

• Widget resources. To make a widget attribute localizable, its value string must be declared as the value of a text entity and referenced by its entity name.

• The entities to substitute attribute values of a widget shall be named after the widget ID (or widget element names if no ID is assigned.)

• Content data. Content data, either in plain text or HTML/XML tagged, need to be declared as general entities in the external DTD and referenced in XUL stream.

• Content containing markups shall be separated from plain text data. Localizing plain text is much easier (and cheaper) than localizing markup tagged data. See the example for illustrations.

• Content text forming a complete sentence shall be declared in one single entity. We try to avoid placing markups in entity declaration; but the rule, "forming a complete sentence", takes precedence when there is a conflict. Translating broken sentences is not only painful but also error-prone. Here are examples of HTML tagged data which shall be declared as one entity:

• A list item (as opposed to the whole list.)
• A table cell (as opposed to the whole table.)
• A paragraph (as opposed to the whole chapter).
• And many others (such as framesets...).

In the past, localization enablement used to be considered as a downstream task in the process of software development. This is actually a misconception. Internationalization enablement must be taken into account in the early phase of product planning. Localizing a software product with no underlying internationalization support is nearly tantamount to rebuilding the whole product. It is both tedious and difficult if not impossible.

Two important features of the XUL technology constitute the localizability of XUL-based UI:

• the parser support of text entities in the external DTD subset;
• the "Configurable Chrome" feature

While the DTD features externalize the localizable resources, the "Configurable Chrome" feature allows the browser client to load language-specific files dynamically.

Localization enabling is a collaborative effort. It demands an enormous amount of communication and co-operation from all component owners. At the same time, the quality of the whole product also improves since the adoption of Unicode as the standard data encoding makes the internal data exchange more consistent and reliable and thus reduces the chance of data loss and corruption.

XUL style guidelines for externalizing text entities, style sheets, JavaScript functions, etc. are widely supported by the front-end developers. They have been adopted as a way of componentizing XUL files such that files are legible, maintainable, and customizable.

The author would like to thank Bob Jung, Katsuhiko Momoi, Erik van der Poel, Montserrat Sanz, and Yung-Fong Tang for their tireless guidance in his exploration of the Internationalization and Localization world. His appreciation also goes to Tague Griffith who inspires the idea of writing down this paper. Finally, he would like to direct his appreciation to Shani Parrott and Katsuhiko Momoi for proofreading this paper.

1. Sample XUL document: mozilla/xpfe/broswer/src/openLocation.xul

1 <?xml version="1.0"?>

2 <?xml-stylesheet href="xul.css" type="text/css"?>

3

4 <!DOCTYPE window>

5

6 <window xmlns:html="http://www.w3.org/1999/xhtml"

7 xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"

8 onload="onLoad()"

9 title="Open Location"

10 width="420"

11 height="190">

12

13 <html:script language="javascript" src="openLocation.js">

14 </html:script>

15

16 <broadcaster id="args" value=""/>

17

18

19

20

21 <html:center>

22 <html:p/>

23 <html:table width="400" cellspacing="5">

24 <html:tr>

25 <html:td>

26 Enter the World Wide Web location (URL) you would like to open. Use

27 the Choose File... button to select a local file:

28 </html:td>

29 </html:tr>

30 <html:tr>

31 <html:td>

32. <html:table cellspacing="5">
33. <html:tr>
34. <html:td width="275">
35. <html:input id="dialog.input" style="width:275;"
36. onkeyup="onTyping(event.which)"/>

37 </html:td>

38 <html:td width="100">

39 <html:button onclick="choose()">Select File...</html:button>

40 </html:td>

41 </html:tr>

42 </html:table>

43 </html:td>

44 </html:tr>

45 <html:tr>

46 <html:td>

47 <html:table cellspacing="5">

48 <html:tr>

49 <html:td width="165">

50. <html:input id="dialog.newWindow" type="checkbox"/>

51 </html:td>

52 <html:td width="70">

53. <html:button id="dialog.ok" onclick="open()"

54 </html:td>

55. <html:td width="70">
56. <html:button id="dialog.cancel" onclick="cancel()"
57. disabled="">Cancel</html:button>

58 </html:td>

58. <html:td width="70">
59. <html:button id="dialog.help" onclick="help()"
60. disabled="">Help</html:button>

61 </html:td>

62 </html:tr>

63 </html:table>

64 </html:td>

65 </html:tr>

66 </html:table>

67 <html:p/>

68 </html:center>

69

70 </window>

B. Sample JavaScript file, openLocation.js, associated with the XUL document in Appendix A.

21 var toolkit;

22 var browser;

23 var dialog;

24

25 function onLoad() {

26 dialog = new Object;

27 dialog.input = document.getElementById( "dialog.input" );

28 dialog.ok = document.getElementById( "dialog.ok" );

29 dialog.cancel = document.getElementById( "dialog.cancel" );

30 dialog.help = document.getElementById( "dialog.help" );

31 dialog.newWindow = document.getElementById( "dialog.newWindow" );

32 dialog.args = document.getElementById( "args" );

33

34 toolkit = XPAppCoresManager.Find( "toolkitCore" );

35 if ( !toolkit ) {

36 toolkit = new ToolkitCore();

37 toolkit.Init( "toolkitCore" );

38 }

39

40 browser = XPAppCoresManager.Find( dialog.args.getAttribute( "value" ) );

41 if ( !browser ) {

42 dump( "unable to get browser app core\n" );

43 //toolkit.CloseWindow( window );

44 }

45

46 /* Give input field the focus. */

47 dialog.input.focus();

48 }

49

50 function onTyping( key ) {

51 // Look for enter key...

52 if ( key == 13 ) {

53 // If ok button not disabled, go for it.

54 if ( !dialog.ok.disabled ) {

55 open();

56 }

57 } else {

58 // Check for valid input.

59 if ( dialog.input.value == "" ) {

60 // No input, disable ok button if enabled.

61 if ( !dialog.ok.disabled ) {

62 dialog.ok.setAttribute( "disabled", "" );

63 }

64 } else {

65 // Input, enable ok button if disabled.

66 if ( dialog.ok.disabled ) {

67 dialog.ok.removeAttribute( "disabled" );

68 }

69 }

70 }

71 }

72

73 function open() {

74 if ( dialog.ok.disabled ) {

75 return;

76 }

77

78 var url = dialog.input.value;

79

80 if ( !dialog.newWindow.checked ) {

81 /* Load url in opener. */

82 browser.loadUrl( url );

83 } else {

84 /* User wants new window. */

85. toolkit.ShowWindowWithArgs( "resource:/res/samples/navigator.xul",

86 }

87

88 /* Close dialog. */

89 //toolkit.CloseWindow( window );

90 }

91

92 function choose() {

93 /* Use existing browser "open" logic. */

94 browser.openWindow();

95 //toolkit.CloseWindow( window );

96 }

97

98 function cancel() {

99 if ( dialog.cancel.disabled ) {

100 return;

101 }

102 //toolkit.CloseWindow( window );

103 }

104

105 function help() {

106 if ( dialog.help.disabled ) {

107 return;

108 }

109 dump( "openLocation::help() not implemented\n" );

110 }