Common Formatter Types
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.
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.
- 5.5.1. Label Formatters
- 5.5.2. Number Formatters
- 5.5.3. Digit Formats
- 5.5.4. Cross Reference Formatters
- 5.5.5. Tooltip Formatters
5.5.1. Label Formatters
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.
The Serbian label formatters for sections and figures follow.
#: ../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>"
In both cases, translations are provided for the header and li 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.
Most label formatters provide three format arguments which can be used in the translations:
- <title/>
Insert the title of the element being labeled. For most types of element, the title is simply provided by the title in DocBook. A few DocBook elements, notably refentry, have more complicated content models. Translators need only reference the argument, and the stylesheets will determine the title.
- <titleabbrev/>
Insert the abbreviated title of the element being labeled. Abbreviated titles are provided by the titleabbrev element in DocBook. If the labeled element does not have an abbreviated title, the title is used instead.
- <number/>
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.
Since labels are used before titles, most label formatters should only need to use the number of the element.
5.5.2. Number Formatters
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.
The single-level number of an element in its parent is referred to as that element's digit. Number formatters work by specifying how to combine the parent element's number with the current element's digit. Two format arguments are allowed:
- <parent/>
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.
- <digit/>
Insert the single-level position of the element in its parent element. How the digit is displayed is determined by the corresponding digit format.
The Serbian label formatters for sections and figures follow.
#: ../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>"
Note that msgstr elements are used to contain the strings, even though neither plural forms nor roles are being used. This is because a msgid has been inserted into the translatable string to allow number formatters for different elements to be distinct messages in PO files.
5.5.3. Digit Formats
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.
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:
- 1
Format the number using Arabic numerals: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12.
- A
Format the number using uppercase Latin letters: A, B, C, D, E, F, G, H, I, J, K, L.
- a
Format the number using lowercase Latin letters: a, b, c, d, e, f, g, h, i, j, k, l.
- I
Format the number using uppercase Roman numerals: I, II, III, IV, V, VI, VII, VIII, IX, X, XI, XII:
- i
Format the number using lowercase Roman numerals: i, ii, iii, iv, v, vi, vii, viii, ix, x, xi, xii:
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.
5.5.4. Cross Reference Formatters
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.
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 xref element. The Gnome documentation stylesheets allow xrefstyle attributes of the form role:somerole, where somerole is the role to be passed to the cross reference formatter.
Cross reference formatters generally provide the following three format arguments:
- <title/>
Insert the title of the element being referenced. For most types of element, the title is simply provided by the title in DocBook. A few DocBook elements, notably refentry, have more complicated content models. Translators need only reference the argument, and the stylesheets will determine the title.
- <titleabbrev/>
Insert the abbreviated title of the element being referenced. Abbreviated titles are provided by the titleabbrev element in DocBook. If the labeled element does not have an abbreviated title, the title is used instead.
- <number/>
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.
5.5.5. Tooltip Formatters
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.
For example, the email element in DocBook is converted into a hyperlink allowing users to send email to the given address. The Serbian translation for this formatter follows.
#: ../xslt/gettext/l10n.xml.in.h:329 msgid "" "<msgid>email.tooltip</msgid> " "<msgstr>Send email to ‘<node/>’.</msgstr>" msgstr "" "Пошаљите е-писмо на „<node/>“."
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.