Mac Easy 2010 May/Mac Life Ubuntu.iso/casper/filesystem.squashfs/usr/share/gnome/help/gnome-doc-xslt/C/translating.xml

Extensible Markup Language | 2009-03-17 | 31.6 KB | 681 lines

<?xml version="1.0" encoding="utf-8"?><!-- -*- indent-tabs-mode: nil -*- -->
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY intltool "<command>intltool</command>">
<!ENTITY gettext_xsl "<filename>gettext.xsl</filename>">
<!ENTITY l10n_xml "<filename>l10n.xml</filename>">
<!ENTITY l10n_gettext
  "<function role='xsl-template' moreinfo='refentry'>l10n.gettext</function>">
<!ENTITY l10n_plural_form
  "<function role='xsl-template' moreinfo='refentry'>l10n.plural.form</function>">
<!ENTITY xrefstyle
  "<sgmltag class='attribute'>xrefstyle</sgmltag>">
]>

<section id="translating">
  <title>Translating the Stylesheets</title>
  <para>The Gnome documentation stylesheets provide support for localizing
  the rendered output from DocBook documents.  Localizable strings in the
  stylesheets are marked for translation and extracted into PO files and
  &intltool;.  After they have been translated, &intltool; merges them into
  an XML file called &l10n_xml;, which is then used by the stylesheets to
  localize the output.</para>

  <para>Providing full internationalization support for the DocBook stylesheets
  is not trivial, and providing localizations requires translators to understand
  how documents are formatted and, to some extent, how DocBook works.  DocBook
  is a high-level markup language, and it requires processing applications to
  provide much of the formatting for documents.  DocBook applications must
  resolve cross references, create tables of contents, format headers, and
  perform other formatting tasks that need to be localized.  Localizing these
  tasks involves more than translating stand-alone sentences.  In effect, the
  very formatting code itself is localizable.</para>

  <note>
    <title>Help Us Help You</title>
    <para>Document formatting varies greatly across the world.  Each locale has
    a long history of formatting conventions and methods.  The maintainers of
    these stylesheets do not know all the nuances of formatting documents in
    all locales.  The only way we can create better output for your locale is
    if you tell us when you encounter problems.</para>
  </note>

  <para>Although all localization is done by translating strings in a PO file,
  there are many cases where the translatable string is not a simple sentence
  or phrase.  Rather, translators must provide data using XML fragments.  These
  structured fragments can be used to work with plural forms, provide alternative
  formattings based on context, or provide format strings.</para>

  <section id="translating-simple">
    <title>Simple Strings</title>

    <para>Translated strings are extracted in the stylesheets by a template
    called &l10n_gettext;.  This template extracts strings from an XML file,
    which is built from PO files by &intltool;.  For example, consider the
    string <wordasword>Caution</wordasword>, which is used as a heading for
    <sgmltag>caution</sgmltag> elements.  The stylesheets would call
    &l10n_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:</para>

    <programlisting><![CDATA[
<msgset xmlns=""http://www.gnome.org/~shaunm/gnome-doc-utils/l10n">
  <msgid>Caution</msgid>
  <msg>Caution</msg>
  <msg xml:lang="ar">إنتباه</msg>
  <msg xml:lang="bg">–í–Ω–∏–º–∞–Ω–∏–µ</msg>
  <msg xml:lang="ca">Compte</msg>
  <msg xml:lang="cs">Upozornění</msg>
  <msg xml:lang="da">Forsigtig</msg>
  <msg xml:lang="de">Achtung</msg>
  <msg xml:lang="el">Προσοχή</msg>
  <msg xml:lang="en_CA">Caution</msg>
  <msg xml:lang="en_GB">Caution</msg>
  <msg xml:lang="es">Precaución</msg>
  <msg xml:lang="et">Ettevaatust</msg>
  <msg xml:lang="fi">Varoitus</msg>
  <msg xml:lang="fr">Attention</msg>
  <msg xml:lang="gu">સાવધાન</msg>
  <msg xml:lang="hi">चेतावनी</msg>
  <msg xml:lang="hu">Figyelem</msg>
  <msg xml:lang="id">Perhatian</msg>
  <msg xml:lang="it">Attenzione</msg>
  <msg xml:lang="ja">注意</msg>
  <msg xml:lang="ko">주의</msg>
  <msg xml:lang="lt">Įspėjimas</msg>
  <msg xml:lang="nb">Advarsel</msg>
  <msg xml:lang="ne">सावधानी</msg>
  <msg xml:lang="nl">Let op</msg>
  <msg xml:lang="no">Advarsel</msg>
  <msg xml:lang="pa">ਸਾਵਧਾਨ</msg>
  <msg xml:lang="pt">Cuidado</msg>
  <msg xml:lang="pt_BR">Cuidado</msg>
  <msg xml:lang="ro">Aten≈£ie</msg>
  <msg xml:lang="sk">V√Ωstraha</msg>
  <msg xml:lang="sq">Kujdes</msg>
  <msg xml:lang="sr">–ü–∞–∂—ö–∞</msg>
  <msg xml:lang="sr@Latn">Pažnja</msg>
  <msg xml:lang="sv">Varning</msg>
  <msg xml:lang="tr">Uyarı</msg>
  <msg xml:lang="uk">–ó–∞—Å—Ç–µ—Ä–µ–∂–µ–Ω–Ω—è</msg>
  <msg xml:lang="vi">C·∫£nh b√°o</msg>
  <msg xml:lang="wa">Adviertance</msg>
  <msg xml:lang="zh_CN">小心</msg>
  <msg xml:lang="zh_TW">注意</msg>
</msgset>]]></programlisting>

    <para>Translators, 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 <literal>sr</literal> locale for the
    above string would look like this:</para>

    <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:1347
