cb92e28384 · matheusbsbs/matheus-bagliano

@@ -1,5 +1,4 @@

1 -Core GIT Translations

2 -=====================

1 +# Core GIT Translations

2

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

@@ -8,14 +7,14 @@ coverage and maintaining the translation.

7 The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,

8 coordinates our localization effort in the l10 coordinator repository:

9

11 - https://github.com/git-l10n/git-po/

10 + https://github.com/git-l10n/git-po/

11

13 -The two character language translation codes are defined by ISO_639-1, as

12 +The two character language translation codes are defined by ISO\_639-1, as

13 stated in the gettext(1) full manual, appendix A.1, Usual Language Codes.

14

15

17 -Contributing to an existing translation

18 ----------------------------------------

16 +## Contributing to an existing translation

17 +

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.

@@ -28,10 +27,10 @@ For this case, wrong translations should be reported and fixed through

27 their workflows.

28

29

31 -Creating a new language translation

32 ------------------------------------

30 +## Creating a new language translation

31 +

32 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

33 +repository, prepare and/or update the translated message file "po/XX.po"

34 (described later), and ask the l10n coordinator to pull your work.

35

36 If there are multiple contributors for the same language, please first

@@ -40,8 +39,8 @@ language, so that the l10n coordinator only needs to interact with one

39 person per language.

40

41

43 -Core translation

44 -----------------

42 +## Core translation

43 +

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,

@@ -51,21 +50,25 @@ 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

54 - git-po-helper init --core XX.po

53 +```shell

54 +git-po-helper init --core XX.po

55 +```

56

57 After translating the generated "po-core/XX.po", you can merge it to

58 "po/XX.po" using the following commands:

59

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

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 +```

65

66 Edit "po/XX.po" by hand to fix "fuzzy" messages, which may have misplaced

67 translated messages and duplicate messages.

68

69

67 -Translation Process Flow

68 -------------------------

70 +## Translation Process Flow

71 +

72 The overall data-flow looks like this:

73

74 +-------------------+ +------------------+

@@ -79,21 +82,20 @@ The overall data-flow looks like this:

82 | Language Team XX |

83 +------------------+

84

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).

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

91 -Maintaining the po/git.pot file

92 --------------------------------

94 +## Maintaining the "po/git.pot" file

95

96 (This is done by the l10n coordinator).

97

96 -The po/git.pot file contains a message catalog extracted from Git's

98 +The "po/git.pot" file contains a message catalog extracted from Git's

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

@@ -105,62 +107,68 @@ Language contributors use this file to prepare translations for their

107 language, but they are not expected to modify it.

108

109

108 -Initializing a XX.po file

109 --------------------------

110 +## Initializing a "XX.po" file

111

112 (This is done by the language teams).

113

113 -If your language XX does not have translated message file po/XX.po yet,

114 +If your language XX does not have translated message file "po/XX.po" yet,

115 you add a translation for the first time by running:

116

116 - msginit --locale=XX

117 +```shell

118 +msginit --locale=XX

119 +```

120

118 -in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR",

119 -"zh_CN", etc.

121 +in the "po/" directory, where XX is the locale, e.g. "de", "is", "pt\_BR",

122 +"zh\_CN", etc.

123

121 -Then edit the automatically generated copyright info in your new XX.po

124 +Then edit the automatically generated copyright info in your new "XX.po"

125 to be correct, e.g. for Icelandic:

126

124 - @@ -1,6 +1,6 @@

125 - -# Icelandic translations for PACKAGE package.

127 - -# This file is distributed under the same license as the PACKAGE package.

128 - +# Icelandic translations for Git.

130 - +# This file is distributed under the same license as the Git package.

131 - # Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.

127 +```diff

128 +@@ -1,6 +1,6 @@

129 +-# Icelandic translations for PACKAGE package.

131 +-# This file is distributed under the same license as the PACKAGE package.

132 ++# Icelandic translations for Git.

134 ++# This file is distributed under the same license as the Git package.

135 + # Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.

136 +```

137

138 And change references to PACKAGE VERSION in the PO Header Entry to

139 just "Git":

140

136 - perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po

141 +```shell

142 +perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po

143 +```

144

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

142 -Updating a XX.po file

143 ----------------------

149 +## Updating a "XX.po" file

150

151 (This is done by the language teams).

152

147 -If you are replacing translation strings in an existing XX.po file to

153 +If you are replacing translation strings in an existing "XX.po" file to

154 improve the translation, just edit the file.

155

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

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

158 pull from the l10n coordinator (see the beginning of this document for its

159 URL), and then update the existing translation by running:

160

155 - msgmerge --add-location --backup=off -U XX.po git.pot

161 +```shell

162 +msgmerge --add-location --backup=off -U XX.po git.pot

