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