begriffs open source - ai-pg/blob - full-docs/txt/nls-translator.txt

   1
   2 56.1. For the Translator #
   3
   4    56.1.1. Requirements
   5    56.1.2. Concepts
   6    56.1.3. Creating and Maintaining Message Catalogs
   7    56.1.4. Editing the PO Files
   8
   9    PostgreSQL programs (server and client) can issue their messages in
  10    your favorite language — if the messages have been translated. Creating
  11    and maintaining translated message sets needs the help of people who
  12    speak their own language well and want to contribute to the PostgreSQL
  13    effort. You do not have to be a programmer at all to do this. This
  14    section explains how to help.
  15
  16 56.1.1. Requirements #
  17
  18    We won't judge your language skills — this section is about software
  19    tools. Theoretically, you only need a text editor. But this is only in
  20    the unlikely event that you do not want to try out your translated
  21    messages. When you configure your source tree, be sure to use the
  22    --enable-nls option. This will also check for the libintl library and
  23    the msgfmt program, which all end users will need anyway. To try out
  24    your work, follow the applicable portions of the installation
  25    instructions.
  26
  27    If you want to start a new translation effort or want to do a message
  28    catalog merge (described later), you will need the programs xgettext
  29    and msgmerge, respectively, in a GNU-compatible implementation. Later,
  30    we will try to arrange it so that if you use a packaged source
  31    distribution, you won't need xgettext. (If working from Git, you will
  32    still need it.) GNU Gettext 0.10.36 or later is currently recommended.
  33
  34    Your local gettext implementation should come with its own
  35    documentation. Some of that is probably duplicated in what follows, but
  36    for additional details you should look there.
  37
  38 56.1.2. Concepts #
  39
  40    The pairs of original (English) messages and their (possibly)
  41    translated equivalents are kept in message catalogs, one for each
  42    program (although related programs can share a message catalog) and for
  43    each target language. There are two file formats for message catalogs:
  44    The first is the “PO” file (for Portable Object), which is a plain text
  45    file with special syntax that translators edit. The second is the “MO”
  46    file (for Machine Object), which is a binary file generated from the
  47    respective PO file and is used while the internationalized program is
  48    run. Translators do not deal with MO files; in fact hardly anyone does.
  49
  50    The extension of the message catalog file is to no surprise either .po
  51    or .mo. The base name is either the name of the program it accompanies,
  52    or the language the file is for, depending on the situation. This is a
  53    bit confusing. Examples are psql.po (PO file for psql) or fr.mo (MO
  54    file in French).
  55
  56    The file format of the PO files is illustrated here:
  57 # comment
  58
  59 msgid "original string"
  60 msgstr "translated string"
  61
  62 msgid "more original"
  63 msgstr "another translated"
  64 "string can be broken up like this"
  65
  66 ...
  67
  68    The msgid lines are extracted from the program source. (They need not
  69    be, but this is the most common way.) The msgstr lines are initially
  70    empty and are filled in with useful strings by the translator. The
  71    strings can contain C-style escape characters and can be continued
  72    across lines as illustrated. (The next line must start at the beginning
  73    of the line.)
  74
  75    The # character introduces a comment. If whitespace immediately follows
  76    the # character, then this is a comment maintained by the translator.
  77    There can also be automatic comments, which have a non-whitespace
  78    character immediately following the #. These are maintained by the
  79    various tools that operate on the PO files and are intended to aid the
  80    translator.
  81 #. automatic comment
  82 #: filename.c:1023
  83 #, flags, flags
  84
  85    The #. style comments are extracted from the source file where the
  86    message is used. Possibly the programmer has inserted information for
  87    the translator, such as about expected alignment. The #: comments
  88    indicate the exact locations where the message is used in the source.
  89    The translator need not look at the program source, but can if there is
  90    doubt about the correct translation. The #, comments contain flags that
  91    describe the message in some way. There are currently two flags: fuzzy
  92    is set if the message has possibly been outdated because of changes in
  93    the program source. The translator can then verify this and possibly
  94    remove the fuzzy flag. Note that fuzzy messages are not made available
  95    to the end user. The other flag is c-format, which indicates that the
  96    message is a printf-style format template. This means that the
  97    translation should also be a format string with the same number and
  98    type of placeholders. There are tools that can verify this, which key
  99    off the c-format flag.
 100
 101 56.1.3. Creating and Maintaining Message Catalogs #
 102
 103    OK, so how does one create a “blank” message catalog? First, go into
 104    the directory that contains the program whose messages you want to
 105    translate. If there is a file nls.mk, then this program has been
 106    prepared for translation.
 107
 108    If there are already some .po files, then someone has already done some
 109    translation work. The files are named language.po, where language is
 110    the ISO 639-1 two-letter language code (in lower case), e.g., fr.po for
 111    French. If there is really a need for more than one translation effort
 112    per language then the files can also be named language_region.po where
 113    region is the ISO 3166-1 two-letter country code (in upper case), e.g.,
 114    pt_BR.po for Portuguese in Brazil. If you find the language you wanted
 115    you can just start working on that file.
 116
 117    If you need to start a new translation effort, then first run the
 118    command:
 119 make init-po
 120
 121    This will create a file progname.pot. (.pot to distinguish it from PO
 122    files that are “in production”. The T stands for “template”.) Copy this
 123    file to language.po and edit it. To make it known that the new language
 124    is available, also edit the file po/LINGUAS and add the language (or
 125    language and country) code next to languages already listed, like:
 126 de fr
 127
 128    (Other languages can appear, of course.)
 129
 130    As the underlying program or library changes, messages might be changed
 131    or added by the programmers. In this case you do not need to start from
 132    scratch. Instead, run the command:
 133 make update-po
 134
 135    which will create a new blank message catalog file (the pot file you
 136    started with) and will merge it with the existing PO files. If the
 137    merge algorithm is not sure about a particular message it marks it
 138    “fuzzy” as explained above. The new PO file is saved with a .po.new
 139    extension.
 140
 141 56.1.4. Editing the PO Files #
 142
 143    The PO files can be edited with a regular text editor. There are also
 144    several specialized editors for PO files which can help the process
 145    with translation-specific features. There is (unsurprisingly) a PO mode
 146    for Emacs, which can be quite useful.
 147
 148    The translator should only change the area between the quotes after the
 149    msgstr directive, add comments, and alter the fuzzy flag.
 150
 151    The PO files need not be completely filled in. The software will
 152    automatically fall back to the original string if no translation (or an
 153    empty translation) is available. It is no problem to submit incomplete
 154    translations for inclusions in the source tree; that gives room for
 155    other people to pick up your work. However, you are encouraged to give
 156    priority to removing fuzzy entries after doing a merge. Remember that
 157    fuzzy entries will not be installed; they only serve as reference for
 158    what might be the right translation.
 159
 160    Here are some things to keep in mind while editing the translations:
 161      * Make sure that if the original ends with a newline, the translation
 162        does, too. Similarly for tabs, etc.
 163      * If the original is a printf format string, the translation also
 164        needs to be. The translation also needs to have the same format
 165        specifiers in the same order. Sometimes the natural rules of the
 166        language make this impossible or at least awkward. In that case you
 167        can modify the format specifiers like this:
 168 msgstr "Die Datei %2$s hat %1$u Zeichen."
 169
 170        Then the first placeholder will actually use the second argument
 171        from the list. The digits$ needs to follow the % immediately,
 172        before any other format manipulators. (This feature really exists
 173        in the printf family of functions. You might not have heard of it
 174        before because there is little use for it outside of message
 175        internationalization.)
 176      * If the original string contains a linguistic mistake, report that
 177        (or fix it yourself in the program source) and translate normally.
 178        The corrected string can be merged in when the program sources have
 179        been updated. If the original string contains a factual mistake,
 180        report that (or fix it yourself) and do not translate it. Instead,
 181        you can mark the string with a comment in the PO file.
 182      * Maintain the style and tone of the original string. Specifically,
 183        messages that are not sentences (cannot open file %s) should
 184        probably not start with a capital letter (if your language
 185        distinguishes letter case) or end with a period (if your language
 186        uses punctuation marks). It might help to read Section 55.3.
 187      * If you don't know what a message means, or if it is ambiguous, ask
 188        on the developers' mailing list. Chances are that English speaking
 189        end users might also not understand it or find it ambiguous, so
 190        it's best to improve the message.