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