msgid "Caution"
msgstr "–ü–∞–∂—ö–∞"]]></programlisting>
  </section>

  <section id="translating-plurals">
    <title>Plurals</title>

    <para>In many cases, a static string is insufficient for proper localized
    content.  For these cases, the stylesheets allow for alternate strings by
    placing the strings in a structured XML fragment.  Alternate strings are
    used in two ways: to provide plural forms according to the plural rules
    of the language, and to provide alternate formattings based on a specified
    role.  This section discusses plurals.  See <xref linkend="translating-roles"/>
    for a discussion of roles.</para>

    <para>Plural forms are handled similarly to how they are handled in other
    applications.  A rule is provided to transform a number into a plural index,
    and a translation is provided for each of those indexes.  Unfortunately,
    there is no standard way to encode this information into XML; thus, there
    is no mechanism in &intltool;'s XML mode.  Consequently, translators must
    place their translations in an XML fragment.  This fragment is merged into
    the &l10n_xml; file, and the stylesheets extract the appropriate form.</para>

    <para>Here is an example entry in the &l10n_xml; file:</para>

    <programlisting><![CDATA[
<msgset xmlns=""http://www.gnome.org/~shaunm/gnome-doc-utils/l10n">
  <msgid>Author</msgid>
  <msg>
    <msgstr form='0'>Author</msgstr>
    <msgstr form='1'>Authors</msgstr>
  </msg>
  <msg xml:lang="sr">
    <msgstr form='0'>–ê—É—Ç–æ—Ä</msgstr>
    <msgstr form='1'>–ê—É—Ç–æ—Ä–∏</msgstr>
    <msgstr form='2'>–ê—É—Ç–æ—Ä–∏</msgstr>
  </msg>
</msgset>]]></programlisting>

    <para>Since the Serbian language has three plural forms, three translations
    have been provided.  Each of these is placed in a <sgmltag>msgstr</sgmltag>
    element, and the <sgmltag role="attribute">form</sgmltag> attribute is used
    to indicate for which plural form they are used.</para>

    <para>Again, translators will only see the entries in their PO files.  The
    PO file entry for the above translation looks like this:</para>

    <programlisting><![CDATA[
#. Used as a header before a list of authors.
#: ../xslt/gettext/l10n.xml.in.h:1310
msgid ""
"<msgstr form='0'>Author</msgstr> "
"<msgstr form='1'>Authors</msgstr>"
msgstr ""
"<msgstr form='0'>–ê—É—Ç–æ—Ä</msgstr>\n"
"<msgstr form='1'>–ê—É—Ç–æ—Ä–∏</msgstr>\n"
"<msgstr form='2'>–ê—É—Ç–æ—Ä–∏</msgstr>"
]]></programlisting>

    <para>Since <command>intltool</command> 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 <sgmltag>msgstr</sgmltag> elements if they choose.  This extra
    text content is ignored by &l10n_gettext;.</para>

    <para>Note that translators may add a <sgmltag>msgstr</sgmltag> element
    without a <sgmltag class="attribute">form</sgmltag> attribute as a fallback
    translation.  In the example above, the last two <sgmltag>msgstr</sgmltag>
    elements could have been replaced by a single <sgmltag>msgstr</sgmltag>
    element without a <sgmltag class="attribute">form</sgmltag> attribute.
    The &l10n_gettext; template would match the first element whenever the
    plural form is 0, and the fallback element otherwise.</para>

    <para>The plural form is selected using the &l10n_plural_form; template.
    This templates takes the number of items as a parameter, and returns the
    numeric index of the plural form to use.  Currently, the rule cannot be
    automatically extracted from the <literal>Plural-Forms</literal> entry
    in the PO file, though this feature is planned for the future.  Until
    this feature is added, plural rules have to be coded manually in the
    stylesheets.  Translators need to notify the maintainers when they
    begin translating the stylesheets.</para>
  </section>

  <section id="translating-roles">
    <title>Roles</title>

    <para>In many cases, how to render an element depends on various
    conditions, such as the grammatical role.  For these cases, the
    stylesheets allow translators to provide multiple translations,
    each marked with a <sgmltag role="attribute">role</sgmltag>
    attribute from a fixed vocabulary.  The list of valid roles will
    depend on the template, and should be given in the translator
    comment accompanying each string.  However, there are a number
    of common cases, particularly for labels and cross references.
    </para>

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

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

    <programlisting><![CDATA[
<msgstr role='article'>“<node/>”</msgstr>
<msgstr><i><node/></i></msg:msgstr>
]]></programlisting>

    <para>The Serbian translation team has chosen to follow the same
    convention of quoting article titles and italicizing all others.
    The entry in <filename>sr.po</filename> follows.</para>

    <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:304
