Chapter 4. Localization

One unfortunate consequence of this history is that there’s some cruft in the localization files. There are mappings and possibly templates that aren’t actually used. Or, at least, they’re not used in the standard DocBook stylesheet. They might be used in customization layers.

I made a few attempts to trim out cruft, but found all of the results unsatisfying. So, at least for the moment, I’ve left it in place. Like everything on earth, it’s mostly harmless.

The mappings section is a simple list of key/value pairs. Each gentext element defines a key and its replacement.

1 |  <mappings>
  |    <gentext key="above">above</gentext>
  |    <gentext key="abstract">Abstract</gentext>
  |    …
5 |    <gentext key="xrefto">xref to</gentext>
  |   </mappings>

These mappings serve two purposes. For many languages, a lot of the work of defining a new localization is just updating these mappings. For a stylesheet customization layer, it provides a mechanism for remapping on an ad hoc basis.

In a localization template, any key entered in curly braces will be replaced by the mapping. In other words, for the example above, {abstract} will be replaced by the word “Abstract”. This mapping is done when the document is transformed, not when the localization file is compiled.

Groups are the primary templating system. In a context where generated text is required, a group is selected and within that group, a template is selected. The template is selected by evaluating the expression in the match attribute with the current node as the context item. A template with the match express true() will always succeed; it is used as a fallback.

The title-numbered group determines how titles are formatted if they are numbered, (there’s also title-unnumbered when titles aren’t being numbered):

1 |<group name="title-numbered">
  |   <template match="self::db:section[ancestor::db:preface]">%c</template>
  |   …
  |   <template match="self::db:appendix">{Appendix} %l%.%c</template>
5 |   …
  |   <template match="self::db:warning">%c</template>
  |   <template match="true()">%l%.%c</template>
  |</group>

(Note that not all titles are numbered, this is just the group that’s used if they could be. See $division-numbers, $component-numbers, and $section-numbers.)

Within a template, two kinds of substitution are performed: names in curly braces are replaced by the corresponding mapping and %-letter values are substituted as follows:

If the title group is being used to generate text for the chapter from our example document:

• The chapter context is used to select the template ({chapter} %l%.%c).

• The string {chapter} is replaced by the mapping for chapter, which is “Chapter” in English.

• The label %l is “1” because this is the first chapter. (In fact, constructing the label uses templates from the localization file as well.)

• The separator %. is “. ”. (Like the label, this is also constructed from a separate query to the localization file.)

• And the content %c is “Chapter the first”. (There’s no markup in this title, but if there was, it would be retained. The content is a list of items, not a string.)

• Literal text, such as the non-breakable space between “{chapter}” and “%l”, is retained verbatim.

List elements are used to format items that can be repeated (terms in a variable list, lists of authors, lists of “see also” terms, etc.). The list consists of a series of items. Within each item, one or more content replacements is specified with %c. The items must be arranged so that there’s a match for one, two, three, etc. items.

If an item contains a repeat, that repeat will be used for as many items as necessary to complete the list formatting. The default list format is:

1 |   <list name="_default">
  |      <items>%c</items>
  |      <items>%c {and} %c</items>
  |      <items>%c<repeat>, %c</repeat>, {and} %c</items>
5 |   </list>

Consider how a list of four authors in an authorgroup would be formatted. Call them A, B, C, D, for simplicity (and assume there’s no list for “authorgroup”, so the “_default” will be used).

The first two items match one and two items, respectively. They aren’t appropriate for a list of four items. The third item contains three items and a repeat, so that can be used for a list of four (or more) items.

The first %c is “A”. The second %c is in a repeat, followed by another %c. There are three elements left in the list at this point, so two will be used in the repeat and the last one will follow it.

The result will be A, B, C, and D where the word “and” was found by looking for the and key in the mappings.

The letters group is used to identify the lexical order and grouping of letters.

 1 |   <letters>
   |      <l i="-1"/>
   |      <l i="0">Symbols</l>
   |      <l i="10">A</l>
 5 |      <l i="10">a</l>
   |      …
   |      <l i="20">B</l>
   |      <l i="20">b</l>
   |      …
10 |   </letters>

All of the symbols with the same “i” value will be grouped together.

This mechanism dates from the days before XSLT supported language-specific collations. It is used in generated indexes, but perhaps it should simply be phased out.

If you want to replace an entire localization file (if, for example, you want to apply the same changes to a set of stylesheets), you can approach that as follows:

1. Copy the localization source files.

2. Update the ones you wish to change.

3. Compile them all with src/main/xslt/modules/xform-locale.xsl saving the output in a new location.

4. In your stylesheet, change the $v:localization-base-uri to point to the directory where the new locales reside. Those locale files will be used.

If you only want to override a small number of localization features, it may be simpler to do so directly in your stylesheet. The variable $v:custom-localizations will be merged with the default localizations before transformation begins. But you can only override existing groups with the procedure described here. You cannot use $v:custom-localizations to define new groups.

Suppose, for example, that you wanted:

• The table of contents title to simply be “Contents”,

• To omit the word “Appendix” from the appendix title, and

• To change the form of the cross reference to appendixes to read “App. A” instead of “Appendix A”.

The following customization would accomplish that:

 1 |<xsl:variable name="v:custom-localizations">
   |  <locale xmlns="http://docbook.org/ns/docbook/l10n/source"
   |          language="en"
   |          english-language-name="English">
 5 |    <mappings>
   |      <gentext key="TableofContents">Contents</gentext>
   |    </mappings>
   |    <group name="title-numbered">
   |      <template name="appendix">%l%.%c</template>
10 |    </group>
   |    <group name="xref-number">
   |      <template name="appendix">App. %l</template>
   |    </group>
   |  </locale>
15 |</xsl:variable>

Note that it defines (a portion of) a locale source file for the language en. These changes only apply to that locale.

This fragment replaces the mapping for TableofContents and the templates for numbered titles and numbered cross references.

To update multiple languages, put additional locale elements in the variable as siblings.

Formatting our example document above now produces:

Figure 4.6. Sample book (Alternate)

Sometimes, rather than change a template, you want to change which group of templates is used. This is controlled by two variables: $v:user-title-groups and $v:user-xref-groups.

  |<title xpath="self::db:section[ancestor::db:preface]"
  |       group="title-unnumbered"/>

  |<title xpath="self::db:section"
  |       group="title-numbered"/>

  |<xsl:variable name="v:user-xref-groups" as="element()*">
  |  <crossref xpath="self::db:chapter|self::db:appendix"
  |            context="xref-number"/>
  |</xsl:variable>