diff options
| author | Shaun McCance <shaunm@src.gnome.org> | 2005-07-17 07:48:16 +0000 |
|---|---|---|
| committer | Shaun McCance <shaunm@src.gnome.org> | 2005-07-17 07:48:16 +0000 |
| commit | a46adae2ccad437aebf85a4b0f1cdc498b69d18d (patch) | |
| tree | 864a437806a9be9ab7b1c0bd82a25841685ade3e /i18n/STYLESHEETS.xhtml | |
| parent | fc16361be7681111719cc3a26af9b37a992784e0 (diff) | |
| download | yelp-xsl-a46adae2ccad437aebf85a4b0f1cdc498b69d18d.tar.gz | |
- Moved stylesheets translator docs to i18n/STYLESHEETS.xhtml - Generated
* Makefile.am:
* i18n/Makefile:
* i18n/PLURALS.txt:
* i18n/STYLESHEETS.xhtml:
* i18n/plurals.sh:
* xslt/gettext/l10n.xml.in:
- Moved stylesheets translator docs to i18n/STYLESHEETS.xhtml
- Generated PLURALS.txt of supported plural forms
* i18n/notes/vi.txt
- Added Vietnamese formatting notes from Clytie Siddall
* po/POTFILES.in:
- Removed db2format.xml.in
* xslt/gettext/gettext.xsl:
- Added more plural forms
Diffstat (limited to 'i18n/STYLESHEETS.xhtml')
| -rw-r--r-- | i18n/STYLESHEETS.xhtml | 560 |
1 files changed, 560 insertions, 0 deletions
diff --git a/i18n/STYLESHEETS.xhtml b/i18n/STYLESHEETS.xhtml new file mode 100644 index 00000000..b4934942 --- /dev/null +++ b/i18n/STYLESHEETS.xhtml @@ -0,0 +1,560 @@ +<?xml version="1.0"?> +<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Translating the Stylesheets</title><style> + div[class~="caution"] { + background-image: url("caution.png"); + } + div[class~="important"] { + background-image: url("important.png"); + } + div[class~="note"] { + background-image: url("note.png"); + } + div[class~="tip"] { + background-image: url("tip.png"); + } + div[class~="warning"] { + background-image: url("warning.png"); + } + div[class~="admonition"] { + margin-left: 2em; + margin-right: 2em; + padding-top: 4px; + padding-bottom: 4px; + padding-left: 56px; + padding-right: 8px; + min-height: 52px; + border: dotted #D1940C 1px; + background-position: 4px 4px; + background-repeat: no-repeat; + } + + div[class~="autotoc"] { margin-left: 2em; padding: 0em; } + div[class~="autotoc"] ul { margin-left: 0em; padding-left: 0em; } + div[class~="autotoc"] ul li { + margin-right: 0em; + padding: 0em; + list-style-type: none; + } + + div[class~="figure"] { margin-left: 2em; margin-right: 1em; } + pre[class~="programlisting"] { + margin-left: 2em; + margin-right: 1em; + padding: 6px; + -moz-border-radius: 8px; + overflow: auto;background-color: #EEEEEE;border: solid 1px #DDDDDD + } + pre[class~="screen"] { + margin-left: 2em; + margin-right: 1em; + padding: 6px; + -moz-border-radius: 8px; + overflow: auto;background-color: #EEEEEE;border: solid 1px #DDDDDD + } + pre[class~="synopsis"] { + margin-left: 2em; + margin-right: 1em; + overflow: auto; + } + pre[class~="linenumbering"] { + + margin-top: 0px; + margin-left: 0.8em; + background-color: black; + color: white; + -moz-opacity: .3; + padding-right: 0.4em; + padding-left: 0.4em; + } + blockquote[class~="blockquote"] { margin-left: 2em; margin-right: 1em; } + dt[class~="glossterm"] { margin-left: 0em; } + dd + dt[class~="glossterm"] { margin-top: 2em; } + dd[class~="glossdef"] + { margin-top: 1em; margin-left: 2em; margin-right: 1em; } + dd[class~="glosssee"] + { margin-top: 1em; margin-left: 2em; margin-right: 1em; } + dd[class~="glossseealso"] + { margin-top: 1em; margin-left: 2em; margin-right: 1em; } + + span[class~="co"] { + font-size: 8px; + padding-left: 0.4em; + padding-right: 0.4em; + margin-left: 0.2em; + margin-right: 0.2em; + border: solid 1px; + -moz-border-radius: 8px; + color: #FFFFFF; + background-color: #000000; + border-color: #000000; + } + span[class~="co"]:hover { + color: #FFFFFF; + background-color: #333333; + border-color: #333333; + } + span[class~="co"] a { text-decoration: none; } + span[class~="co"] a:hover { text-decoration: none; } + + div[class~="cmdsynopsis"] { font-family: monospace; } + + div[class~="list"] { margin-left: 0px; padding: 0px; margin-bottom: 1em; } + div[class~="list"] dl dt { margin-left: 0em; } + div[class~="list"] dl dd + dt { margin-top: 1em; } + div[class~="list"] dl dd { + margin-top: 1em; + margin-left: 2em; + margin-right: 1em; + } + div[class~="list"] ul { margin-left: 2em; padding-left: 0em; } + div[class~="list"] ol { margin-left: 2em; padding-left: 0em; } + div[class~="list"] ul li { margin-right: 1em; padding: 0em; } + div[class~="list"] ol li { margin-right: 1em; padding: 0em; } + div[class~="list"] li + li { margin-top: 0.5em; } + + dt[class~="question"] { margin-left: 0em; } + dt[class~="question"] div[class~="label"] { float: left; } + dd + dt[class~="question"] { margin-top: 1em; } + dd[class~="answer"] { + margin-top: 1em; + margin-left: 2em; + margin-right: 1em; + } + dd[class~="answer"] div[class~="label"] { float: left; } + + div[class~="refentry"] h2[class~="refentry"] { + border: none; + margin-top: 1em; + } + div[class~="refentry"] + div[class~="refentry"] { + border-top: dashed black 1px; + } + + div[class~="table"] { margin-left: 2em; } + table { + border-collapse: collapse; + border: solid 1px; + -moz-border-radius: 5px; + } + tr[class~="odd"] { background-color: #F0F0F0 } + td { + padding-left: 0.8em; + padding-right: 0.8em; + padding-top: 4px; + padding-bottom: 4px; + } + th { padding-left: 0.8em; padding-right: 0.8em; } + thead { + border-top: solid 2px; + border-bottom: solid 2px; + } + tfoot { + border-top: solid 2px; + border-bottom: solid 2px; + } + td + td { + border-left: solid 1px; + } + tbody { + border: solid 1px; + -moz-border-radius: 5px; + } + + h1 { font-size: 1.6em; margin-top: 0em; } + h2 { font-size: 1.4em; } + h2[class~="title"] { margin-top: 3em; border-bottom: solid 1px; } + + h3 { font-size: 1.2em; } + h3[class~="title"] { margin-top: 2em; } + h3 span[class~="title"] { border-bottom: solid 1px; } + + h4 { font-size: 1.0em; } + h4[class~="title"] { margin-top: 1.5em; } + h4 span[class~="title"] { border-bottom: solid 1px; } + + h5 { font-size: 1em; margin-top: 1em; } + h6 { font-size: 1em; margin-top: 1em; } + h7 { font-size: 1em; margin-top: 1em; } + + div[class~="title"] { margin-bottom: 0em; } + div[class~="title"] + * { margin-top: 0em; } + + body { + margin: 0px; + } + div[class ~= "body"] { + padding: 12px; + } + div[class ~= "navbar"] { + margin-left: 12px; + margin-right: 12px; + margin-bottom: 12px; + padding: 6px; + border: solid 1px; + } + div[class ~= "navbar-prev"] { + margin: 0px; + padding: 0px; + float: left; + } + div[class ~= "navbar-prev-sans-next"] { + float: none; + } + div[class ~= "navbar-next"] { + margin: 0px; + padding: 0px; + text-align: right; + } + div { + margin-top: 0em; margin-bottom: 0em; + padding-top: 0em; padding-bottom: 0em; + } + p { + margin-top: 0em; margin-bottom: 0em; + padding-top: 0em; padding-bottom: 0em; + } + div + * { margin-top: 1em; } + p + * { margin-top: 1em; } + p > div { margin-top: 1em; } + p { text-align: justify; } + </style></head><body><div class="body"><div class="section"><a name="translating"/><h1 class="section title"><span class="title">Translating the Stylesheets</span></h1><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 + <span class="command" style="font-family: monospace; ">intltool</span>. After they have been translated, <span class="command" style="font-family: monospace; ">intltool</span> merges them into + an XML file called <span class="filename" style="font-family: monospace; ">l10n.xml</span>, which is then used by the stylesheets to + localize the output.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><div class="admonition note"> + <div class="title"><span class="title"><b>Help Us Help You</b></span></div> + <p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p> + </div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><div class="section"><a name="translating-simple"/><h2 class="section title"><span class="title"><span class="label">1. </span>Simple Strings</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Translated strings are extracted in the stylesheets by a template + called <span class="function" style="font-family: monospace; ">l10n.gettext</span>. This template extracts strings from an XML file, + which is built from PO files by <span class="command" style="font-family: monospace; ">intltool</span>. For example, consider the + string <span class="wordasword" style="font-style: italic; ">Caution</span>, which is used as a heading for + <tt class="sgmltag-element">caution</tt> elements. The stylesheets would call + <span class="function" style="font-family: monospace; ">l10n.gettext</span> to extract the translated value of this string for + the document's language. The <span class="filename" style="font-family: monospace; ">l10n.xml</span> file would have an entry + similar to this:</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting"><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></pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <span class="literal" style="font-family: monospace; ">sr</span> locale for the + above string would look like this:</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../xslt/gettext/l10n.xml.in.h:1347 +msgid "Caution" +msgstr "Пажња"</pre></div></div><div class="section"><a name="translating-plurals"/><h2 class="section title"><span class="title"><span class="label">2. </span>Plurals</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <a class="xref" href=".xhtml#translating-roles" title="Roles">Section 3 ― Roles</a> + for a discussion of roles.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <span class="command" style="font-family: monospace; ">intltool</span>'s XML mode. Consequently, translators must + place their translations in an XML fragment. This fragment is merged into + the <span class="filename" style="font-family: monospace; ">l10n.xml</span> file, and the stylesheets extract the appropriate form.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Here is an example entry in the <span class="filename" style="font-family: monospace; ">l10n.xml</span> file:</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting"><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></pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Since the Serbian language has three plural forms, three translations + have been provided. Each of these is placed in a <tt class="sgmltag-element">msgstr</tt> + element, and the <tt class="sgmltag-element">form</tt> attribute is used + to indicate for which plural form they are used.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Again, translators will only see the entries in their PO files. The + PO file entry for the above translation looks like this:</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#. 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>" +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Since <span class="command" style="font-family: monospace; ">intltool</span> 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 <tt class="sgmltag-element">msgstr</tt> elements if they choose. This extra + text content is ignored by <span class="function" style="font-family: monospace; ">l10n.gettext</span>.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Note that translators may add a <tt class="sgmltag-element">msgstr</tt> element + without a <tt class="sgmltag-attribute">form</tt> attribute as a fallback + translation. In the example above, the last two <tt class="sgmltag-element">msgstr</tt> + elements could have been replaced by a single <tt class="sgmltag-element">msgstr</tt> + element without a <tt class="sgmltag-attribute">form</tt> attribute. + The <span class="function" style="font-family: monospace; ">l10n.gettext</span> template would match the first element whenever the + plural form is 0, and the fallback element otherwise.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The plural form is selected using the <span class="function" style="font-family: monospace; ">l10n.plural.form</span> 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 <span class="literal" style="font-family: monospace; ">Plural-Forms</span> 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.</p></div><div class="section"><a name="translating-roles"/><h2 class="section title"><span class="title"><span class="label">3. </span>Roles</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <tt class="sgmltag-element">role</tt> + 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. + </p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Translating using roles is similar to translating using plural + forms. A translation consists of any number of <tt class="sgmltag-element">msgstr</tt> + elements, each with a <tt class="sgmltag-attribute">role</tt> attribute. + A <tt class="sgmltag-element">msgstr</tt> element without an attribute can be provided + as a default if none of the roles match.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">For example, the <tt class="sgmltag-element">citetitle</tt> element in DocBook + is used to cite the title of a publication. The type of the publication + is specified in the <tt class="sgmltag-attribute">class</tt> 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.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting"><msgstr role='article'>“<node/>”</msgstr> +<msgstr><i><node/></i></msg:msgstr> +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The Serbian translation team has chosen to follow the same + convention of quoting article titles and italicizing all others. + The entry in <span class="filename" style="font-family: monospace; ">sr.po</span> follows.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../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>" +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The meaning of the markup inside the <tt class="sgmltag-element">msgstr</tt> + elements will be explained in <a class="xref" href=".xhtml#translating-formats" title="Format Strings">Section 4 ― Format Strings</a>. + For now, simply note that multiple strings have been provided, each + in a <tt class="sgmltag-element">msgstr</tt> 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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Note also that the original translation contains an additional + <tt class="sgmltag-element">msgid</tt> 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 <tt class="sgmltag-element">msgid</tt> 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 <tt class="sgmltag-element">msgstr</tt> + element with no attributes.</p></div><div class="section"><a name="translating-formats"/><h2 class="section title"><span class="title"><span class="label">4. </span>Format Strings</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The Gnome documentation stylesheets can translate more than simple + strings using specialized format strings. These 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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">For instance, DocBook provides the <tt class="sgmltag-element">quote</tt> 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.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../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>" +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Multiple <tt class="sgmltag-element">msgstr</tt> elements have been provided + with roles. These are used to distinguish inner quotes from outer + quotes. Roles were described in <a class="xref" href=".xhtml#translating-roles" title="Roles">Section 3 ― Roles</a>. + The <tt class="sgmltag-element">msgstr</tt> elements also contain inline markup. + This markup is used to insert additional content. In this case, + only the <tt class="sgmltag-emptytag"><node/></tt> element has been + used. This element is replaced by the contents of the quotation + element being processed.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">In addition to marker elements in format strings, translators + may also use simple inline formatting markup. Currently, the only + supported elements are <tt class="sgmltag-element">i</tt> for italics, + <tt class="sgmltag-element">b</tt> for bold, and <tt class="sgmltag-element">tt</tt> for + monospace. This may be expanded to include all of PangoMarkup + in the future.</p></div><div class="section"><a name="translating-types"/><h2 class="section title"><span class="title"><span class="label">5. </span>Common Formatter Types</span></h2><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><div class="section"><a name="translating-types-labels"/><h3 class="section title"><span class="title"><span class="label">5.1. </span>Label Formatters</span></h3><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The Serbian label formatters for sections and figures follow.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../xslt/gettext/l10n.xml.in.h:1128 +msgid "" +"<msgid>section.label</msgid> " +"<msgstr role='header'><number/>.&#x2003;</msgstr> " +"<msgstr role='li'><number/>.&#x2002;</msgstr> " +"<msgstr>Section <number/></msgstr>" +msgstr "" +"<msgstr role='header'><number/>.&#x2003;</msgstr>\n" +"<msgstr role='li'><number/>.&#x2002;</msgstr>\n" +"<msgstr>Одељак <number/></msgstr>" + +#: ../xslt/gettext/l10n.xml.in.h:492 +msgid "" +"<msgid>figure.label</msgid> " +"<msgstr role='header'><i>Figure <number/></i>&#x2003;</msgstr> " +"<msgstr role='li'>Figure <number/>&#x2002;</msgstr> " +"<msgstr>Figure <number/></msgstr>" +msgstr "" +"<msgstr role='header'><i>Слика <number/></i>&#x2003;</msgstr>\n" +"<msgstr role='li'>Слика <number/>&#x2002;</msgstr>\n" +"<msgstr>Слика <number/></msgstr>" +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">In both cases, translations are provided for the + <span class="literal" style="font-family: monospace; ">header</span> and <span class="literal" style="font-family: monospace; ">li</span> 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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Most label formatters provide three format arguments which + can be used in the translations:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-emptytag"><title/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Insert the title of the element being labeled. + For most types of element, the title is simply provided by the + <tt class="sgmltag-element">title</tt> in DocBook. A few DocBook elements, + notably <tt class="sgmltag-element">refentry</tt>, have more complicated + content models. Translators need only reference the argument, + and the stylesheets will determine the title.</p></dd><dt><span class="term"><tt class="sgmltag-emptytag"><titleabbrev/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Insert the abbreviated title of the element + being labeled. Abbreviated titles are provided by the + <tt class="sgmltag-element">titleabbrev</tt> element in DocBook. If the + labeled element does not have an abbreviated title, the + title is used instead.</p></dd><dt><span class="term"><tt class="sgmltag-emptytag"><number/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd></dl></div></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Since labels are used before titles, most label formatters should + only need to use the number of the element.</p></div><div class="section"><a name="translating-types-numbers"/><h3 class="section title"><span class="title"><span class="label">5.2. </span>Number Formatters</span></h3><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The single-level number of an element in its parent is referred to + as that element's <span class="firstterm" style="font-style: italic; ">digit</span>. Number formatters work + by specifying how to combine the parent element's number with the current + element's digit. Two format arguments are allowed:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-emptytag"><parent/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd><dt><span class="term"><tt class="sgmltag-emptytag"><digit/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd></dl></div></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">The Serbian label formatters for sections and figures follow.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../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>" +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Note that <tt class="sgmltag-element">msgstr</tt> elements are used to contain + the strings, even though neither plural forms nor roles are being used. + This is because a <tt class="sgmltag-element">msgid</tt> has been inserted into the + translatable string to allow number formatters for different elements + to be distinct messages in PO files.</p></div><div class="section"><a name="translating-types-digits"/><h3 class="section title"><span class="title"><span class="label">5.3. </span>Digit Formats</span></h3><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><span class="literal" style="font-family: monospace; ">1</span></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Format the number using Arabic numerals: + 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12.</p></dd><dt><span class="term"><span class="literal" style="font-family: monospace; ">A</span></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Format the number using uppercase Latin letters: + A, B, C, D, E, F, G, H, I, J, K, L.</p></dd><dt><span class="term"><span class="literal" style="font-family: monospace; ">a</span></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Format the number using lowercase Latin letters: + a, b, c, d, e, f, g, h, i, j, k, l.</p></dd><dt><span class="term"><span class="literal" style="font-family: monospace; ">I</span></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Format the number using uppercase Roman numerals: + I, II, III, IV, V, VI, VII, VIII, IX, X, XI, XII:</p></dd><dt><span class="term"><span class="literal" style="font-family: monospace; ">i</span></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Format the number using lowercase Roman numerals: + i, ii, iii, iv, v, vi, vii, viii, ix, x, xi, xii:</p></dd></dl></div></div><div class="admonition note"><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></div></div><div class="section"><a name="translating-types-xrefs"/><h3 class="section title"><span class="title"><span class="label">5.4. </span>Cross Reference Formatters</span></h3><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <tt class="sgmltag-attribute">xrefstyle</tt> attribute on + the <tt class="sgmltag-element">xref</tt> element. The Gnome documentation stylesheets + allow <tt class="sgmltag-attribute">xrefstyle</tt> attributes of the form + <tt class="sgmltag-attvalue">role:<span class="replaceable" style="font-style: italic; ">somerole</span></tt>, + where <span class="replaceable" style="font-style: italic; ">somerole</span> is the role to be passed to the + cross reference formatter.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Cross reference formatters generally provide the following three + format arguments:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-emptytag"><title/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Insert the title of the element being referenced. + For most types of element, the title is simply provided by the + <tt class="sgmltag-element">title</tt> in DocBook. A few DocBook elements, + notably <tt class="sgmltag-element">refentry</tt>, have more complicated + content models. Translators need only reference the argument, + and the stylesheets will determine the title.</p></dd><dt><span class="term"><tt class="sgmltag-emptytag"><titleabbrev/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Insert the abbreviated title of the element + being referenced. Abbreviated titles are provided by the + <tt class="sgmltag-element">titleabbrev</tt> element in DocBook. If the + labeled element does not have an abbreviated title, the + title is used instead.</p></dd><dt><span class="term"><tt class="sgmltag-emptytag"><number/></tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd></dl></div></div></div><div class="section"><a name="translating-types-tooltips"/><h3 class="section title"><span class="title"><span class="label">5.5. </span>Tooltip Formatters</span></h3><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">For example, the <tt class="sgmltag-element">email</tt> element in DocBook is + converted into a hyperlink allowing users to send email to the given + address. The Serbian translation for this formatter follows.</p><div xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="programlisting"><pre class="programlisting">#: ../xslt/gettext/l10n.xml.in.h:329 +msgid "" +"<msgid>email.tooltip</msgid> " +"<msgstr>Send email to ‘<node/>’.</msgstr>" +msgstr "" +"Пошаљите е-писмо на „<node/>“." +</pre></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></div></div></div></div><div class="navbar"/></body></html> |