msgid ""
"<msgid>citetitle.format</msgid> "
"<msgstr role='article'>“<node/>”</msgstr> "
"<msgstr><i><node/></i></msgstr>"
msgstr ""
"<msgstr role='article'>„<node/>“</msgstr>\n"
"<msgstr><i><node/></i></msgstr>"
]]></programlisting>

    <para>The meaning of the markup inside the <sgmltag>msgstr</sgmltag>
    elements will be explained in <xref linkend="translating-formats"/>.
    For now, simply note that multiple strings have been provided, each
    in a <sgmltag>msgstr</sgmltag> element.  The only difference between
    the original string and the Serbian string is that Serbian is using
    a different opening quote character, aligned at the baseline.</para>

    <para>Note also that the original translation contains an additional
    <sgmltag>msgid</sgmltag> element.  This element is redundant in the
    merged XML; its only purpose is to distinguish the string from other
    strings, which may potentially have the same formatting in English.
    Redundant <sgmltag>msgid</sgmltag> elements are sometimes used even
    when neither plural forms nor roles are being used.  In those cases,
    the sole translatable string is placed in a <sgmltag>msgstr</sgmltag>
    element with no attributes.</para>
  </section>

  <section id="translating-formats">
    <title>Format Strings</title>

    <para>Using specialized format strings, the Gnome documentation stylesheets
    can translate more than just simple strings.  These format strings are
    similar in principle to format strings used in C programs, except that
    XML is used to insert named parameters, rather than special format tokens
    being used to insert positional parameters.</para>

    <para>For instance, DocBook provides the <sgmltag>quote</sgmltag> 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 Serbian, they
    are typically rendered with the opening quotation „aligned at the baseline“.
    The entry in the Serbian PO file for this format string follows.</para>

    <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:936
