11.4. Programming and Localization

11.4.1. Naming Conventions

The decision of what to call your code internals emerged more than once in this book. In Chapter 8, you decided the name of the component IDL interface IDL file and its associated implementation. In locale, it is the entity names and string identifiers contained in bundles.

Naming conventions in localization are useful because they provide some context to the translator. In this spirit, it is good for the reference to be as descriptive as possible. You can choose your route for naming or stick with the way that Mozilla does it. Examining the files in the Mozilla source base, common naming conventions for entities include the following:

Certain XUL widgets can contain multiple localizable resources, including a text label or description, a tooltip, and an accesskey. A button is a prime example:

<button id="flyBtn" label="&flyBtn.label;" accesskey="&flyBtn.accesskey;" 
    tooltip="&flyBtn.tooltip;" />

The naming convention is consistent, using the value of the id attribute appended by the name of the UI feature. The attribute and name are delimited by a period. Not only does using this value flag the resource as being associated with a certain widget, but it also permits logical grouping in the DTD:

<!ENTITY flyBtn.label "Fly Away"> 
<!ENTITY flyBtn.accesskey "f">
<!ENTITY flyBtn.tooltip "Click here to take to the air">

Naming string identifiers in bundle files fits less into a pattern like that in DTDs, and in the Mozilla, source files may appear random. If a pattern must be found, you could look at two things: filenames and identifier descriptions.

In a filename, the association of a single .properties file is with a logical part of the application. If a string appears in a certain dialog or window, you know where to go to translate the strings or add more strings. Example files in the Mozilla tree worth examining include editor.properties, commonDialogs.properties, and wizardManager.properties.

With identifier descriptions, the text used on the identifier describes what the text actually refers to. The goal is to be as descriptive as possible by using as brief text as possible:

dontDeleteFiles=Don't Delete Files

The descriptor is the same as the value, although in a different format. The opportunity was taken here to be as descriptive as possible.

11.4.2. Breaking Up the Text

Under certain circumstances, you may need to pop up your own alert messages as XUL dialogs. Some messages may involve multiple lines of text that need to be put on new lines. There is no natural delimiter that breaks up the text contained within <description> or <label> elements in XUL, so following are a couple of tricks to get around this problem.

<vbox id="main-message" flex="1" style="max-width: 40em;"/>
  <!-- insert elements here -->
</vbox>

var text = window.arguments[0];
var holder = document.getElementById("main-message");
var lines = text.split("\n");
for (var i = 0; i < lines.length; i++) {
  var descriptionNode = document.createElement("description");
  var linetext = document.createTextNode(lines[i]);
  descriptionNode.appendChild(linetext);
  holder.appendChild(descriptionNode);
}

var text = window.arguments[0];
var holder = document.getElementById("main-message");
var lines = text.split("\n");
var descriptionNode = document.createElement("description");
for (var i = 0; i < lines.length; i++) {
  var linetext = document.createTextNode(lines[i]);
  var breakNode = document.createElement("html:br");
  descriptionNode.appendChild(linetext);
  descriptionNode.appendChild(breakNode);
}
holder.appendChild(descriptionNode);

11.4.3. Anonymous Content and Locale

Entities are everywhere. Well, not quite everywhere. However, as entity references and DTD constructs are part of the XML language, they can be used for localization purposes in other files in your package, such as RDF and XBL files.

In the case of XBL, it is common for binding content to inherit its locale information from the base widget. Take the Example 11-7 as a case in point. Here is the bound element in the XUL document; the binding for the bound element is shown:

<article id="artheader" class="articleheader" title="Common Garden Flies" author="Brad Buzzworth"/>

The attributes of note here are title and author, both user-defined, because they contain the localizable values that will be used in the binding.

<binding id="articleheader">
  <content>
    <xul:hbox flex="1">
      <xul:label class="flybox-homeheader-text" xbl:inherits="value=title"/>
      <xul:spacer flex="1"/>
      <xul:label class="flybox-homeheader-text" xbl:inherits="value=author"/>
    </xul:hbox>
  </content>
  <implementation>
    <property name="title">
      <setter> 
        <![CDATA[
          this.setAttribute('title',val); return val;
        ]]>
      </setter>
      <getter>
        <![CDATA[
          return this.getAttribute('title');
        ]]>
      </getter>
    </property>
    <property name="author">
      <setter> 
        <![CDATA[
          this.setAttribute('author',val); return val;
        ]]>
      </setter>
      <getter>
        <![CDATA[
          return this.getAttribute('author');
        ]]>
      </getter>
    </property>
  </implementation>
</binding>

The binding in Example 11-7 illustrates a binding whose content inherits its locale from the bound element. The attributes used on the bound element, namely title and author, are descriptive, enabling the author to be specific about what they are setting a value to. The rest is taken care of in the binding, where the inherits attribute sets the value on the anonymous content to the value of the more descriptive attributes on the bound element. You can retrieve the values or set them by using the getter and setter.

<!ENTITY PrintPreviewCmd.label    "Print Preview">

<!ENTITY PrintPreviewCmd.label    "Presentación preliminar...">

> nsconv -f ascii -t utf-8 foo.dtd bar.dtd

<!ENTITY PrintPreviewCmd.label   "Presentaci&#243;n preliminar...">

11.4.4. Localizable Resources in HTML

As a web application, Mozilla permits seamless integration of web content, both local and remote, in many formats. If you have verbose text that just needs to be displayed somewhere in the framework of your application, HTML or XML content may be ideal for this purpose. Through the use of XUL content widgets, such as <iframe> and <browser>, you have ready-made frames to slot your content into:

<iframe src="xFly.html" flex="1"/>

Therefore, a simple modification of xFly.html with a local language leaves the main application untouched. Some other uses of HTML or XML content include an "About" dialog/page, Help pages, a wizard interface, or a getting started/introduction page.

11.4.5. Localizable Resources in RDF

Strings to be converted in RDF content can take more than one form. You can use entities directly in your RDF file or have the text inline in your node descriptions. Whichever method you choose, you must ensure that the file is installed in the right place in the tree and registered correctly for the application to pick up on it.

As an XML markup, RDF can handle inline entity definitions. These entity definitions have been covered thoroughly in the chapter so far. Example 11-8 looks at localizable strings contained directly in RDF node descriptions. This example is taken from the Help table of contents in the Mozilla tree.

<rdf:Description about="#nav-doc">
  <nc:subheadings>
    <rdf:Seq>
      <rdf:li> 
        <rdf:Description ID="nav-doc-language" 
               nc:name="Language and Translation Services"
               nc:link="chrome://help/locale/nav_help.html#nav_language"/>
      </rdf:li>
    </rdf:Seq>
  </nc:subheadings>
</rdf:Description>

The text in the nc:name attribute is the text that will be changed. Note that this issue of text in RDF is separate from the topic of using RDF as the mechanism in the chrome registry to register your locale and set up a switching mechanism. This difference is addressed in the next section.