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