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.
- 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 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
# 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.
- XUL is discussed in depth in XUL Language Spec and XUL Window Language.
- XUL Localizability issues
- XHTML 1.1 Recommendation
- Namespaces in XML
- Extensible Markup Language (XML) 1.0
- Euro Sign The Unicode Standard®, Version 2.1
- "XML Applications" by Frank Boumphrey. Published by Wrox Press Inc. ISBN 1-861001-52-5.