po/README

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