XUL Coding Style Guidelines

Introduction

XUL, pronounced as "zool", stands for "XML-based User Interface Language", is a cross platform way of describing user interface. It could contain XUL specific element types for UI controls, HTML4 markups for content data, and even JavaScript for user event handling. To make XUL files easy to read and maintain, localization friendly, and portable across user agents, we need to have a set of coding style guidelines to ensure our objectives are achievable. The author has collected a set of guidelines from various sources listed in the References section. While some of the guidelines are recommended practices, the others are mandatory.

XML, XUL, HTML, and XHTML guidelines

The following are considered good coding style for XML/XUL documents. Disobeying them might not cause any parsing error for now, however, it might cause future maintenance headache:

  • convert HTML files to XUL files.
  • use the XML declaration.
  • use Namespace.
  • case sensitivity.
  • use chrome URLs.
  • JavaScript code shall be moved out of XUL.
  • DTD declaration.
  • predefined Entities.
  • Other guidelines mentioned in XHTML 1.1 Recommendation.

See details here.

Making XUL localizable -- mandatory

In the past, UI (display) related resource descriptions are stored in *.rc (for Windows client) or *.ad (for UNIX client) so that they can be localized for a specific language or culture. In the new world, Mozilla 5.0, this is not true any more. Most of the windows and dialogs in Mozilla will be described using XUL.

To make XUL stream/file localizable, several guidelines are to be adopted to make the translation work easier and less error-prone. The issues are discussed in details here:

What is localizable?

  • Widget resources
  • Content data
  • Style info
  • Layout geometry

How to make them localizable?

Localization Notes

Localization notes are the XUL writers' notes to the localizers/translators. They are placed above the actual entity string in the format: 

<!-- LOCALIZATION NOTE  (entity.name): content -->

where the <var>entity.name</var> is the entity name (id) for the string (entity value) to be localized, and the content provides helpful hints to the localizers. For example: 

<!-- LOCALIZATION NOTE  homeBtn.label : Do not translate the entity value "Home". -->
<!-- ENTITY homeBtn.label "Home" -->

Properties files are very similar, but use the pound sign instead of <!--<var>xxxxx</var>-->: 

# LOCALIZATION NOTE  entity name : content

We recognize that translation is a subset of localization even though we've consistently referred to our notes as "LOCALIZATION NOTE".

Files not to be localized?

Some files live in the tree but aren't really part of the build; they're just there as programming examples or a kind of source documentation. To prevent them from being localized, you may insert a line of comment following the XML declaration as follows. 

<?xml version="1.0" encoding='UTF-8'?>
<!-- DO NOT localize this file: [reason...] it isn't part of the build; -->

When translators see this line, they won't bother to look at the rest of the file.

References

Author: Tao Cheng
newsgroup discussion
mailing list

Original Document Information

  • Author(s): Tao Cheng
  • Last Updated Date: December 10, 2004
  • Copyright Information: Copyright (C) Tao Cheng