po/README

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