163 +```

164

157 -in the po/ directory, where XX.po is the file you want to update.

165 +in the "po/" directory, where "XX.po" is the file you want to update.

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

162 -Fuzzy translation

163 ------------------

170 +

171 +## Fuzzy translation

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

@@ -172,14 +180,15 @@ After fixing the corresponding translation, you must remove the "fuzzy"

180 tag in the comment.

181

182

175 -Testing your changes

176 ---------------------

183 +## Testing your changes

184

178 -(This is done by the language teams, after creating or updating XX.po file).

185 +(This is done by the language teams, after creating or updating "XX.po" file).

186

187 Before you submit your changes go back to the top-level and do:

188

182 - make

189 +```shell

190 +make

191 +```

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

@@ -188,8 +197,7 @@ messages that deviate from the originals in whether they begin/end

197 with a newline or not.

198

199

191 -Marking strings for translation

192 --------------------------------

200 +## Marking strings for translation

201

202 (This is done by the core developers).

203

@@ -202,132 +210,155 @@ gettext library, so most of the advice in your gettext documentation

210

211 General advice:

212

205 - - Don't mark everything for translation, only strings which will be

206 - read by humans (the porcelain interface) should be translated.

213 +- Don't mark everything for translation, only strings which will be

214 + read by humans (the porcelain interface) should be translated.

215

208 - The output from Git's plumbing utilities will primarily be read by

209 - programs and would break scripts under non-C locales if it was

210 - translated. Plumbing strings should not be translated, since

211 - they're part of Git's API.

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

213 - - Adjust the strings so that they're easy to translate. Most of the

214 - advice in `info '(gettext)Preparing Strings'` applies here.

221 +- Adjust the strings so that they're easy to translate. Most of the

222 + advice in `info '(gettext)Preparing Strings'` applies here.

223

216 - - If something is unclear or ambiguous you can use a "TRANSLATORS"

217 - comment to tell the translators what to make of it. These will be

218 - extracted by xgettext(1) and put in the po/*.po files, e.g. from

219 - git-am.sh:

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

221 - # TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a]

222 - # in your translation. The program will only accept English

223 - # input at this point.

224 - gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all "

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

226 - Or in C, from builtin/revert.c:

236 + Or in C, from builtin/revert.c:

237

228 - /* TRANSLATORS: %s will be "revert" or "cherry-pick" */

229 - die(_("%s: Unable to write new index file"), action_name(opts));

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

243 We provide wrappers for C, Shell and Perl programs. Here's how they're

244 used:

245

234 -C:

246

236 - - Include builtin.h at the top, it'll pull in gettext.h, which

237 - defines the gettext interface. Consult with the list if you need to

238 - use gettext.h directly.

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 +- \_()

257

240 - - The C interface is a subset of the normal GNU gettext

241 - interface. We currently export these functions:

258 + Mark and translate a string. E.g.:

259

243 - - _()

260 + ```c

261 + printf(_("HEAD is now at %s"), hex);

262 + ```

263

245 - Mark and translate a string. E.g.:

264 +- Q\_()

265

247 - printf(_("HEAD is now at %s"), hex);

266 + Mark and translate a plural string. E.g.:

267

249 - - Q_()

268 + ```c

269 + printf(Q_("%d commit", "%d commits", number_of_commits));

270 + ```

271

251 - Mark and translate a plural string. E.g.:

272 + This is just a wrapper for the ngettext() function.

273

253 - printf(Q_("%d commit", "%d commits", number_of_commits));

274 +- N\_()

275

255 - This is just a wrapper for the ngettext() function.

276 + A no-op pass-through macro for marking strings inside static

277 + initializations, e.g.:

278

257 - - N_()

279 + ```c

280 + static const char *reset_type_names[] = {

281 + N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL

282 + };

283 + ```

284

259 - A no-op pass-through macro for marking strings inside static

260 - initializations, e.g.:

285 + And then, later:

286

262 - static const char *reset_type_names[] = {

263 - N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL

264 - };

287 + ```c

288 + die(_("%s reset is not allowed in a bare repository"),

289 + _(reset_type_names[reset_type]));

290 + ```

291

266 - And then, later:

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

268 - die(_("%s reset is not allowed in a bare repository"),

269 - _(reset_type_names[reset_type]));

296

271 - Here _() couldn't have statically determined what the translation

272 - string will be, but since it was already marked for translation

273 - with N_() the look-up in the message catalog will succeed.

297 +### Shell

298

275 -Shell:

299 +The Git gettext shell interface is just a wrapper for

300 +gettext.sh. Import it right after git-sh-setup like this:

301

277 - - The Git gettext shell interface is just a wrapper for

278 - gettext.sh. Import it right after git-sh-setup like this:

302 +```shell

303 +. git-sh-setup

304 +. git-sh-i18n

305 +```

306

280 - . git-sh-setup

281 - . git-sh-i18n

307 +And then use the `gettext` or `eval_gettext` functions:

308

283 - And then use the gettext or eval_gettext functions:

309 +```shell

310 +# For constant interface messages:

311 +gettext "A message for the user"; echo

312

285 - # For constant interface messages:

286 - gettext "A message for the user"; echo

313 +# To interpolate variables:

314 +details="oh noes"

315 +eval_gettext "An error occurred: \$details"; echo

