1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:xsl="FIXME" style="xslt-template" id="l10n.gettext">
<info>
<link type="guide" xref="l10n" group="templates"/>
<link type="guide" xref="templates" group="l10n"/>
<desc>Look up the translation for a string.</desc>
<revision version="3.18" date="2015-07-29" status="final"/>
</info>
<title>l10n.gettext</title>
<synopsis>
<title>Parameters</title>
<terms>
<item>
<title><code>$domain</code></title>
<p>The domain to look up the string in.</p>
</item>
<item>
<title><code>$msgid</code></title>
<p>The id of the string to look up, often the string in the C locale.</p>
</item>
<item>
<title><code>$lang</code></title>
<p>The locale to use when looking up the translated string.</p>
</item>
<item>
<title><code>$number</code></title>
<p>The cardinality for plural-form lookups.</p>
</item>
<item>
<title><code>$form</code></title>
<p>The form name for plural-form lookups.</p>
</item>
<item>
<title><code>$format</code></title>
<p>Whether to treat the result as a format string.</p>
</item>
<item>
<title><code>$node</code></title>
<p>A context node to pass to <code xref="l10n.format.mode">l10n.format.mode</code>.</p>
</item>
<item>
<title><code>$string</code></title>
<p>A string to pass to <code xref="l10n.format.mode">l10n.format.mode</code> for <sys>msg:string</sys> elements.</p>
</item>
</terms>
</synopsis>
<p>This template extracts a translated version of a source string. In simple cases,
the source string is exactly the string in <code>$msgid</code>, though in more complex
cases, the <code>$msgid</code> parameter is a separate unique identifier.</p>
<p>This template looks up the translation in a message catalog file based on the
<code>$domain</code> parameter. The file must be in a <sys>domains</sys> subdirectory relative to
the directory holding this stylesheet and be named the same as <code>$domain</code> with
the suffix <sys>.xml</sys>. This template will fail if no such file is found. By
default, the domain is <sys>yelp-xsl</sys> to reference the translations shipped with
these stylesheets. Extensions and third-party stylesheets, however, can use
this template by installing a file and passing the <code>$domain</code> parameter.</p>
<p>The message catalog file format is designed to work with the XML/PO translation
tool <sys>itstool</sys>, using its join mode to create a single polylingual file. There
is no tool to automatically extract messages from XSLT files. You must add
messages to the source catalog file when adding translatable strings.</p>
<p>The message catalog file contains a set of <sys>msg</sys> elements, one for each string
that needs translation. Each <sys>msg</sys> element has an <sys>id</sys> attribute. It is this
attribute that is matched against the <code>$msgid</code> parameter. Each <sys>msg</sys> element
then has one or more <sys>msgstr</sys> elements, each with an <sys>xml:lang</sys> attribute.
This template tries to find a best match language with the <code>$lang</code> parameter,
falling back to a <sys>msgstr</sys> element with no <sys>xml:lang</sys> attribute.</p>
<p>In a source message catalog file, put the string to be translated inside a
singleton <sys>msgstr</sys> element in each <sys>msg</sys> element, without an <sys>xml:lang</sys>
parameter. Add this element even if it is the same as the <sys>id</sys> attribute of
the <sys>msg</sys> element. These <sys>msgstr</sys> elements are what <sys>itstool</sys> uses to create
a PO file, and it provides the fallback string when no language matches.</p>
<p>The <sys>xml:lang</sys> attribute should contain an RFC 3066 language identifier, which
is different from the POSIX locale identifiers used by gettext. To accommodate
this difference, this stylesheet converts all identifiers to lowercase and
replaces the characters <sys>_</sys>, <sys>@</sys>, and <sys>.</sys> with the character <sys>-</sys>. If it
cannot find an exact match, it strips the part after the last <sys>-</sys> and looks
again. It repeats this as long as the identifier contains a <sys>-</sys> character.
If there is still no matching <sys>msgstr</sys> element, it looks for one with no
<sys>xml:lang</sys> attribute.</p>
<p>Sometimes you have to provide different versions of a string for different
cardinalities. While English and many other languages have singular and plural,
some languages have no plural forms, while others have as many as six. These
stylesheets use a numeric index for plural forms, similarly to gettext. To get
the string for a plural, pass the cardinality in the <code>$number</code> parameter. This
template gets an index for that number by calling <code xref="l10n.plural.form">l10n.plural.form</code>. The
plural form index is in the <code>$form</code> parameter. You do not have to pass this
parameter. It will be computed automatically based on the <code>$number</code> parameter.</p>
<p>There is currently no support for editing plural forms using the standard PO
syntax. Instead, plurals are defined with an XML snippet. Instead of putting
the single translated message in the <sys>msgstr</sys> element, plural messages have
<sys>msgstr</sys> child elements of the <sys>msgstr</sys> element with the <sys>xml:lang</sys>
attribute. Each of these child <sys>msgstr</sys> elements has a <sys>form</sys> attribute that
holds the numeric index returned by <code xref="l10n.plural.form">l10n.plural.form</code>. Translators must adapt
the XML snippet according to the plural rules and forms defined in this
stylesheet for their language.</p>
<p>Some translations aren't simple strings, but are instead format strings where
certain values are inserted. This template can handle format strings with XML
marker elements to signal where values should be substituted. These values
can be the result of applying templates.</p>
<p>To enable format strings, set the <code>$format</code> parameter to <sys>true()</sys>.
Instead of just returning the translated string, this template will
apply templates in the mode <code xref="l10n.format.mode">l10n.format.mode</code> to the fragment contained in
the <sys>msgstr</sys> element.</p>
<p>The <code>$node</code> and <code>$string</code> parameters are passed to templates in
<code xref="l10n.format.mode">l10n.format.mode</code>. This stylesheet contains matches in <code xref="l10n.format.mode">l10n.format.mode</code>
for the marker elements <sys><string/></sys> and <sys><node/></sys>. The element
<sys><string/></sys> will be replaced by the string value of <code>$string</code>. The
element <sys><node/></sys> will apply templates without a mode to <code>$node</code>.
Text nodes are copied to the result in <code xref="l10n.format.mode">l10n.format.mode</code>.</p>
<p>If you need any other behavior, add elements with any name of your choosing to
the format string, then match on those elements in <code xref="l10n.format.mode">l10n.format.mode</code>. You will
be able to use the <code>$node</code> and <code>$string</code> parameters in your template. Try to
use a name that is unique.</p>
<list style="compact">
<title>Calls Parameters</title>
<item>
<p><link xref="l10n.locale"/></p>
</item>
</list>
<list style="compact">
<title>Calls Keys</title>
<item>
<p><link xref="l10n.msgstr.key"/></p>
</item>
</list>
<list style="compact">
<title>Calls Templates</title>
<item>
<p><link xref="l10n.gettext"/></p>
</item>
<item>
<p><link xref="l10n.gettext.msg"/></p>
</item>
<item>
<p><link xref="l10n.plural.form"/></p>
</item>
</list>
</page>
|
