| 1 |
<!-- doc/src/sgml/nls.sgml --> |
| 2 |
|
| 3 |
<chapter id="nls"> |
| 4 |
<title>Native Language Support</title> |
| 5 |
|
| 6 |
<sect1 id="nls-translator"> |
| 7 |
<title>For the Translator</title> |
| 8 |
|
| 9 |
<para> |
| 10 |
<productname>PostgreSQL</productname> |
| 11 |
programs (server and client) can issue their messages in |
| 12 |
your favorite language — if the messages have been translated. |
| 13 |
Creating and maintaining translated message sets needs the help of |
| 14 |
people who speak their own language well and want to contribute to |
| 15 |
the <productname>PostgreSQL</productname> effort. You do not have to be a |
| 16 |
programmer at all |
| 17 |
to do this. This section explains how to help. |
| 18 |
</para> |
| 19 |
|
| 20 |
<sect2 id="nls-translator-requirements"> |
| 21 |
<title>Requirements</title> |
| 22 |
|
| 23 |
<para> |
| 24 |
We won't judge your language skills — this section is about |
| 25 |
software tools. Theoretically, you only need a text editor. But |
| 26 |
this is only in the unlikely event that you do not want to try out |
| 27 |
your translated messages. When you configure your source tree, be |
| 28 |
sure to use the <option>--enable-nls</option> option. This will |
| 29 |
also check for the <application>libintl</application> library and the |
| 30 |
<filename>msgfmt</filename> program, which all end users will need |
| 31 |
anyway. To try out your work, follow the applicable portions of |
| 32 |
the installation instructions. |
| 33 |
</para> |
| 34 |
|
| 35 |
<para> |
| 36 |
If you want to start a new translation effort or want to do a |
| 37 |
message catalog merge (described later), you will need the |
| 38 |
programs <filename>xgettext</filename> and |
| 39 |
<filename>msgmerge</filename>, respectively, in a GNU-compatible |
| 40 |
implementation. Later, we will try to arrange it so that if you |
| 41 |
use a packaged source distribution, you won't need |
| 42 |
<filename>xgettext</filename>. (If working from Git, you will still need |
| 43 |
it.) <application>GNU Gettext 0.10.36</application> or later is currently recommended. |
| 44 |
</para> |
| 45 |
|
| 46 |
<para> |
| 47 |
Your local gettext implementation should come with its own |
| 48 |
documentation. Some of that is probably duplicated in what |
| 49 |
follows, but for additional details you should look there. |
| 50 |
</para> |
| 51 |
</sect2> |
| 52 |
|
| 53 |
<sect2 id="nls-translator-concepts"> |
| 54 |
<title>Concepts</title> |
| 55 |
|
| 56 |
<para> |
| 57 |
The pairs of original (English) messages and their (possibly) |
| 58 |
translated equivalents are kept in <firstterm>message |
| 59 |
catalogs</firstterm>, one for each program (although related |
| 60 |
programs can share a message catalog) and for each target |
| 61 |
language. There are two file formats for message catalogs: The |
| 62 |
first is the <quote>PO</quote> file (for Portable Object), which |
| 63 |
is a plain text file with special syntax that translators edit. |
| 64 |
The second is the <quote>MO</quote> file (for Machine Object), |
| 65 |
which is a binary file generated from the respective PO file and |
| 66 |
is used while the internationalized program is run. Translators |
| 67 |
do not deal with MO files; in fact hardly anyone does. |
| 68 |
</para> |
| 69 |
|
| 70 |
<para> |
| 71 |
The extension of the message catalog file is to no surprise either |
| 72 |
<filename>.po</filename> or <filename>.mo</filename>. The base |
| 73 |
name is either the name of the program it accompanies, or the |
| 74 |
language the file is for, depending on the situation. This is a |
| 75 |
bit confusing. Examples are <filename>psql.po</filename> (PO file |
| 76 |
for psql) or <filename>fr.mo</filename> (MO file in French). |
| 77 |
</para> |
| 78 |
|
| 79 |
<para> |
| 80 |
The file format of the PO files is illustrated here: |
| 81 |
<programlisting> |
| 82 |
# comment |
| 83 |
|
| 84 |
msgid "original string" |
| 85 |
msgstr "translated string" |
| 86 |
|
| 87 |
msgid "more original" |
| 88 |
msgstr "another translated" |
| 89 |
"string can be broken up like this" |
| 90 |
|
| 91 |
... |
| 92 |
</programlisting> |
| 93 |
The msgid lines are extracted from the program source. (They need not |
| 94 |
be, but this is the most common way.) The msgstr lines are |
| 95 |
initially empty and are filled in with useful strings by the |
| 96 |
translator. The strings can contain C-style escape characters and |
| 97 |
can be continued across lines as illustrated. (The next line must |
| 98 |
start at the beginning of the line.) |
| 99 |
</para> |
| 100 |
|
| 101 |
<para> |
| 102 |
The # character introduces a comment. If whitespace immediately |
| 103 |
follows the # character, then this is a comment maintained by the |
| 104 |
translator. There can also be automatic comments, which have a |
| 105 |
non-whitespace character immediately following the #. These are |
| 106 |
maintained by the various tools that operate on the PO files and |
| 107 |
are intended to aid the translator. |
| 108 |
<programlisting> |
| 109 |
#. automatic comment |
| 110 |
#: filename.c:1023 |
| 111 |
#, flags, flags |
| 112 |
</programlisting> |
| 113 |
The #. style comments are extracted from the source file where the |
| 114 |
message is used. Possibly the programmer has inserted information |
| 115 |
for the translator, such as about expected alignment. The #: |
| 116 |
comments indicate the exact locations where the message is used |
| 117 |
in the source. The translator need not look at the program |
| 118 |
source, but can if there is doubt about the correct |
| 119 |
translation. The #, comments contain flags that describe the |
| 120 |
message in some way. There are currently two flags: |
| 121 |
<literal>fuzzy</literal> is set if the message has possibly been |
| 122 |
outdated because of changes in the program source. The translator |
| 123 |
can then verify this and possibly remove the fuzzy flag. Note |
| 124 |
that fuzzy messages are not made available to the end user. The |
| 125 |
other flag is <literal>c-format</literal>, which indicates that |
| 126 |
the message is a <function>printf</function>-style format |
| 127 |
template. This means that the translation should also be a format |
| 128 |
string with the same number and type of placeholders. There are |
| 129 |
tools that can verify this, which key off the c-format flag. |
| 130 |
</para> |
| 131 |
</sect2> |
| 132 |
|
| 133 |
<sect2 id="nls-translator-message-catalogs"> |
| 134 |
<title>Creating and Maintaining Message Catalogs</title> |
| 135 |
|
| 136 |
<para> |
| 137 |
OK, so how does one create a <quote>blank</quote> message |
| 138 |
catalog? First, go into the directory that contains the program |
| 139 |
whose messages you want to translate. If there is a file |
| 140 |
<filename>nls.mk</filename>, then this program has been prepared |
| 141 |
for translation. |
| 142 |
</para> |
| 143 |
|
| 144 |
<para> |
| 145 |
If there are already some <filename>.po</filename> files, then |
| 146 |
someone has already done some translation work. The files are |
| 147 |
named <filename><replaceable>language</replaceable>.po</filename>, |
| 148 |
where <replaceable>language</replaceable> is the |
| 149 |
<ulink url="https://www.loc.gov/standards/iso639-2/php/English_list.php"> |
| 150 |
ISO 639-1 two-letter language code (in lower case)</ulink>, e.g., |
| 151 |
<filename>fr.po</filename> for French. If there is really a need |
| 152 |
for more than one translation effort per language then the files |
| 153 |
can also be named |
| 154 |
<filename><replaceable>language</replaceable>_<replaceable>region</replaceable>.po</filename> |
| 155 |
where <replaceable>region</replaceable> is the |
| 156 |
<ulink url="https://www.iso.org/iso-3166-country-codes.html"> |
| 157 |
ISO 3166-1 two-letter country code (in upper case)</ulink>, |
| 158 |
e.g., |
| 159 |
<filename>pt_BR.po</filename> for Portuguese in Brazil. If you |
| 160 |
find the language you wanted you can just start working on that |
| 161 |
file. |
| 162 |
</para> |
| 163 |
|
| 164 |
<para> |
| 165 |
If you need to start a new translation effort, then first run the |
| 166 |
command: |
| 167 |
<programlisting> |
| 168 |
make init-po |
| 169 |
</programlisting> |
| 170 |
This will create a file |
| 171 |
<filename><replaceable>progname</replaceable>.pot</filename>. |
| 172 |
(<filename>.pot</filename> to distinguish it from PO files that |
| 173 |
are <quote>in production</quote>. The <literal>T</literal> stands for |
| 174 |
<quote>template</quote>.) |
| 175 |
Copy this file to |
| 176 |
<filename><replaceable>language</replaceable>.po</filename> and |
| 177 |
edit it. To make it known that the new language is available, |
| 178 |
also edit the file <filename>po/LINGUAS</filename> and add the |
| 179 |
language (or language and country) code next to languages already listed, |
| 180 |
like: |
| 181 |
<programlisting> |
| 182 |
de fr |
| 183 |
</programlisting> |
| 184 |
(Other languages can appear, of course.) |
| 185 |
</para> |
| 186 |
|
| 187 |
<para> |
| 188 |
As the underlying program or library changes, messages might be |
| 189 |
changed or added by the programmers. In this case you do not need |
| 190 |
to start from scratch. Instead, run the command: |
| 191 |
<programlisting> |
| 192 |
make update-po |
| 193 |
</programlisting> |
| 194 |
which will create a new blank message catalog file (the pot file |
| 195 |
you started with) and will merge it with the existing PO files. |
| 196 |
If the merge algorithm is not sure about a particular message it |
| 197 |
marks it <quote>fuzzy</quote> as explained above. The new PO file |
| 198 |
is saved with a <filename>.po.new</filename> extension. |
| 199 |
</para> |
| 200 |
</sect2> |
| 201 |
|
| 202 |
<sect2 id="nls-translator-editing-po"> |
| 203 |
<title>Editing the PO Files</title> |
| 204 |
|
| 205 |
<para> |
| 206 |
The PO files can be edited with a regular text editor. There are also |
| 207 |
several specialized editors for PO files which can help the process with |
| 208 |
translation-specific features. |
| 209 |
There is (unsurprisingly) a PO mode for Emacs, which can be quite |
| 210 |
useful. |
| 211 |
</para> |
| 212 |
|
| 213 |
<para> |
| 214 |
The translator should only change the area between the quotes after |
| 215 |
the msgstr directive, add comments, and alter the fuzzy flag. |
| 216 |
</para> |
| 217 |
|
| 218 |
<para> |
| 219 |
The PO files need not be completely filled in. The software will |
| 220 |
automatically fall back to the original string if no translation |
| 221 |
(or an empty translation) is available. It is no problem to |
| 222 |
submit incomplete translations for inclusions in the source tree; |
| 223 |
that gives room for other people to pick up your work. However, |
| 224 |
you are encouraged to give priority to removing fuzzy entries |
| 225 |
after doing a merge. Remember that fuzzy entries will not be |
| 226 |
installed; they only serve as reference for what might be the right |
| 227 |
translation. |
| 228 |
</para> |
| 229 |
|
| 230 |
<para> |
| 231 |
Here are some things to keep in mind while editing the |
| 232 |
translations: |
| 233 |
<itemizedlist> |
| 234 |
<listitem> |
| 235 |
<para> |
| 236 |
Make sure that if the original ends with a newline, the |
| 237 |
translation does, too. Similarly for tabs, etc. |
| 238 |
</para> |
| 239 |
</listitem> |
| 240 |
|
| 241 |
<listitem> |
| 242 |
<para> |
| 243 |
If the original is a <function>printf</function> format string, the translation |
| 244 |
also needs to be. The translation also needs to have the same |
| 245 |
format specifiers in the same order. Sometimes the natural |
| 246 |
rules of the language make this impossible or at least awkward. |
| 247 |
In that case you can modify the format specifiers like this: |
| 248 |
<programlisting> |
| 249 |
msgstr "Die Datei %2$s hat %1$u Zeichen." |
| 250 |
</programlisting> |
| 251 |
Then the first placeholder will actually use the second |
| 252 |
argument from the list. The |
| 253 |
<literal><replaceable>digits</replaceable>$</literal> needs to |
| 254 |
follow the % immediately, before any other format manipulators. |
| 255 |
(This feature really exists in the <function>printf</function> |
| 256 |
family of functions. You might not have heard of it before because |
| 257 |
there is little use for it outside of message |
| 258 |
internationalization.) |
| 259 |
</para> |
| 260 |
</listitem> |
| 261 |
|
| 262 |
<listitem> |
| 263 |
<para> |
| 264 |
If the original string contains a linguistic mistake, report |
| 265 |
that (or fix it yourself in the program source) and translate |
| 266 |
normally. The corrected string can be merged in when the |
| 267 |
program sources have been updated. If the original string |
| 268 |
contains a factual mistake, report that (or fix it yourself) |
| 269 |
and do not translate it. Instead, you can mark the string with |
| 270 |
a comment in the PO file. |
| 271 |
</para> |
| 272 |
</listitem> |
| 273 |
|
| 274 |
<listitem> |
| 275 |
<para> |
| 276 |
Maintain the style and tone of the original string. |
| 277 |
Specifically, messages that are not sentences (<literal>cannot |
| 278 |
open file %s</literal>) should probably not start with a |
| 279 |
capital letter (if your language distinguishes letter case) or |
| 280 |
end with a period (if your language uses punctuation marks). |
| 281 |
It might help to read <xref linkend="error-style-guide"/>. |
| 282 |
</para> |
| 283 |
</listitem> |
| 284 |
|
| 285 |
<listitem> |
| 286 |
<para> |
| 287 |
If you don't know what a message means, or if it is ambiguous, |
| 288 |
ask on the developers' mailing list. Chances are that English |
| 289 |
speaking end users might also not understand it or find it |
| 290 |
ambiguous, so it's best to improve the message. |
| 291 |
</para> |
| 292 |
</listitem> |
| 293 |
|
| 294 |
</itemizedlist> |
| 295 |
</para> |
| 296 |
</sect2> |
| 297 |
|
| 298 |
</sect1> |
| 299 |
|
| 300 |
|
| 301 |
<sect1 id="nls-programmer"> |
| 302 |
<title>For the Programmer</title> |
| 303 |
|
| 304 |
<sect2 id="nls-mechanics"> |
| 305 |
<title>Mechanics</title> |
| 306 |
|
| 307 |
<para> |
| 308 |
This section describes how to implement native language support in a |
| 309 |
program or library that is part of the |
| 310 |
<productname>PostgreSQL</productname> distribution. |
| 311 |
Currently, it only applies to C programs. |
| 312 |
</para> |
| 313 |
|
| 314 |
<procedure> |
| 315 |
<title>Adding NLS Support to a Program</title> |
| 316 |
|
| 317 |
<step> |
| 318 |
<para> |
| 319 |
Insert this code into the start-up sequence of the program: |
| 320 |
<programlisting> |
| 321 |
#ifdef ENABLE_NLS |
| 322 |
#include <locale.h> |
| 323 |
#endif |
| 324 |
|
| 325 |
... |
| 326 |
|
| 327 |
#ifdef ENABLE_NLS |
| 328 |
setlocale(LC_ALL, ""); |
| 329 |
bindtextdomain("<replaceable>progname</replaceable>", LOCALEDIR); |
| 330 |
textdomain("<replaceable>progname</replaceable>"); |
| 331 |
#endif |
| 332 |
</programlisting> |
| 333 |
(The <replaceable>progname</replaceable> can actually be chosen |
| 334 |
freely.) |
| 335 |
</para> |
| 336 |
</step> |
| 337 |
|
| 338 |
<step> |
| 339 |
<para> |
| 340 |
Wherever a message that is a candidate for translation is found, |
| 341 |
a call to <function>gettext()</function> needs to be inserted. E.g.: |
| 342 |
<programlisting> |
| 343 |
fprintf(stderr, "panic level %d\n", lvl); |
| 344 |
</programlisting> |
| 345 |
would be changed to: |
| 346 |
<programlisting> |
| 347 |
fprintf(stderr, gettext("panic level %d\n"), lvl); |
| 348 |
</programlisting> |
| 349 |
(<symbol>gettext</symbol> is defined as a no-op if NLS support is |
| 350 |
not configured.) |
| 351 |
</para> |
| 352 |
|
| 353 |
<para> |
| 354 |
This tends to add a lot of clutter. One common shortcut is to use: |
| 355 |
<programlisting> |
| 356 |
#define _(x) gettext(x) |
| 357 |
</programlisting> |
| 358 |
Another solution is feasible if the program does much of its |
| 359 |
communication through one or a few functions, such as |
| 360 |
<function>ereport()</function> in the backend. Then you make this |
| 361 |
function call <function>gettext</function> internally on all |
| 362 |
input strings. |
| 363 |
</para> |
| 364 |
</step> |
| 365 |
|
| 366 |
<step> |
| 367 |
<para> |
| 368 |
Add a file <filename>nls.mk</filename> in the directory with the |
| 369 |
program sources. This file will be read as a makefile. The |
| 370 |
following variable assignments need to be made here: |
| 371 |
|
| 372 |
<variablelist> |
| 373 |
<varlistentry> |
| 374 |
<term><varname>CATALOG_NAME</varname></term> |
| 375 |
|
| 376 |
<listitem> |
| 377 |
<para> |
| 378 |
The program name, as provided in the |
| 379 |
<function>textdomain()</function> call. |
| 380 |
</para> |
| 381 |
</listitem> |
| 382 |
</varlistentry> |
| 383 |
|
| 384 |
<varlistentry> |
| 385 |
<term><varname>GETTEXT_FILES</varname></term> |
| 386 |
|
| 387 |
<listitem> |
| 388 |
<para> |
| 389 |
List of files that contain translatable strings, i.e., those |
| 390 |
marked with <function>gettext</function> or an alternative |
| 391 |
solution. Eventually, this will include nearly all source |
| 392 |
files of the program. If this list gets too long you can |
| 393 |
make the first <quote>file</quote> be a <literal>+</literal> |
| 394 |
and the second word be a file that contains one file name per |
| 395 |
line. |
| 396 |
</para> |
| 397 |
</listitem> |
| 398 |
</varlistentry> |
| 399 |
|
| 400 |
<varlistentry> |
| 401 |
<term><varname>GETTEXT_TRIGGERS</varname></term> |
| 402 |
|
| 403 |
<listitem> |
| 404 |
<para> |
| 405 |
The tools that generate message catalogs for the translators |
| 406 |
to work on need to know what function calls contain |
| 407 |
translatable strings. By default, only |
| 408 |
<function>gettext()</function> calls are known. If you used |
| 409 |
<function>_</function> or other identifiers you need to list |
| 410 |
them here. If the translatable string is not the first |
| 411 |
argument, the item needs to be of the form |
| 412 |
<literal>func:2</literal> (for the second argument). |
| 413 |
If you have a function that supports pluralized messages, |
| 414 |
the item should look like <literal>func:1,2</literal> |
| 415 |
(identifying the singular and plural message arguments). |
| 416 |
</para> |
| 417 |
</listitem> |
| 418 |
</varlistentry> |
| 419 |
</variablelist> |
| 420 |
</para> |
| 421 |
</step> |
| 422 |
|
| 423 |
<step> |
| 424 |
<para> |
| 425 |
Add a file <filename>po/LINGUAS</filename>, which will contain the list |
| 426 |
of provided translations — initially empty. |
| 427 |
</para> |
| 428 |
</step> |
| 429 |
</procedure> |
| 430 |
|
| 431 |
<para> |
| 432 |
The build system will automatically take care of building and |
| 433 |
installing the message catalogs. |
| 434 |
</para> |
| 435 |
</sect2> |
| 436 |
|
| 437 |
<sect2 id="nls-guidelines"> |
| 438 |
<title>Message-Writing Guidelines</title> |
| 439 |
|
| 440 |
<para> |
| 441 |
Here are some guidelines for writing messages that are easily |
| 442 |
translatable. |
| 443 |
|
| 444 |
<itemizedlist> |
| 445 |
<listitem> |
| 446 |
<para> |
| 447 |
Do not construct sentences at run-time, like: |
| 448 |
<programlisting> |
| 449 |
printf("Files were %s.\n", flag ? "copied" : "removed"); |
| 450 |
</programlisting> |
| 451 |
The word order within the sentence might be different in other |
| 452 |
languages. Also, even if you remember to call <function>gettext()</function> on |
| 453 |
each fragment, the fragments might not translate well separately. It's |
| 454 |
better to duplicate a little code so that each message to be |
| 455 |
translated is a coherent whole. Only numbers, file names, and |
| 456 |
such-like run-time variables should be inserted at run time into |
| 457 |
a message text. |
| 458 |
</para> |
| 459 |
</listitem> |
| 460 |
|
| 461 |
<listitem> |
| 462 |
<para> |
| 463 |
For similar reasons, this won't work: |
| 464 |
<programlisting> |
| 465 |
printf("copied %d file%s", n, n!=1 ? "s" : ""); |
| 466 |
</programlisting> |
| 467 |
because it assumes how the plural is formed. If you figured you |
| 468 |
could solve it like this: |
| 469 |
<programlisting> |
| 470 |
if (n==1) |
| 471 |
printf("copied 1 file"); |
| 472 |
else |
| 473 |
printf("copied %d files", n): |
| 474 |
</programlisting> |
| 475 |
then be disappointed. Some languages have more than two forms, |
| 476 |
with some peculiar rules. It's often best to design the message |
| 477 |
to avoid the issue altogether, for instance like this: |
| 478 |
<programlisting> |
| 479 |
printf("number of copied files: %d", n); |
| 480 |
</programlisting> |
| 481 |
</para> |
| 482 |
|
| 483 |
<para> |
| 484 |
If you really want to construct a properly pluralized message, |
| 485 |
there is support for this, but it's a bit awkward. When generating |
| 486 |
a primary or detail error message in <function>ereport()</function>, you can |
| 487 |
write something like this: |
| 488 |
<programlisting> |
| 489 |
errmsg_plural("copied %d file", |
| 490 |
"copied %d files", |
| 491 |
n, |
| 492 |
n) |
| 493 |
</programlisting> |
| 494 |
The first argument is the format string appropriate for English |
| 495 |
singular form, the second is the format string appropriate for |
| 496 |
English plural form, and the third is the integer control value |
| 497 |
that determines which plural form to use. Subsequent arguments |
| 498 |
are formatted per the format string as usual. (Normally, the |
| 499 |
pluralization control value will also be one of the values to be |
| 500 |
formatted, so it has to be written twice.) In English it only |
| 501 |
matters whether <replaceable>n</replaceable> is 1 or not 1, but in other |
| 502 |
languages there can be many different plural forms. The translator |
| 503 |
sees the two English forms as a group and has the opportunity to |
| 504 |
supply multiple substitute strings, with the appropriate one being |
| 505 |
selected based on the run-time value of <replaceable>n</replaceable>. |
| 506 |
</para> |
| 507 |
|
| 508 |
<para> |
| 509 |
If you need to pluralize a message that isn't going directly to an |
| 510 |
<function>errmsg</function> or <function>errdetail</function> report, you have to use |
| 511 |
the underlying function <function>ngettext</function>. See the gettext |
| 512 |
documentation. |
| 513 |
</para> |
| 514 |
</listitem> |
| 515 |
|
| 516 |
<listitem> |
| 517 |
<para> |
| 518 |
If you want to communicate something to the translator, such as |
| 519 |
about how a message is intended to line up with other output, |
| 520 |
precede the occurrence of the string with a comment that starts |
| 521 |
with <literal>translator</literal>, e.g.: |
| 522 |
<programlisting> |
| 523 |
/* translator: This message is not what it seems to be. */ |
| 524 |
</programlisting> |
| 525 |
These comments are copied to the message catalog files so that |
| 526 |
the translators can see them. |
| 527 |
</para> |
| 528 |
</listitem> |
| 529 |
</itemizedlist> |
| 530 |
</para> |
| 531 |
</sect2> |
| 532 |
</sect1> |
| 533 |
|
| 534 |
</chapter> |