I386LINUX/util/I386LINUX/doc/postgresql/html/nls.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Native Language Support</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="Internals"
  16 HREF="internals.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="Error Message Style Guide"
  19 HREF="error-style-guide.html"><LINK
  20 REL="NEXT"
  21 TITLE="For the Programmer"
  22 HREF="nls-programmer.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="CHAPTER"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="error-style-guide.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="source.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="plhandler.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="nls-programmer.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><DIV
  91 CLASS="CHAPTER"
  92 ><H1
  93 ><A
  94 NAME="NLS"
  95 ></A
  96 >Chapter 46. Native Language Support</H1
  97 ><DIV
  98 CLASS="TOC"
  99 ><DL
 100 ><DT
 101 ><B
 102 >Table of Contents</B
 103 ></DT
 104 ><DT
 105 >46.1. <A
 106 HREF="nls.html#NLS-TRANSLATOR"
 107 >For the Translator</A
 108 ></DT
 109 ><DD
 110 ><DL
 111 ><DT
 112 >46.1.1. <A
 113 HREF="nls.html#AEN54156"
 114 >Requirements</A
 115 ></DT
 116 ><DT
 117 >46.1.2. <A
 118 HREF="nls.html#AEN54168"
 119 >Concepts</A
 120 ></DT
 121 ><DT
 122 >46.1.3. <A
 123 HREF="nls.html#AEN54186"
 124 >Creating and maintaining message catalogs</A
 125 ></DT
 126 ><DT
 127 >46.1.4. <A
 128 HREF="nls.html#AEN54220"
 129 >Editing the PO files</A
 130 ></DT
 131 ></DL
 132 ></DD
 133 ><DT
 134 >46.2. <A
 135 HREF="nls-programmer.html"
 136 >For the Programmer</A
 137 ></DT
 138 ><DD
 139 ><DL
 140 ><DT
 141 >46.2.1. <A
 142 HREF="nls-programmer.html#NLS-MECHANICS"
 143 >Mechanics</A
 144 ></DT
 145 ><DT
 146 >46.2.2. <A
 147 HREF="nls-programmer.html#NLS-GUIDELINES"
 148 >Message-writing guidelines</A
 149 ></DT
 150 ></DL
 151 ></DD
 152 ></DL
 153 ></DIV
 154 ><DIV
 155 CLASS="SECT1"
 156 ><H1
 157 CLASS="SECT1"
 158 ><A
 159 NAME="NLS-TRANSLATOR"
 160 >46.1. For the Translator</A
 161 ></H1
 162 ><P
 163 >   <SPAN
 164 CLASS="PRODUCTNAME"
 165 >PostgreSQL</SPAN
 166 >
 167    programs (server and client) can issue their messages in
 168    your favorite language -- if the messages have been translated.
 169    Creating and maintaining translated message sets needs the help of
 170    people who speak their own language well and want to contribute to
 171    the <SPAN
 172 CLASS="PRODUCTNAME"
 173 >PostgreSQL</SPAN
 174 > effort.  You do not have to be a
 175    programmer at all
 176    to do this.  This section explains how to help.
 177   </P
 178 ><DIV
 179 CLASS="SECT2"
 180 ><H2
 181 CLASS="SECT2"
 182 ><A
 183 NAME="AEN54156"
 184 >46.1.1. Requirements</A
 185 ></H2
 186 ><P
 187 >    We won't judge your language skills -- this section is about
 188     software tools.  Theoretically, you only need a text editor.  But
 189     this is only in the unlikely event that you do not want to try out
 190     your translated messages.  When you configure your source tree, be
 191     sure to use the <VAR
 192 CLASS="OPTION"
 193 >--enable-nls</VAR
 194 > option.  This will
 195     also check for the <SPAN
 196 CLASS="APPLICATION"
 197 >libintl</SPAN
 198 > library and the
 199     <TT
 200 CLASS="FILENAME"
 201 >msgfmt</TT
 202 > program, which all end users will need
 203     anyway.  To try out your work, follow the applicable portions of
 204     the installation instructions.
 205    </P
 206 ><P
 207 >    If you want to start a new translation effort or want to do a
 208     message catalog merge (described later), you will need the
 209     programs <TT
 210 CLASS="FILENAME"
 211 >xgettext</TT
 212 > and
 213     <TT
 214 CLASS="FILENAME"
 215 >msgmerge</TT
 216 >, respectively, in a GNU-compatible
 217     implementation.  Later, we will try to arrange it so that if you
 218     use a packaged source distribution, you won't need
 219     <TT
 220 CLASS="FILENAME"
 221 >xgettext</TT
 222 >.  (From CVS, you will still need
 223     it.)  <SPAN
 224 CLASS="APPLICATION"
 225 >GNU Gettext 0.10.36</SPAN
 226 > or later is currently recommended.
 227    </P
 228 ><P
 229 >    Your local gettext implementation should come with its own
 230     documentation.  Some of that is probably duplicated in what
 231     follows, but for additional details you should look there.
 232    </P
 233 ></DIV
 234 ><DIV
 235 CLASS="SECT2"
 236 ><H2
 237 CLASS="SECT2"
 238 ><A
 239 NAME="AEN54168"
 240 >46.1.2. Concepts</A
 241 ></H2
 242 ><P
 243 >    The pairs of original (English) messages and their (possibly)
 244     translated equivalents are kept in <I
 245 CLASS="FIRSTTERM"
 246 >message
 247     catalogs</I
 248 >, one for each program (although related
 249     programs can share a message catalog) and for each target
 250     language.  There are two file formats for message catalogs:  The
 251     first is the <SPAN
 252 CLASS="QUOTE"
 253 >"PO"</SPAN
 254 > file (for Portable Object), which
 255     is a plain text file with special syntax that translators edit.
 256     The second is the <SPAN
 257 CLASS="QUOTE"
 258 >"MO"</SPAN
 259 > file (for Machine Object),
 260     which is a binary file generated from the respective PO file and
 261     is used while the internationalized program is run.  Translators
 262     do not deal with MO files; in fact hardly anyone does.
 263    </P
 264 ><P
 265 >    The extension of the message catalog file is to no surprise either
 266     <TT
 267 CLASS="FILENAME"
 268 >.po</TT
 269 > or <TT
 270 CLASS="FILENAME"
 271 >.mo</TT
 272 >.  The base
 273     name is either the name of the program it accompanies, or the
 274     language the file is for, depending on the situation.  This is a
 275     bit confusing.  Examples are <TT
 276 CLASS="FILENAME"
 277 >psql.po</TT
 278 > (PO file
 279     for psql) or <TT
 280 CLASS="FILENAME"
 281 >fr.mo</TT
 282 > (MO file in French).
 283    </P
 284 ><P
 285 >    The file format of the PO files is illustrated here:
 286 </P><PRE
 287 CLASS="PROGRAMLISTING"
 288 ># comment
 289
 290 msgid "original string"
 291 msgstr "translated string"
 292
 293 msgid "more original"
 294 msgstr "another translated"
 295 "string can be broken up like this"
 296
 297 ...</PRE
 298 ><P>
 299     The msgid's are extracted from the program source.  (They need not
 300     be, but this is the most common way.)  The msgstr lines are
 301     initially empty and are filled in with useful strings by the
 302     translator.  The strings can contain C-style escape characters and
 303     can be continued across lines as illustrated.  (The next line must
 304     start at the beginning of the line.)
 305    </P
 306 ><P
 307 >    The # character introduces a comment.  If whitespace immediately
 308     follows the # character, then this is a comment maintained by the
 309     translator.  There may also be automatic comments, which have a
 310     non-whitespace character immediately following the #.  These are
 311     maintained by the various tools that operate on the PO files and
 312     are intended to aid the translator.
 313 </P><PRE
 314 CLASS="PROGRAMLISTING"
 315 >#. automatic comment
 316 #: filename.c:1023
 317 #, flags, flags</PRE
 318 ><P>
 319     The #. style comments are extracted from the source file where the
 320     message is used.  Possibly the programmer has inserted information
 321     for the translator, such as about expected alignment.  The #:
 322     comment indicates the exact location(s) where the message is used
 323     in the source.  The translator need not look at the program
 324     source, but he can if there is doubt about the correct
 325     translation.  The #, comments contain flags that describe the
 326     message in some way.  There are currently two flags:
 327     <TT
 328 CLASS="LITERAL"
 329 >fuzzy</TT
 330 > is set if the message has possibly been
 331     outdated because of changes in the program source.  The translator
 332     can then verify this and possibly remove the fuzzy flag.  Note
 333     that fuzzy messages are not made available to the end user.  The
 334     other flag is <TT
 335 CLASS="LITERAL"
 336 >c-format</TT
 337 >, which indicates that
 338     the message is a <CODE
 339 CLASS="FUNCTION"
 340 >printf</CODE
 341 >-style format
 342     template.  This means that the translation should also be a format
 343     string with the same number and type of placeholders.  There are
 344     tools that can verify this, which key off the c-format flag.
 345    </P
 346 ></DIV
 347 ><DIV
 348 CLASS="SECT2"
 349 ><H2
 350 CLASS="SECT2"
 351 ><A
 352 NAME="AEN54186"
 353 >46.1.3. Creating and maintaining message catalogs</A
 354 ></H2
 355 ><P
 356 >    OK, so how does one create a <SPAN
 357 CLASS="QUOTE"
 358 >"blank"</SPAN
 359 > message
 360     catalog?  First, go into the directory that contains the program
 361     whose messages you want to translate.  If there is a file
 362     <TT
 363 CLASS="FILENAME"
 364 >nls.mk</TT
 365 >, then this program has been prepared
 366     for translation.
 367    </P
 368 ><P
 369 >    If there are already some <TT
 370 CLASS="FILENAME"
 371 >.po</TT
 372 > files, then
 373     someone has already done some translation work.  The files are
 374     named <TT
 375 CLASS="FILENAME"
 376 ><VAR
 377 CLASS="REPLACEABLE"
 378 >language</VAR
 379 >.po</TT
 380 >,
 381     where <VAR
 382 CLASS="REPLACEABLE"
 383 >language</VAR
 384 > is the <A
 385 HREF="http://lcweb.loc.gov/standards/iso639-2/englangn.html"
 386 TARGET="_top"
 387 >ISO
 388     639-1</A
 389 > two-letter language code (in lower case), e.g.,
 390     <TT
 391 CLASS="FILENAME"
 392 >fr.po</TT
 393 > for French.  If there is really a need
 394     for more than one translation effort per language then the files
 395     may also be named
 396     <TT
 397 CLASS="FILENAME"
 398 ><VAR
 399 CLASS="REPLACEABLE"
 400 >language</VAR
 401 >_<VAR
 402 CLASS="REPLACEABLE"
 403 >region</VAR
 404 >.po</TT
 405 >
 406     where <VAR
 407 CLASS="REPLACEABLE"
 408 >region</VAR
 409 > is the <A
 410 HREF="http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html"
 411 TARGET="_top"
 412 >ISO
 413     3166-1</A
 414 > two-letter country code (in upper case), e.g.,
 415     <TT
 416 CLASS="FILENAME"
 417 >pt_BR.po</TT
 418 > for Portuguese in Brazil.  If you
 419     find the language you wanted you can just start working on that
 420     file.
 421    </P
 422 ><P
 423 >    If you need to start a new translation effort, then first run the
 424     command
 425 </P><PRE
 426 CLASS="PROGRAMLISTING"
 427 >gmake init-po</PRE
 428 ><P>
 429     This will create a file
 430     <TT
 431 CLASS="FILENAME"
 432 ><VAR
 433 CLASS="REPLACEABLE"
 434 >progname</VAR
 435 >.pot</TT
 436 >.
 437     (<TT
 438 CLASS="FILENAME"
 439 >.pot</TT
 440 > to distinguish it from PO files that
 441     are <SPAN
 442 CLASS="QUOTE"
 443 >"in production"</SPAN
 444 >. The <TT
 445 CLASS="LITERAL"
 446 >T</TT
 447 > stands for
 448     <SPAN
 449 CLASS="QUOTE"
 450 >"template"</SPAN
 451 >.)
 452     Copy this file to
 453     <TT
 454 CLASS="FILENAME"
 455 ><VAR
 456 CLASS="REPLACEABLE"
 457 >language</VAR
 458 >.po</TT
 459 > and
 460     edit it.  To make it known that the new language is available,
 461     also edit the file <TT
 462 CLASS="FILENAME"
 463 >nls.mk</TT
 464 > and add the
 465     language (or language and country) code to the line that looks like:
 466 </P><PRE
 467 CLASS="PROGRAMLISTING"
 468 >AVAIL_LANGUAGES := de fr</PRE
 469 ><P>
 470     (Other languages may appear, of course.)
 471    </P
 472 ><P
 473 >    As the underlying program or library changes, messages may be
 474     changed or added by the programmers.  In this case you do not need
 475     to start from scratch.  Instead, run the command
 476 </P><PRE
 477 CLASS="PROGRAMLISTING"
 478 >gmake update-po</PRE
 479 ><P>
 480     which will create a new blank message catalog file (the pot file
 481     you started with) and will merge it with the existing PO files.
 482     If the merge algorithm is not sure about a particular message it
 483     marks it <SPAN
 484 CLASS="QUOTE"
 485 >"fuzzy"</SPAN
 486 > as explained above.  For the case
 487     where something went really wrong, the old PO file is saved with a
 488     <TT
 489 CLASS="FILENAME"
 490 >.po.old</TT
 491 > extension.
 492    </P
 493 ></DIV
 494 ><DIV
 495 CLASS="SECT2"
 496 ><H2
 497 CLASS="SECT2"
 498 ><A
 499 NAME="AEN54220"
 500 >46.1.4. Editing the PO files</A
 501 ></H2
 502 ><P
 503 >    The PO files can be edited with a regular text editor.  The
 504     translator should only change the area between the quotes after
 505     the msgstr directive, may add comments and alter the fuzzy flag.
 506     There is (unsurprisingly) a PO mode for Emacs, which I find quite
 507     useful.
 508    </P
 509 ><P
 510 >    The PO files need not be completely filled in.  The software will
 511     automatically fall back to the original string if no translation
 512     (or an empty translation) is available.  It is no problem to
 513     submit incomplete translations for inclusions in the source tree;
 514     that gives room for other people to pick up your work.  However,
 515     you are encouraged to give priority to removing fuzzy entries
 516     after doing a merge.  Remember that fuzzy entries will not be
 517     installed; they only serve as reference what might be the right
 518     translation.
 519    </P
 520 ><P
 521 >    Here are some things to keep in mind while editing the
 522     translations:
 523     <P
 524 ></P
 525 ></P><UL
 526 ><LI
 527 ><P
 528 >       Make sure that if the original ends with a newline, the
 529        translation does, too.  Similarly for tabs, etc.
 530       </P
 531 ></LI
 532 ><LI
 533 ><P
 534 >       If the original is a <CODE
 535 CLASS="FUNCTION"
 536 >printf</CODE
 537 > format string, the translation
 538        also needs to be.  The translation also needs to have the same
 539        format specifiers in the same order.  Sometimes the natural
 540        rules of the language make this impossible or at least awkward.
 541        In that case you can modify the format specifiers like this:
 542 </P><PRE
 543 CLASS="PROGRAMLISTING"
 544 >msgstr "Die Datei %2$s hat %1$u Zeichen."</PRE
 545 ><P>
 546        Then the first placeholder will actually use the second
 547        argument from the list.  The
 548        <TT
 549 CLASS="LITERAL"
 550 ><VAR
 551 CLASS="REPLACEABLE"
 552 >digits</VAR
 553 >$</TT
 554 > needs to
 555        follow the % immediately, before any other format manipulators.
 556        (This feature really exists in the <CODE
 557 CLASS="FUNCTION"
 558 >printf</CODE
 559 >
 560        family of functions.  You may not have heard of it before because
 561        there is little use for it outside of message
 562        internationalization.)
 563       </P
 564 ></LI
 565 ><LI
 566 ><P
 567 >       If the original string contains a linguistic mistake, report
 568        that (or fix it yourself in the program source) and translate
 569        normally.  The corrected string can be merged in when the
 570        program sources have been updated.  If the original string
 571        contains a factual mistake, report that (or fix it yourself)
 572        and do not translate it.  Instead, you may mark the string with
 573        a comment in the PO file.
 574       </P
 575 ></LI
 576 ><LI
 577 ><P
 578 >       Maintain the style and tone of the original string.
 579        Specifically, messages that are not sentences (<TT
 580 CLASS="LITERAL"
 581 >cannot
 582        open file %s</TT
 583 >) should probably not start with a
 584        capital letter (if your language distinguishes letter case) or
 585        end with a period (if your language uses punctuation marks).
 586        It may help to read <A
 587 HREF="error-style-guide.html"
 588 >Section 45.3</A
 589 >.
 590       </P
 591 ></LI
 592 ><LI
 593 ><P
 594 >       If you don't know what a message means, or if it is ambiguous,
 595        ask on the developers' mailing list.  Chances are that English
 596        speaking end users might also not understand it or find it
 597        ambiguous, so it's best to improve the message.
 598       </P
 599 ></LI
 600 ></UL
 601 ><P>
 602    </P
 603 ></DIV
 604 ></DIV
 605 ></DIV
 606 ><DIV
 607 CLASS="NAVFOOTER"
 608 ><HR
 609 ALIGN="LEFT"
 610 WIDTH="100%"><TABLE
 611 SUMMARY="Footer navigation table"
 612 WIDTH="100%"
 613 BORDER="0"
 614 CELLPADDING="0"
 615 CELLSPACING="0"
 616 ><TR
 617 ><TD
 618 WIDTH="33%"
 619 ALIGN="left"
 620 VALIGN="top"
 621 ><A
 622 HREF="error-style-guide.html"
 623 ACCESSKEY="P"
 624 >Prev</A
 625 ></TD
 626 ><TD
 627 WIDTH="34%"
 628 ALIGN="center"
 629 VALIGN="top"
 630 ><A
 631 HREF="index.html"
 632 ACCESSKEY="H"
 633 >Home</A
 634 ></TD
 635 ><TD
 636 WIDTH="33%"
 637 ALIGN="right"
 638 VALIGN="top"
 639 ><A
 640 HREF="nls-programmer.html"
 641 ACCESSKEY="N"
 642 >Next</A
 643 ></TD
 644 ></TR
 645 ><TR
 646 ><TD
 647 WIDTH="33%"
 648 ALIGN="left"
 649 VALIGN="top"
 650 >Error Message Style Guide</TD
 651 ><TD
 652 WIDTH="34%"
 653 ALIGN="center"
 654 VALIGN="top"
 655 ><A
 656 HREF="internals.html"
 657 ACCESSKEY="U"
 658 >Up</A
 659 ></TD
 660 ><TD
 661 WIDTH="33%"
 662 ALIGN="right"
 663 VALIGN="top"
 664 >For the Programmer</TD
 665 ></TR
 666 ></TABLE
 667 ></DIV
 668 ></BODY
 669 ></HTML
 670 >