# Translating the Stylesheets

The Gnome documentation stylesheets use two different mechanisms for internationalization. The simpler method is provided by &gettext_xsl;. This method reads in translated strings from a simple &l10n_xml; file, which is easily managed using PO files and `intltool`. The other method is provided by &format2xsl_xsl;. This method converts special format files to XSLT stylesheets at build time. It is considerably more flexible than the &gettext_xsl; method, as it allows translators programmer-level control over the formatted output.

Generally, &gettext; is used only for simple string lookups that require no special formatting. However, since it tends to have better performance than &format2xsl;, it is preferred whenever possible. If you are providing translations and find that a string marked for translation is insufficient for your locale, you should request to have that translation reworked using format strings. Document processing is a much more difficult task for internationalization than most simple application translations in Gnome. The maintainers don't know all the nuances of document processing in every language, so the only way we can improve the internationalization support is with the help of the translators.

## The &gettext; Method

The Gnome documentation stylesheets provide an XSLT template called &gettext; which extracts localized values of strings from a localization file. This file is easily translated with PO files using the XML mode of `intltool`.

For instance, consider the string Caution, which is used as a heading for `caution` elements. The stylesheets would call &gettext; to extract the translated value of this string for the document's language. The &l10n_xml; file would have an entry similar to this:

    <msg xmlns=""http://www.gnome.org/~shaunm/gnome-doc-utils/xsl-format">
      <msgid>Caution</msgid>
      <msgstr>Caution</msgstr>
      <msgstr xml:lang="ca">Compte</msgstr>
      <msgstr xml:lang="cs">Upozornění</msgstr>
      <msgstr xml:lang="de">Warnung</msgstr>
      <msgstr xml:lang="es">Precaución</msgstr>
      <msgstr xml:lang="hu">Figyelem</msgstr>
      <msgstr xml:lang="nl">Let op</msgstr>
      <msgstr xml:lang="pt">Cuidado</msgstr>
      <msgstr xml:lang="sq">Kujdes</msgstr>
      <msgstr xml:lang="sv">Varning</msgstr>
      <msgstr xml:lang="uk">Застереження</msgstr>
      <msgstr xml:lang="wa">Adviertance</msgstr>
    </msg>

A translator, however, will work only with the PO files. Using PO files for these strings is no different than any other simple string translation. The PO entry in the `cs` locale for the above string would look like this:

    #: xslt/gettext/l10n.xml.in.h:63
    msgid "Warning"
    msgstr "Varování"

The &gettext; template also allows pluralized translations. However, the standard multiple message strings used in PO files are not used for the pluralized translations, because `intltool` can't merge these into an XML file. Instead, the translated message string is an XML fragment. This is copied into the localization XML file, and &gettext; extracts the value for the appropriate plural form.

After merging values from the PO files, the localization file will have entries similar to this:

    <msg xmlns="http://www.gnome.org/~shaunm/gnome-doc-utils/xsl-format">
      <msgid>Author</msgid>
      <msgstr>
        <msgstr form="0">Author</msgstr>
        <msgstr form="1">Authors</msgstr>
      </msgstr>
      <msgstr xml:lang="cs">
        <msgstr form="0">Autor</msgstr>
        <msgstr form="1">Autoři</msgstr>
        <msgstr form="2">Autoři</msgstr>
      </msgstr>
    </msg>

As with the simple case, each locale has a `msgstr` element with an `xml:lang` attribute. For pluralized translations, however, the translation is a sequence of nested `msgstr` elements, each with a `form` attribute. The &gettext; template extracts the correct string based on the plural form, which is computed from the number of referenced objects.

Translators simply write the correct XML fragment in the translated message string. For example, here is the PO file entry in the `cs` locale for the above:

    #. Used as a header before a list of authors.
    #: xslt/gettext/l10n.xml.in.h:2
    msgid ""
    "<msgstr form=\"0\">Author</msgstr>"
    "<msgstr form=\"1\">Authors</msgstr>"
    msgstr ""
    "<msgstr form=\"0\">Autor</msgstr>"
    "<msgstr form=\"1\">Autoři</msgstr>"
    "<msgstr form=\"2\">Autoři</msgstr>"

Since `intltool` often alters whitespace, the entry in the PO file might not look as nice as this. When creating the translated message strings, translators may add or remove whitespace between `msgstr` elements if they choose. This extra text content is ignored by &gettext;.

Note that translators may add a `msgstr` element without a `form` attribute as a fallback translation. In the example above, the last two `msgstr` elements could have been replaced by a single `msgstr` element without a `form` attribute. The &gettext; template would match the first element whenever the plural form is 0, and the fallback element otherwise.

The plural form is determined by calling the &gettext_plural_form; template. This template has the plural forms for locales hard-coded; they are not extracted automatically from PO files. When translators begin translating the stylesheets, they should contact the maintainers to have an appropriate plural form added to the stylesheets.

## The &format2xsl; Method

The Gnome documentation stylesheets can translate more than simple strings using the &format2xsl; template. The &format2xsl; template creates a localized XSLT stylesheet from an XML template file. The template file contains format strings which can be translated with PO files.

For instance, DocBook provides the `quote` element, used to mark inline quotations. How to render an inline quotation depends on the typographic conventions of the language. In U.S. English, they are rendered inside “double inverted-comma” quotation marks. In German, they are typically rendered inside «double angle» quotation marks.

