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 his repository: 10 11 https://github.com/gotgit/git-po/ 12 13As a contributor for a language XX, you would fork this repository, 14prepare and/or update the translated message file po/XX.po (described 15later), and ask the l10n coordinator to pull your work. 16 17If there are multiple contributors for the same language, please first 18coordinate among yourselves and nominate the team leader for your 19language, so that the l10n coordinator only needs to interact with one 20person per language. 21 22For the list of exiting translations and language teams, see TEAMS file in 23this directory. 24 25The 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 47Maintaining the po/git.pot file 48------------------------------- 49 50(This is done by the l10n coordinator). 51 52The po/git.pot file contains a message catalog extracted from Git's 53sources. The l10n coordinator maintains it by adding new translations with 54msginit(1), or update existing ones with msgmerge(1). In order to update 55the Git sources to extract the messages from, the l10n coordinator is 56expected to pull from the main git repository at strategic point in 57history (e.g. when a major release and release candidates are tagged), 58and then run "make pot" at the top-level directory. 59 60Language contributors use this file to prepare translations for their 61language, but they are not expected to modify it. 62 63 64Initializing a XX.po file 65------------------------- 66 67(This is done by the language teams). 68 69If your language XX does not have translated message file po/XX.po yet, 70you add a translation for the first time by running: 71 72 msginit --locale=XX 73 74in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR", 75"zh_CN", etc. 76 77Then edit the automatically generated copyright info in your new XX.po 78to 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 89And change references to PACKAGE VERSION in the PO Header Entry to 90just "Git": 91 92 perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po 93 94Once you are done testing the translation (see below), commit the result 95and ask the l10n coordinator to pull from you. 96 97 98Updating a XX.po file 99--------------------- 100 101(This is done by the language teams). 102 103If you are replacing translation strings in an existing XX.po file to 104improve the translation, just edit the file. 105 106If there's an existing XX.po file for your language, but the repository 107of the l10n coordinator has newer po/git.pot file, you would need to first 108pull from the l10n coordinator (see the beginning of this document for its 109URL), and then update the existing translation by running: 110 111 msgmerge --add-location --backup=off -U XX.po git.pot 112 113in the po/ directory, where XX.po is the file you want to update. 114 115Once you are done testing the translation (see below), commit the result 116and ask the l10n coordinator to pull from you. 117 118 119Testing your changes 120-------------------- 121 122(This is done by the language teams, after creating or updating XX.po file). 123 124Before you submit your changes go back to the top-level and do: 125 126 make 127 128On systems with GNU gettext (i.e. not Solaris) this will compile your 129changed PO file with `msgfmt --check`, the --check option flags many 130common errors, e.g. missing printf format strings, or translated 131messages that deviate from the originals in whether they begin/end 132with a newline or not. 133 134 135Marking strings for translation 136------------------------------- 137 138(This is done by the core developers). 139 140Before strings can be translated they first have to be marked for 141translation. 142 143Git uses an internationalization interface that wraps the system's 144gettext library, so most of the advice in your gettext documentation 145(on GNU systems `info gettext` in a terminal) applies. 146 147General 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 175We provide wrappers for C, Shell and Perl programs. Here's how they're 176used: 177 178C: 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 219Shell: 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 252Perl: 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 264Testing marked strings 265---------------------- 266 267Even if you've correctly marked porcelain strings for translation 268something in the test suite might still depend on the US English 269version of the strings, e.g. to grep some error message or other 270output. 271 272To smoke out issues like these Git can be compiled with gettext poison 273support, at the top-level: 274 275 make GETTEXT_POISON=YesPlease 276 277That'll give you a git which emits gibberish on every call to 278gettext. It's obviously not meant to be installed, but you should run 279the test suite with it: 280 281 cd t && prove -j 9 ./t[0-9]*.sh 282 283If tests break with it you should inspect them manually and see if 284what you're translating is sane, i.e. that you're not translating 285plumbing output. 286 287If not you should replace calls to grep with test_i18ngrep, or 288test_cmp calls with test_i18ncmp. If that's not enough you can skip 289the whole test by making it depend on the C_LOCALE_OUTPUT 290prerequisite. See existing test files with this prerequisite for 291examples.