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