msgid ""
"<msgid>quote.format</msgid> "
"<msgstr role='inner'>‘<node/>’</msgstr> "
"<msgstr>“<node/>”</msgstr>"
msgstr ""
"<msgstr role='inner'>‘<node/>’</msgstr>\n"
"<msgstr>„<node/>”</msgstr>"
]]></programlisting>

    <para>Multiple <sgmltag>msgstr</sgmltag> elements have been provided
    with roles.  These are used to distinguish inner quotes from outer
    quotes.  Roles were described in <xref linkend="translating-roles"/>.
    The <sgmltag>msgstr</sgmltag> elements also contain inline markup.
    This markup is used to insert additional content.  In this case,
    only the <sgmltag class="emptytag">node</sgmltag> element has been
    used.  This element is replaced by the contents of the quotation
    element being processed.</para>

    <para>Each format string has a set number of named arguments available.
    These arguments should be documented in the translator comments that
    accompany the string.  Note that the default translation may not make
    use of all the available arguments.</para>

    <para>In addition to marker elements in format strings, translators
    may also use simple inline formatting markup.  Any content can be
    wrapped in a <sgmltag>span</sgmltag> element with certain attributes
    to control formatting.  The attributes are a subset of CSS properties.
    For HTML output, they are converted directly into the corresponding
    CSS.  The list of allowed attributes is as follows:</para>

    <variablelist>
      <varlistentry>
        <term><sgmltag>font-family</sgmltag></term>
        <listitem><para>This attribute sets the font family.  Specifying
        exact font is generally a not advisable.  Rather, this should be
        used to provide a generic family: serif, sans-serif, cursive,
        fantasy, or monospace.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>font-style</sgmltag></term>
        <listitem><para>This attribute can be used to italicize the text.
        The allowed values are italic, oblique, and normal.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>font-variant</sgmltag></term>
        <listitem><para>This attribute can be used to set the text in small
        caps.  Small caps prints lowercase letters with smaller versions of
        the uppercase glyphs.  The allowed values are small-caps and normal.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>font-weight</sgmltag></term>
        <listitem><para>This attribute can be used to mark the text bold.
        CSS allows any number from 100 to 900, with normal text being 400
        and bold being 700.  In addition to numerical values, you can use
        one of bold, bolder, lighter, or normal to use pre-defined values.
        Only bold and normal should generally be needed.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>font-stretch</sgmltag></term>
        <listitem><para>This attribute can be used to stretch or condense
        the font.  CSS allows a number of keywords to specify by exactly
        how much to stretch the font.  In practice, only wider, narrower,
        and normal should generally be used.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>font-size</sgmltag></term>
        <listitem><para>This attribute sets the size of the font.  CSS
        allows both absolute font sizes using keywords or numeric lenghts,
        as well as relative font sizes using keywords or percentages.
        Generally, only larger, smaller, and normal should be used for
        this attribute.  Better, use the <sgmltag>big</sgmltag> and
        <sgmltag>small</sgmltag> convenience elements described below.
        They are defined to respect the size scales used throughout the
        stylesheets.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>text-decoration</sgmltag></term>
        <listitem><para>This attribute can set various effects on the text.
        The allowed values are none, underline, overline, line-through,
        and blink.  Don't use blink.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>Additionally, extra inline elements are provided for convenience.
    The formatting done by these elements could also be done using the
    <sgmltag>span</sgmltag> element.  Using these elements is just easier
    for common formatting tasks.</para>

    <variablelist>
      <varlistentry>
        <term><sgmltag>big</sgmltag></term>
        <listitem><para>Make the text larger.  This is preferred over using
        the <sgmltag>font-size</sgmltag> attribute, because it is defined to
        use the size scale used throughout the stylesheets.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>small</sgmltag></term>
        <listitem><para>Make the text smaller.  This is preferred over using
        the <sgmltag>font-size</sgmltag> attribute, because it is defined to
        use the size scale used throughout the stylesheets.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>sub</sgmltag></term>
        <listitem><para>Render the text as a subscript.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>sup</sgmltag></term>
        <listitem><para>Render the text as a superscript.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>b</sgmltag></term>
        <listitem><para>Make the text bold.  This is equivalent to setting
        the <sgmltag>font-weight</sgmltag> attribute to bold.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>i</sgmltag></term>
        <listitem><para>Make the text italic.  This is equivalent to setting
        the <sgmltag>font-style</sgmltag> attribute to italic.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>tt</sgmltag></term>
        <listitem><para>Make the text monospace.  This is equivalent to setting
        the <sgmltag>font-family</sgmltag> attribute to monospace.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><sgmltag>u</sgmltag></term>
        <listitem><para>Underline the text.  This is equivalent to setting the
        <sgmltag>text-decoration</sgmltag> attribute to underline.</para></listitem>
      </varlistentry>
    </variablelist>

  </section>

  <section id="translating-types">
    <title>Common Formatter Types</title>

    <para>There are a number of common types of format strings that are
    marked for translation in the stylesheets.  DocBook contains a lot
    of structural markup, and many of the same sorts of formatting tasks
    have to be performed on different elements.  For example, chapters,
    appendixes, and sections all have similar formatting needs, but they
    usually need to be handled distinctly.  The stylesheets do not expose
    every distinct element of DocBook; rather, they only make distinctions
    when they matter from a document presentation viewpoint.</para>

    <para>This section outlines many of the common types of strings
    translators will encounter.  Strings of the same type will generally
    have the same format arguments and the same set of roles.</para>

    <section id="translating-types-labels">
      <title>Label Formatters</title>
      <para>Labels are used before titles in headers and contents listings.
      Usually, a label will contain the object's number followed by some
      punctuation.  Formal block objects, such as tables and figures,
      often have more information in the label.</para>

      <para>The Serbian label formatters for sections and figures follow.</para>

      <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:1128
