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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
|
<?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"] {
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~="biblioentry"] { margin-top: 1.2em; }
* + div[class~="bibliomixed"] { margin-top: 1.2em; }
*[class~="block-indent"] {
margin-left: 1.72em;
margin-right: 1em;
}
*[class~="block-indent"] *[class~="block-indent"] {
margin-left: 0em;
margin-right: 0em;
}
*[class~="block-verbatim"] {
white-space: pre;
}
pre[class~="programlisting"] {
padding: 6px;
-moz-border-radius: 8px;
overflow: auto;background-color: #EEEEEE;border: solid 1px #DDDDDD
}
pre[class~="screen"] {
padding: 6px;
-moz-border-radius: 8px;
overflow: auto;background-color: #EEEEEE;border: solid 1px #DDDDDD
}
pre[class~="synopsis"] {
overflow: auto;
}
pre[class~="linenumbering"] {
padding-top: 6px;
padding-bottom: 6px;
-moz-border-radius: 8px;
border: solid 1px black;
margin-top: 0px;
margin-left: 0.83em;
background-color: black;
color: white;
-moz-opacity: .3;
padding-right: 0.4em;
padding-left: 0.4em;
}
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: 0.69em;
margin-left: 1.72em;
margin-right: 1em;
}
div[class~="list"] ul { margin-left: 1.72em; padding-left: 0em; }
div[class~="list"] ol { margin-left: 1.72em; 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.69em; }
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;
}
table {
border-collapse: collapse;
border: solid 1px;
-moz-border-radius: 5px;
}
tr[class~="odd"] { background-color: #F0F0F0 }
td {
padding-left: 0.83em;
padding-right: 0.83em;
padding-top: 4px;
padding-bottom: 4px;
}
th { padding-left: 0.8em; padding-right: 0.83em; }
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.72em; margin-top: 0em; }
h2 { font-size: 1.44em; }
h2[class~="title"] { margin-top: 1.72em; border-bottom: solid 1px; }
h3 { font-size: 1.2em; }
h3[class~="title"] { margin-top: 1.72em; }
h3 span[class~="title"] { border-bottom: solid 1px; }
h4 { font-size: 1.0em; }
h4[class~="title"] { margin-top: 1.44em; }
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; }
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; margin-bottom: 1em; }
p > div + div { margin-top: 0em; }
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 block-indent 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 block-indent"><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 block-indent"><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 block-indent"><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 block-indent"><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 block-indent"><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 block-indent"><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">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.</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 block-indent"><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. Any content can be
wrapped in a <tt class="sgmltag-element">span</tt> 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:</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-element">font-family</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-style</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">This attribute can be used to italicize the text.
The allowed values are italic, oblique, and normal.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-variant</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.
</p></dd><dt><span class="term"><tt class="sgmltag-element">font-weight</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-stretch</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd><dt><span class="term"><tt class="sgmltag-element">font-size</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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 <tt class="sgmltag-element">big</tt> and
<tt class="sgmltag-element">small</tt> convenience elements described below.
They are defined to respect the size scales used throughout the
stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">text-decoration</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="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.</p></dd></dl></div></div><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Additionally, extra inline elements are provided for convenience.
The formatting done by these elements could also be done using the
<tt class="sgmltag-element">span</tt> element. Using these elements is just easier
for common formatting tasks.</p><div class="list"><div class="variablelist"><dl><dt><span class="term"><tt class="sgmltag-element">big</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text larger. This is preferred over using
the <tt class="sgmltag-element">font-size</tt> attribute, because it is defined to
use the size scale used throughout the stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">small</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text smaller. This is preferred over using
the <tt class="sgmltag-element">font-size</tt> attribute, because it is defined to
use the size scale used throughout the stylesheets.</p></dd><dt><span class="term"><tt class="sgmltag-element">sub</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Render the text as a subscript.</p></dd><dt><span class="term"><tt class="sgmltag-element">sup</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Render the text as a superscript.</p></dd><dt><span class="term"><tt class="sgmltag-element">b</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text bold. This is equivalent to setting
the <tt class="sgmltag-element">font-weight</tt> attribute to bold.</p></dd><dt><span class="term"><tt class="sgmltag-element">i</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text italic. This is equivalent to setting
the <tt class="sgmltag-element">font-style</tt> attribute to italic.</p></dd><dt><span class="term"><tt class="sgmltag-element">tt</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Make the text monospace. This is equivalent to setting
the <tt class="sgmltag-element">font-family</tt> attribute to monospace.</p></dd><dt><span class="term"><tt class="sgmltag-element">u</tt></span></dt><dd><p xmlns:msg="http://www.gnome.org/~shaunm/gnome-doc-utils/l10n" class="para">Underline the text. This is equivalent to setting the
<tt class="sgmltag-element">text-decoration</tt> attribute to underline.</p></dd></dl></div></div></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 block-indent"><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 block-indent"><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 block-indent 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 block-indent"><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>
|
