1# Core GIT Translations 2 3This directory holds the translations for the core of Git. This document 4describes how you can contribute to the effort of enhancing the language 5coverage and maintaining the translation. 6 7The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>, 8coordinates our localization effort in the l10 coordinator repository: 9 10 https://github.com/git-l10n/git-po/ 11 12The two character language translation codes are defined by ISO\_639-1, as 13stated in the gettext(1) full manual, appendix A.1, Usual Language Codes. 14 15 16## Contributing to an existing translation 17 18As a contributor for a language XX, you should first check TEAMS file in 19this directory to see whether a dedicated repository for your language XX 20exists. Fork the dedicated repository and start to work if it exists. 21 22Sometime, contributors may find that the translations of their Git 23distributions are quite different with the translations of the 24corresponding version from Git official. This is because some Git 25distributions (such as from Ubuntu, etc.) have their own l10n workflow. 26For this case, wrong translations should be reported and fixed through 27their workflows. 28 29 30## Creating a new language translation 31 32If you are the first contributor for the language XX, please fork this 33repository, prepare and/or update the translated message file "po/XX.po" 34(described later), and ask the l10n coordinator to pull your work. 35 36If there are multiple contributors for the same language, please first 37coordinate among yourselves and nominate the team leader for your 38language, so that the l10n coordinator only needs to interact with one 39person per language. 40 41 42## Core translation 43 44The core translation is the smallest set of work that must be completed 45for a new language translation. Because there are more than 5000 messages 46in the template message file "po/git.pot" that need to be translated, 47this is not a piece of cake for the contributor for a new language. 48 49The core template message file which contains a small set of messages 50will be generated in "po-core/core.pot" automatically by running a helper 51program named "git-po-helper" (described later). 52 53```shell 54git-po-helper init --core XX.po 55``` 56 57After translating the generated "po-core/XX.po", you can merge it to 58"po/XX.po" using the following commands: 59 60```shell 61msgcat po-core/XX.po po/XX.po -s -o /tmp/XX.po 62mv /tmp/XX.po po/XX.po 63git-po-helper update XX.po 64``` 65 66Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced 67translated messages and duplicate messages. 68 69 70## Translation Process Flow 71 72The overall data-flow looks like this: 73 74 +-------------------+ +------------------+ 75 | Git source code | ---(1)---> | L10n coordinator | 76 | repository | <---(4)--- | repository | 77 +-------------------+ +------------------+ 78 | ^ 79 (2) (3) 80 V | 81 +------------------+ 82 | Language Team XX | 83 +------------------+ 84 85- Translatable strings are marked in the source file. 86- L10n coordinator pulls from the source (1) 87- L10n coordinator updates the message template "po/git.pot" 88- Language team pulls from L10n coordinator (2) 89- Language team updates the message file "po/XX.po" 90- L10n coordinator pulls from Language team (3) 91- L10n coordinator asks the result to be pulled (4). 92 93 94## Maintaining the "po/git.pot" file 95 96(This is done by the l10n coordinator). 97 98The "po/git.pot" file contains a message catalog extracted from Git's 99sources. The l10n coordinator maintains it by adding new translations with 100msginit(1), or update existing ones with msgmerge(1). In order to update 101the Git sources to extract the messages from, the l10n coordinator is 102expected to pull from the main git repository at strategic point in 103history (e.g. when a major release and release candidates are tagged), 104and then run "make pot" at the top-level directory. 105 106Language contributors use this file to prepare translations for their 107language, but they are not expected to modify it. 108 109 110## Initializing a "XX.po" file 111 112(This is done by the language teams). 113 114If your language XX does not have translated message file "po/XX.po" yet, 115you add a translation for the first time by running: 116 117```shell 118msginit --locale=XX 119``` 120 121in the "po/" directory, where XX is the locale, e.g. "de", "is", "pt\_BR", 122"zh\_CN", etc. 123 124Then edit the automatically generated copyright info in your new "XX.po" 125to be correct, e.g. for Icelandic: 126 127```diff 128@@ -1,6 +1,6 @@ 129-# Icelandic translations for PACKAGE package. 130-# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER 131-# This file is distributed under the same license as the PACKAGE package. 132+# Icelandic translations for Git. 133+# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com> 134+# This file is distributed under the same license as the Git package. 135 # Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010. 136``` 137 138And change references to PACKAGE VERSION in the PO Header Entry to 139just "Git": 140 141```shell 142perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po 143``` 144 145Once you are done testing the translation (see below), commit the result 146and ask the l10n coordinator to pull from you. 147 148 149## Updating a "XX.po" file 150 151(This is done by the language teams). 152 153If you are replacing translation strings in an existing "XX.po" file to 154improve the translation, just edit the file. 155 156If there's an existing "XX.po" file for your language, but the repository 157of the l10n coordinator has newer "po/git.pot" file, you would need to first 158pull from the l10n coordinator (see the beginning of this document for its 159URL), and then update the existing translation by running: 160 161```shell 162msgmerge --add-location --backup=off -U XX.po git.pot 163``` 164 165in the "po/" directory, where "XX.po" is the file you want to update. 166 167Once you are done testing the translation (see below), commit the result 168and ask the l10n coordinator to pull from you. 169 170 171## Fuzzy translation 172 173Fuzzy translation is a translation marked by comment "fuzzy" to let you 174know that the translation is out of date because the "msgid" has been 175changed. A fuzzy translation will be ignored when compiling using "msgfmt". 176Fuzzy translation can be marked by hands, but for most cases they are 177marked automatically when running "msgmerge" to update your "XX.po" file. 178 179After fixing the corresponding translation, you must remove the "fuzzy" 180tag in the comment. 181 182 183## Testing your changes 184 185(This is done by the language teams, after creating or updating "XX.po" file). 186 187Before you submit your changes go back to the top-level and do: 188 189```shell 190make 191``` 192 193On systems with GNU gettext (i.e. not Solaris) this will compile your 194changed PO file with `msgfmt --check`, the --check option flags many 195common errors, e.g. missing printf format strings, or translated 196messages that deviate from the originals in whether they begin/end 197with a newline or not. 198 199 200## Marking strings for translation 201 202(This is done by the core developers). 203 204Before strings can be translated they first have to be marked for 205translation. 206 207Git uses an internationalization interface that wraps the system's 208gettext library, so most of the advice in your gettext documentation 209(on GNU systems `info gettext` in a terminal) applies. 210 211General advice: 212 213- Don't mark everything for translation, only strings which will be 214 read by humans (the porcelain interface) should be translated. 215 216 The output from Git's plumbing utilities will primarily be read by 217 programs and would break scripts under non-C locales if it was 218 translated. Plumbing strings should not be translated, since 219 they're part of Git's API. 220 221- Adjust the strings so that they're easy to translate. Most of the 222 advice in `info '(gettext)Preparing Strings'` applies here. 223 224- If something is unclear or ambiguous you can use a "TRANSLATORS" 225 comment to tell the translators what to make of it. These will be 226 extracted by xgettext(1) and put in the "po/\*.po" files, e.g. from 227 git-am.sh: 228 229 ```shell 230 # TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a] 231 # in your translation. The program will only accept English 232 # input at this point. 233 gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all " 234 ``` 235 236 Or in C, from builtin/revert.c: 237 238 ```c 239 /* TRANSLATORS: %s will be "revert" or "cherry-pick" */ 240 die(_("%s: Unable to write new index file"), action_name(opts)); 241 ``` 242 243We provide wrappers for C, Shell and Perl programs. Here's how they're 244used: 245 246 247### C 248 249Include builtin.h at the top, it'll pull in gettext.h, which 250defines the gettext interface. Consult with the list if you need to 251use gettext.h directly. 252 253The C interface is a subset of the normal GNU gettext 254interface. We currently export these functions: 255 256- \_() 257 258 Mark and translate a string. E.g.: 259 260 ```c 261 printf(_("HEAD is now at %s"), hex); 262 ``` 263 264- Q\_() 265 266 Mark and translate a plural string. E.g.: 267 268 ```c 269 printf(Q_("%d commit", "%d commits", number_of_commits)); 270 ``` 271 272 This is just a wrapper for the ngettext() function. 273 274- N\_() 275 276 A no-op pass-through macro for marking strings inside static 277 initializations, e.g.: 278 279 ```c 280 static const char *reset_type_names[] = { 281 N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL 282 }; 283 ``` 284 285 And then, later: 286 287 ```c 288 die(_("%s reset is not allowed in a bare repository"), 289 _(reset_type_names[reset_type])); 290 ``` 291 292 Here `_()` couldn't have statically determined what the translation 293 string will be, but since it was already marked for translation 294 with `N_()` the look-up in the message catalog will succeed. 295 296 297### Shell 298 299The Git gettext shell interface is just a wrapper for 300gettext.sh. Import it right after git-sh-setup like this: 301 302```shell 303. git-sh-setup 304. git-sh-i18n 305``` 306 307And then use the `gettext` or `eval_gettext` functions: 308 309```shell 310# For constant interface messages: 311gettext "A message for the user"; echo 312 313# To interpolate variables: 314details="oh noes" 315eval_gettext "An error occurred: \$details"; echo 316``` 317 318In addition we have wrappers for messages that end with a trailing 319newline. I.e. you could write the above as: 320 321```shell 322# For constant interface messages: 323gettextln "A message for the user" 324 325# To interpolate variables: 326details="oh noes" 327eval_gettextln "An error occurred: \$details" 328``` 329 330More documentation about the interface is available in the GNU info 331page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell 332command to be translated) for examples is also useful: 333 334```shell 335git log --reverse -p --grep=i18n git-am.sh 336``` 337 338 339### Perl 340 341The Git::I18N module provides a limited subset of the 342Locale::Messages functionality, e.g.: 343 344```perl 345use Git::I18N; 346print __("Welcome to Git!\n"); 347printf __("The following error occurred: %s\n"), $error; 348``` 349 350Run `perldoc perl/Git/I18N.pm` for more info. 351 352 353## Testing marked strings 354 355Git's tests are run under `LANG=C LC_ALL=C`. So the tests do not need be 356changed to account for translations as they're added. 357 358 359## PO helper 360 361To make the maintenance of "XX.po" easier, the l10n coordinator and l10n 362team leaders can use a helper program named "git-po-helper". It is a 363wrapper to gettext suite, specifically written for the purpose of Git 364l10n workflow. 365 366To build and install the helper program from source, see 367[git-po-helper/README][]. 368 369Usage for git-po-helper: 370 371- To start a new language translation: 372 373 ```shell 374 git-po-helper init XX.po 375 ``` 376 377- To update your "XX.po" file: 378 379 ```shell 380 git-po-helper update XX.po 381 ``` 382 383- To check commit log and syntax of "XX.po": 384 385 ```shell 386 git-po-helper check-po XX.po 387 git-po-helper check-commits 388 ``` 389 390Run "git-po-helper" without arguments to show usage. 391 392 393## Conventions 394 395There are some conventions that l10n contributors must follow: 396 397- The subject of each l10n commit should be prefixed with "l10n: ". 398 399- Do not use non-ASCII characters in the subject of a commit. 400 401- The length of commit subject (first line of the commit log) should 402 be less than 50 characters, and the length of other lines of the 403 commit log should be no more than 72 characters. 404 405- Add "Signed-off-by" trailer to your commit log, like other commits 406 in Git. You can automatically add the trailer by committing with 407 the following command: 408 409 ```shell 410 git commit -s 411 ``` 412 413- Check syntax with "msgfmt" or the following command before creating 414 your commit: 415 416 ```shell 417 git-po-helper check-po <XX.po> 418 ``` 419 420- Squash trivial commits to make history clear. 421 422- DO NOT edit files outside "po/" directory. 423 424- Other subsystems ("git-gui", "gitk", and Git itself) have their 425 own workflow. See [Documentation/SubmittingPatches][] for 426 instructions on how to contribute patches to these subsystems. 427 428 429To contribute for a new l10n language, contributor should follow 430additional conventions: 431 432- Initialize proper filename of the "XX.po" file conforming to 433 iso-639 and iso-3166. 434 435- Must complete a minimal translation based on the "po-core/core.pot" 436 template. Using the following command to initialize the minimal 437 "po-core/XX.po" file: 438 439 ```shell 440 git-po-helper init --core <your-language> 441 ``` 442 443- Add a new entry in the "po/TEAMS" file with proper format, and check 444 the syntax of "po/TEAMS" by running the following command: 445 446 ```shell 447 git-po-helper team --check 448 ``` 449 450 451[git-po-helper/README]: https://github.com/git-l10n/git-po-helper#readme 452[Documentation/SubmittingPatches]: Documentation/SubmittingPatches 453