msgid ""
"<msgid>section.label</msgid> "
"<msgstr role='header'><number/>. </msgstr> "
"<msgstr role='li'><number/>. </msgstr> "
"<msgstr>Section <number/></msgstr>"
msgstr ""
"<msgstr role='header'><number/>. </msgstr>\n"
"<msgstr role='li'><number/>. </msgstr>\n"
"<msgstr>–û–¥–µ—ô–∞–∫ <number/></msgstr>"

#: ../xslt/gettext/l10n.xml.in.h:492
msgid ""
"<msgid>figure.label</msgid> "
"<msgstr role='header'><i>Figure <number/></i> </msgstr> "
"<msgstr role='li'>Figure <number/> </msgstr> "
"<msgstr>Figure <number/></msgstr>"
msgstr ""
"<msgstr role='header'><i>–°–ª–∏–∫–∞ <number/></i> </msgstr>\n"
"<msgstr role='li'>–°–ª–∏–∫–∞ <number/> </msgstr>\n"
"<msgstr>–°–ª–∏–∫–∞ <number/></msgstr>"
]]></programlisting>

      <para>In both cases, translations are provided for the
      <literal>header</literal> and <literal>li</literal> roles.
      Additionally, a fallback formatting has been provided to format
      labels when no role is provided.  Label formatters will generally
      use the same two roles.  Fallback translations should be provided
      as well.</para>

      <para>Most label formatters provide three format arguments which
      can be used in the translations:</para>

      <variablelist>
        <varlistentry>
          <term><sgmltag class="emptytag">title</sgmltag></term>
          <listitem><para>Insert the title of the element being labeled.
          For most types of element, the title is simply provided by the
          <sgmltag>title</sgmltag> in DocBook.  A few DocBook elements,
          notably <sgmltag>refentry</sgmltag>, have more complicated
          content models.  Translators need only reference the argument,
          and the stylesheets will determine the title.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="emptytag">titleabbrev</sgmltag></term>
          <listitem><para>Insert the abbreviated title of the element
          being labeled.  Abbreviated titles are provided by the
          <sgmltag>titleabbrev</sgmltag> element in DocBook.  If the
          labeled element does not have an abbreviated title, the
          title is used instead.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="emptytag">number</sgmltag></term>
          <listitem><para>Insert the fully qualified number of the element
          being labeled.  For most label formatters, there is a corresponding
          number formatter that will be called for this argument.</para></listitem>
        </varlistentry>
      </variablelist>

      <para>Since labels are used before titles, most label formatters should
      only need to use the number of the element.</para>
    </section>

    <section id="translating-types-numbers">
      <title>Number Formatters</title>
      <para>Numbers are used in labels, cross references, and other identifiers.
      Numbers identify elements by their position in the document.  Numbers can
      be as simple as single-level positions, or they may indicate a hierarchy.
      For example, the third subsection of the fourth section in the second
      chapter would be Section 2.4.3.  The job of number formatters is to put
      together the hierarchical number string.  Thus, number formatters are not
      called for single-level numbers.</para>

      <para>The single-level number of an element in its parent is referred to
      as that element's <firstterm>digit</firstterm>.  Number formatters work
      by specifying how to combine the parent element's number with the current
      element's digit.  Two format arguments are allowed:</para>

      <variablelist>
        <varlistentry>
          <term><sgmltag class="emptytag">parent</sgmltag></term>
          <listitem><para>Insert the fully qualified number of the element's
          parent.  In many cases, this number is constructed by calling the
          number formatter for the parent element.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="emptytag">digit</sgmltag></term>
          <listitem><para>Insert the single-level position of the element
          in its parent element.  How the digit is displayed is determined
          by the corresponding digit format.</para></listitem>
        </varlistentry>
      </variablelist>

      <para>The Serbian label formatters for sections and figures follow.</para>

      <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:1162
