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