po / READMEon commit Merge branch 'tb/test-t9020-no-which' (15f1f9a)
   1Core GIT Translations
   2=====================
   3
   4This directory holds the translations for the core of Git. This document
   5describes how you can contribute to the effort of enhancing the language
   6coverage and maintaining the translation.
   7
   8The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,
   9coordinates our localization effort in the l10 coordinator repository:
  10
  11        https://github.com/git-l10n/git-po/
  12
  13As a contributor for a language XX, you should first check TEAMS file in
  14this directory to see whether a dedicated repository for your language XX
  15exists. Fork the dedicated repository and start to work if it exists.
  16
  17If you are the first contributor for the language XX, please fork this
  18repository, prepare and/or update the translated message file po/XX.po
  19(described later), and ask the l10n coordinator to pull your work.
  20
  21If there are multiple contributors for the same language, please first
  22coordinate among yourselves and nominate the team leader for your
  23language, so that the l10n coordinator only needs to interact with one
  24person per language.
  25
  26The overall data-flow looks like this:
  27
  28    +-------------------+            +------------------+
  29    | Git source code   | ---(1)---> | L10n coordinator |
  30    | repository        | <---(4)--- | repository       |
  31    +-------------------+            +------------------+
  32                                          |      ^
  33                                         (2)    (3)
  34                                          V      |
  35                                     +------------------+
  36                                     | Language Team XX |
  37                                     +------------------+
  38
  39 * Translatable strings are marked in the source file.
  40 * L10n coordinator pulls from the source (1)
  41 * L10n coordinator updates the message template po/git.pot
  42 * Language team pulls from L10n coordinator (2)
  43 * Language team updates the message file po/XX.po
  44 * L10n coordinator pulls from Language team (3)
  45 * L10n coordinator asks the result to be pulled (4).
  46
  47
  48Maintaining the po/git.pot file
  49-------------------------------
  50
  51(This is done by the l10n coordinator).
  52
  53The po/git.pot file contains a message catalog extracted from Git's
  54sources. The l10n coordinator maintains it by adding new translations with
  55msginit(1), or update existing ones with msgmerge(1).  In order to update
  56the Git sources to extract the messages from, the l10n coordinator is
  57expected to pull from the main git repository at strategic point in
  58history (e.g. when a major release and release candidates are tagged),
  59and then run "make pot" at the top-level directory.
  60
  61Language contributors use this file to prepare translations for their
  62language, but they are not expected to modify it.
  63
  64
  65Initializing a XX.po file
  66-------------------------
  67
  68(This is done by the language teams).
  69
  70If your language XX does not have translated message file po/XX.po yet,
  71you add a translation for the first time by running:
  72
  73    msginit --locale=XX
  74
  75in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR",
  76"zh_CN", etc.
  77
  78Then edit the automatically generated copyright info in your new XX.po
  79to be correct, e.g. for Icelandic:
  80
  81    @@ -1,6 +1,6 @@
  82    -# Icelandic translations for PACKAGE package.
  83    -# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER
  84    -# This file is distributed under the same license as the PACKAGE package.
  85    +# Icelandic translations for Git.
  86    +# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
  87    +# This file is distributed under the same license as the Git package.
  88     # Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.
  89
  90And change references to PACKAGE VERSION in the PO Header Entry to
  91just "Git":
  92
  93    perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
  94
  95Once you are done testing the translation (see below), commit the result
  96and ask the l10n coordinator to pull from you.
  97
  98
  99Updating a XX.po file
 100---------------------
 101
 102(This is done by the language teams).
 103
 104If you are replacing translation strings in an existing XX.po file to
 105improve the translation, just edit the file.
 106
 107If there's an existing XX.po file for your language, but the repository
 108of the l10n coordinator has newer po/git.pot file, you would need to first
 109pull from the l10n coordinator (see the beginning of this document for its
 110URL), and then update the existing translation by running:
 111
 112    msgmerge --add-location --backup=off -U XX.po git.pot
 113
 114in the po/ directory, where XX.po is the file you want to update.
 115
 116Once you are done testing the translation (see below), commit the result
 117and ask the l10n coordinator to pull from you.
 118
 119
 120Testing your changes
 121--------------------
 122
 123(This is done by the language teams, after creating or updating XX.po file).
 124
 125Before you submit your changes go back to the top-level and do:
 126
 127    make
 128
 129On systems with GNU gettext (i.e. not Solaris) this will compile your
 130changed PO file with `msgfmt --check`, the --check option flags many
 131common errors, e.g. missing printf format strings, or translated
 132messages that deviate from the originals in whether they begin/end
 133with a newline or not.
 134
 135
 136Marking strings for translation
 137-------------------------------
 138
 139(This is done by the core developers).
 140
 141Before strings can be translated they first have to be marked for
 142translation.
 143
 144Git uses an internationalization interface that wraps the system's
 145gettext library, so most of the advice in your gettext documentation
 146(on GNU systems `info gettext` in a terminal) applies.
 147
 148General advice:
 149
 150 - Don't mark everything for translation, only strings which will be
 151   read by humans (the porcelain interface) should be translated.
 152
 153   The output from Git's plumbing utilities will primarily be read by
 154   programs and would break scripts under non-C locales if it was
 155   translated. Plumbing strings should not be translated, since
 156   they're part of Git's API.
 157
 158 - Adjust the strings so that they're easy to translate. Most of the
 159   advice in `info '(gettext)Preparing Strings'` applies here.
 160
 161 - If something is unclear or ambiguous you can use a "TRANSLATORS"
 162   comment to tell the translators what to make of it. These will be
 163   extracted by xgettext(1) and put in the po/*.po files, e.g. from
 164   git-am.sh:
 165
 166       # TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a]
 167       # in your translation. The program will only accept English
 168       # input at this point.
 169       gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all "
 170
 171   Or in C, from builtin/revert.c:
 172
 173       /* TRANSLATORS: %s will be "revert" or "cherry-pick" */
 174       die(_("%s: Unable to write new index file"), action_name(opts));
 175
 176We provide wrappers for C, Shell and Perl programs. Here's how they're
 177used:
 178
 179C:
 180
 181 - Include builtin.h at the top, it'll pull in gettext.h, which
 182   defines the gettext interface. Consult with the list if you need to
 183   use gettext.h directly.
 184
 185 - The C interface is a subset of the normal GNU gettext
 186   interface. We currently export these functions:
 187
 188   - _()
 189
 190    Mark and translate a string. E.g.:
 191
 192        printf(_("HEAD is now at %s"), hex);
 193
 194   - Q_()
 195
 196    Mark and translate a plural string. E.g.:
 197
 198        printf(Q_("%d commit", "%d commits", number_of_commits));
 199
 200    This is just a wrapper for the ngettext() function.
 201
 202   - N_()
 203
 204    A no-op pass-through macro for marking strings inside static
 205    initializations, e.g.:
 206
 207        static const char *reset_type_names[] = {
 208            N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL
 209        };
 210
 211    And then, later:
 212
 213        die(_("%s reset is not allowed in a bare repository"),
 214               _(reset_type_names[reset_type]));
 215
 216    Here _() couldn't have statically determined what the translation
 217    string will be, but since it was already marked for translation
 218    with N_() the look-up in the message catalog will succeed.
 219
 220Shell:
 221
 222 - The Git gettext shell interface is just a wrapper for
 223   gettext.sh. Import it right after git-sh-setup like this:
 224
 225       . git-sh-setup
 226       . git-sh-i18n
 227
 228   And then use the gettext or eval_gettext functions:
 229
 230       # For constant interface messages:
 231       gettext "A message for the user"; echo
 232
 233       # To interpolate variables:
 234       details="oh noes"
 235       eval_gettext "An error occured: \$details"; echo
 236
 237   In addition we have wrappers for messages that end with a trailing
 238   newline. I.e. you could write the above as:
 239
 240       # For constant interface messages:
 241       gettextln "A message for the user"
 242
 243       # To interpolate variables:
 244       details="oh noes"
 245       eval_gettextln "An error occured: \$details"
 246
 247   More documentation about the interface is available in the GNU info
 248   page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell
 249   command to be translated) for examples is also useful:
 250
 251       git log --reverse -p --grep=i18n git-am.sh
 252
 253Perl:
 254
 255 - The Git::I18N module provides a limited subset of the
 256   Locale::Messages functionality, e.g.:
 257
 258       use Git::I18N;
 259       print __("Welcome to Git!\n");
 260       printf __("The following error occured: %s\n"), $error;
 261
 262   Run `perldoc perl/Git/I18N.pm` for more info.
 263
 264
 265Testing marked strings
 266----------------------
 267
 268Even if you've correctly marked porcelain strings for translation
 269something in the test suite might still depend on the US English
 270version of the strings, e.g. to grep some error message or other
 271output.
 272
 273To smoke out issues like these Git can be compiled with gettext poison
 274support, at the top-level:
 275
 276    make GETTEXT_POISON=YesPlease
 277
 278That'll give you a git which emits gibberish on every call to
 279gettext. It's obviously not meant to be installed, but you should run
 280the test suite with it:
 281
 282    cd t && prove -j 9 ./t[0-9]*.sh
 283
 284If tests break with it you should inspect them manually and see if
 285what you're translating is sane, i.e. that you're not translating
 286plumbing output.
 287
 288If not you should replace calls to grep with test_i18ngrep, or
 289test_cmp calls with test_i18ncmp. If that's not enough you can skip
 290the whole test by making it depend on the C_LOCALE_OUTPUT
 291prerequisite. See existing test files with this prerequisite for
 292examples.