316 +```

317

288 - # To interpolate variables:

289 - details="oh noes"

290 - eval_gettext "An error occurred: \$details"; echo

318 +In addition we have wrappers for messages that end with a trailing

319 +newline. I.e. you could write the above as:

320

292 - In addition we have wrappers for messages that end with a trailing

293 - newline. I.e. you could write the above as:

321 +```shell

322 +# For constant interface messages:

323 +gettextln "A message for the user"

324

295 - # For constant interface messages:

296 - gettextln "A message for the user"

325 +# To interpolate variables:

326 +details="oh noes"

327 +eval_gettextln "An error occurred: \$details"

328 +```

329

298 - # To interpolate variables:

299 - details="oh noes"

300 - eval_gettextln "An error occurred: \$details"

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:

333

302 - More documentation about the interface is available in the GNU info

303 - page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell

304 - command to be translated) for examples is also useful:

334 +```shell

335 +git log --reverse -p --grep=i18n git-am.sh

336 +```

337

306 - git log --reverse -p --grep=i18n git-am.sh

338

308 -Perl:

339 +### Perl

340

310 - - The Git::I18N module provides a limited subset of the

311 - Locale::Messages functionality, e.g.:

341 +The Git::I18N module provides a limited subset of the

342 +Locale::Messages functionality, e.g.:

343

313 - use Git::I18N;

314 - print __("Welcome to Git!\n");

315 - printf __("The following error occurred: %s\n"), $error;

344 +```perl

345 +use Git::I18N;

346 +print __("Welcome to Git!\n");

347 +printf __("The following error occurred: %s\n"), $error;

348 +```

349

317 - Run `perldoc perl/Git/I18N.pm` for more info.

350 +Run `perldoc perl/Git/I18N.pm` for more info.

351

352

320 -Testing marked strings

321 -----------------------

353 +## Testing marked strings

354

323 -Git's tests are run under LANG=C LC_ALL=C. So the tests do not need be

355 +Git's tests are run under `LANG=C LC_ALL=C`. So the tests do not need be

356 changed to account for translations as they're added.

357

358

327 -PO helper

328 ----------

359 +## PO helper

360

330 -To make the maintenance of XX.po easier, the l10n coordinator and l10n

361 +To make the maintenance of "XX.po" easier, the l10n coordinator and l10n

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.

@@ -337,64 +368,84 @@ To build and install the helper program from source, see

368

369 Usage for git-po-helper:

370

340 - - To start a new language translation:

371 +- To start a new language translation:

372

342 - git-po-helper init XX.po

373 + ```shell

374 + git-po-helper init XX.po

375 + ```

376

344 - - To update your XX.po file:

377 +- To update your "XX.po" file:

378

346 - git-po-helper update XX.po

379 + ```shell

380 + git-po-helper update XX.po

381 + ```

382

348 - - To check commit log and syntax of XX.po:

383 +- To check commit log and syntax of "XX.po":

384

350 - git-po-helper check-po XX.po

351 - git-po-helper check-commits

385 + ```shell

386 + git-po-helper check-po XX.po

387 + git-po-helper check-commits

388 + ```

389

390 Run "git-po-helper" without arguments to show usage.

391

392

356 -Conventions

357 ------------

393 +## Conventions

394

395 There are some conventions that l10n contributors must follow:

396

361 -1. The subject of each l10n commit should be prefixed with "l10n: ".

362 -2. Do not use non-ASCII characters in the subject of a commit.

363 -3. The length of commit subject (first line of the commit log) should

364 - be less than 50 characters, and the length of other lines of the

365 - commit log should be no more than 72 characters.

366 -4. Add "Signed-off-by" trailer to your commit log, like other commits

367 - in Git. You can automatically add the trailer by committing with

368 - the following command:

397 +- The subject of each l10n commit should be prefixed with "l10n: ".

398

370 - git commit -s

399 +- Do not use non-ASCII characters in the subject of a commit.

400

372 -5. Check syntax with "msgfmt" or the following command before creating

373 - your commit:

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

375 - git-po-helper check-po <XX.po>

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

377 -6. Squash trivial commits to make history clear.

378 -7. DO NOT edit files outside "po/" directory.

379 -8. Other subsystems ("git-gui", "gitk", and Git itself) have their

380 - own workflow. See [Documentation/SubmittingPatches][] for

381 - instructions on how to contribute patches to these subsystems.

428

429 To contribute for a new l10n language, contributor should follow

430 additional conventions:

431

386 -1. Initialize proper filename of the "XX.po" file conforming to

387 - iso-639 and iso-3166.

388 -2. Must complete a minimal translation based on the "po-core/core.pot"

389 - template. Using the following command to initialize the minimal

390 - "po-core/XX.po" file:

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

392 - git-po-helper init --core <your-language>

439 + ```shell

440 + git-po-helper init --core <your-language>

441 + ```

442

394 -3. Add a new entry in the "po/TEAMS" file with proper format, and check

395 - the syntax of "po/TEAMS" by running the following command:

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

397 - git-po-helper team --check

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

l10n: README: refactor to use GFM syntax