msgid ""
"<msgid>section.number</msgid> "
"<msgstr><parent/>.<digit/></msgstr>"
msgstr""
"<msgstr><parent/>.<digit/></msgstr>"

#: ../xslt/gettext/l10n.xml.in.h:525
msgid ""
"<msgid>figure.number</msgid> "
"<msgstr><parent/>-<digit/></msgstr>"
msgstr ""
"<msgstr><parent/>-<digit/></msgstr>"
]]></programlisting>

      <para>Note that <sgmltag>msgstr</sgmltag> elements are used to contain
      the strings, even though neither plural forms nor roles are being used.
      This is because a <sgmltag>msgid</sgmltag> has been inserted into the
      translatable string to allow number formatters for different elements
      to be distinct messages in PO files.</para>
    </section>

    <section id="translating-types-digits">
      <title>Digit Formats</title>
      <para>Digits are the part of an element's number that specify its
      position in its parent element.  An element's number consists of
      its parent number and its digit.  Digits can be formatted using
      a number of numbering systems.</para>

      <para>Digit formats aren't actually format strings, nor are they
      user-visible strings.  They're simply tokens that specify how to
      format a number.  Currently, only the following five digit formats
      are supported:</para>

      <variablelist>
        <varlistentry>
          <term><literal>1</literal></term>
          <listitem><para>Format the number using Arabic numerals:
          1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>A</literal></term>
          <listitem><para>Format the number using uppercase Latin letters:
          A, B, C, D, E, F, G, H, I, J, K, L.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>a</literal></term>
          <listitem><para>Format the number using lowercase Latin letters:
          a, b, c, d, e, f, g, h, i, j, k, l.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>I</literal></term>
          <listitem><para>Format the number using uppercase Roman numerals:
          I, II, III, IV, V, VI, VII, VIII, IX, X, XI, XII:</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>i</literal></term>
          <listitem><para>Format the number using lowercase Roman numerals:
          i, ii, iii, iv, v, vi, vii, viii, ix, x, xi, xii:</para></listitem>
        </varlistentry>
      </variablelist>

      <note><para>These five numbering systems 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 digit formats.</para></note>
    </section>

    <section id="translating-types-xrefs">
      <title>Cross Reference Formatters</title>
      <para>Cross reference formatters are used to format the text of a link
      to another element in the document.  In many languages, how best to
      format an individual cross reference will depend on its usage.  Often,
      cross references will need to be formatted differently based on their
      grammatical role in a sentence.</para>

      <para>The cross reference formatters allow translators to provide multiple
      formattings using roles.  Documentation authors and translators can then
      select the format for a cross reference using the &xrefstyle; attribute on
      the <sgmltag>xref</sgmltag> element.  The Gnome documentation stylesheets
      allow &xrefstyle; attributes of the form
      <sgmltag class="attvalue">role:<replaceable>somerole</replaceable></sgmltag>,
      where <replaceable>somerole</replaceable> is the role to be passed to the
      cross reference formatter.</para>

      <para>Cross reference formatters generally provide the following three
      format arguments:</para>

      <variablelist>
        <varlistentry>
          <term><sgmltag class="emptytag">title</sgmltag></term>
          <listitem><para>Insert the title of the element being referenced.
          For most types of element, the title is simply provided by the
          <sgmltag>title</sgmltag> in DocBook.  A few DocBook elements,
          notably <sgmltag>refentry</sgmltag>, have more complicated
          content models.  Translators need only reference the argument,
          and the stylesheets will determine the title.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="emptytag">titleabbrev</sgmltag></term>
          <listitem><para>Insert the abbreviated title of the element
          being referenced.  Abbreviated titles are provided by the
          <sgmltag>titleabbrev</sgmltag> element in DocBook.  If the
          labeled element does not have an abbreviated title, the
          title is used instead.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><sgmltag class="emptytag">number</sgmltag></term>
          <listitem><para>Insert the fully qualified number of the element
          being referenced.  For most label formatters, there is a corresponding
          number formatter that will be called for this argument.</para></listitem>
        </varlistentry>
      </variablelist>

      <remark>Insert an example here</remark>
    </section>

    <section id="translating-types-tooltips">
      <title>Tooltip Formatters</title>
      <para>Each hyperlink in the HTML output is given a tooltip by the
      stylesheets.  Since hyperlinks can be created using a number of
      different semantic linking mechanisms in DocBook, the stylesheets
      are able to provide rich information in the hyperlink tooltips.
      The stylesheets provide tooltip formatters for various linking
      mechanisms.  These can then be translated to provide rich
      information about hyperlinks in any language.</para>

      <para>For example, the <sgmltag>email</sgmltag> element in DocBook is
      converted into a hyperlink allowing users to send email to the given
      address.  The Serbian translation for this formatter follows.</para>

      <programlisting><![CDATA[
#: ../xslt/gettext/l10n.xml.in.h:329
msgid ""
"<msgid>email.tooltip</msgid> "
"<msgstr>Send email to ‘<node/>’.</msgstr>"
msgstr ""
"Пошаљите е-писмо на „<node/>“."
]]></programlisting>

      <para>Each tooltip formatter will have its own format arguments.
      Generally, only a single format argument will be needed, and the
      translator comments for the string should clearly specify the
      valid arguments.</para>
    </section>
  </section>
</section>