In the template file `db-format.xml.in`, the string `format.quote.outer` is marked for translation. This is a placeholder for the format strings provided by translators. The default value is `“%t{node}”`. This contains the format argument `%t{node}` which applies XSLT templates to the parameter named `node`. This means that the contents of the `quote` element will be rendered as they would normally be rendered, but they will be wrapped inside quotation marks.

Each template format string has a set number of named arguments availabe, which should be documented along with the template. Note that the default translation may not make use of all the availabe arguments. Each argument is either a template argument, string argument, or number argument.

Template arguments have the form `%t{node}`, and work by applying further XSLT templates to the node. String arguments have the form `%s{str}`, and work by copying a string into the formatted output. For template and string arguments, translators must use the correct prefix, either `%t` or `%s`. The stylesheets will fail to build if the prefix is not correct.

Number arguments work similarly to string arguments, except that translators have control over how the numbers are formatted. Consider the template string `format.example.number`. The default value for this is `%t{parent}-%1{number}`. The template argument calls the number formatter for the enclosing chapter, and the number argument renders the number of the example in the chapter. If this were being called on the fifth example in the second chapter, the value would be 2-5.

Unlike template and string arguments, translators may use a number of different prefixes on number arguments. The prefix indicates how to format the number. Currently, the prefixes `%1`, `%A`, `%a`, `%I`, and `%i` are supported. The `%1` prefix formats the number in decimal form using Arabic numerals. The `%A` and `%a` prefixes format numbers as successive values of the Latin alphabet, either uppercase or lowercase. The `%I` and `%i` prefixes format numbers as Roman numerals, again either uppercase or lowercase.

These five types of number formatters are unlikely to be sufficient, particularly for non-Western languages. Translators who would like to format numbers differently should contact the maintainers, and we can try to add additional number formatters.

### Using Roles

In many cases, how to render an element depends on various conditions, such as the grammatical role. For these cases, the &format2xsl; template can select localized format strings from a list of alternatives, each marked with a `role` attribute. The list of valid roles will depend on the template; however, there are a number of common cases, particularly for automatically generated labels.

The available roles for a template, as well as how the role is extracted, varies from template to template. The documentation for each template should clearly state how the role is determined and which roles are available.

Translating using roles is similar to translating using plural forms. A translation consists of any number of `msgstr` elements, each with a `role` attribute. A `msgstr` element without an attribute can be provided as a default if none of the roles match.

For example, the `citetitle` element in DocBook is used to cite the title of a publication. The type of the publication is specified in the `class` attribute. In many English publications, article titles are place in quotes, while book titles are italicized. The following fragment will quote article titles, but italicize all other cited titles.

    <msg:msgstr role="article">“%t{node}”</msg:msgstr>
    <msg:msgstr><i>%t{node}</i></msg:msgstr>

The Czech translation team has chosen to follow the same convention of quoting article titles and italicizing all others. The entry in `cs.po` follows.

    #: xslt/docbook/common/db-format.xml.in.h:5
    msgid "format.citetitle"
    msgstr ""
    "<msg:msgstr role=\"article\">„%t{node}”</msg:msgstr>"
    "<msg:msgstr><i>%t{node}</i></msg:msgstr>"

Unlike using plural forms with &gettext;, each `msgstr` element must use the namespace prefix `msg:`. Future versions of the stylesheets should remove this requirement.

In this example, text is italicized using inline markup. Although the HTML `i` tag is being used, the templates are not used exclusively for HTML transformations. A limited set of inline markup is permitted, and each stylesheet using the translated templates provides a template to transform the inline markup into its target format. Translators should restrict the use of inline markup to `i` (italics), `b` (bold), and `tt` (monospace).

### Translating Labels

The most common use of roles is to translate the formatting of labels for section and other block elements in DocBook. For example, the second section of an article might be referred to as Section 2. The label for the section is used in many different places throughout the document, and its formatting varies. The following roles are common in many label formatters.

`header`

- The label that appears before the title in the heading of the actual element in the content. The label of this section using this role is translating-labels.

`li`

- The label that appears before the entry in the table of contents. The label of this section using this role is translating-labels.

`xref`

- The label used for cross references placed inline in text. The label of this section using this role is translating-labels.

Additionally, there are four roles that are often used by the stylesheets, but do not need to be defined by translators. These roles are `title`, `titleabbrev`, `subtitle`, and `number`. Unless defined otherwise, these roles will automatically just call the respective argument.

Translators can add support for additional roles for documents written in their language. This is useful for properly rendering cross references used in different parts of speech. For instance, Section 14.2 contains more information and See Section 14.2 for more information use the cross reference label differently. The first uses it as a subject, the second as a direct object. In many languages they will need to be rendered differently.

When the stylesheets resolve a cross reference, they look first at the `xrefstyle` attribute of the `xref` element. If the attribute value is of the form `role:`somerole``, then the value ``somerole`` will be used as the role. Otherwise, the fallback role `xref` will be used.

Translators may add additional roles, such as `xref-subject` and `xref-object`. Once added to the stylesheets, any document in that language can make use of those roles to influence the rendering of cross references. To avoid naming collisions, translators are recommended to prefix roles with `xref-` when creating new roles for use with cross references.