306 lines
10 KiB
Text
306 lines
10 KiB
Text
Core GIT Translations
|
|
=====================
|
|
|
|
This directory holds the translations for the core of Git. This document
|
|
describes how you can contribute to the effort of enhancing the language
|
|
coverage and maintaining the translation.
|
|
|
|
The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,
|
|
coordinates our localization effort in the l10 coordinator repository:
|
|
|
|
https://github.com/git-l10n/git-po/
|
|
|
|
The two character language translation codes are defined by ISO_639-1, as
|
|
stated in the gettext(1) full manual, appendix A.1, Usual Language Codes.
|
|
|
|
|
|
Contributing to an existing translation
|
|
---------------------------------------
|
|
As a contributor for a language XX, you should first check TEAMS file in
|
|
this directory to see whether a dedicated repository for your language XX
|
|
exists. Fork the dedicated repository and start to work if it exists.
|
|
|
|
Sometime, contributors may find that the translations of their Git
|
|
distributions are quite different with the translations of the
|
|
corresponding version from Git official. This is because some Git
|
|
distributions (such as from Ubuntu, etc.) have their own l10n workflow.
|
|
For this case, wrong translations should be reported and fixed through
|
|
their workflows.
|
|
|
|
|
|
Creating a new language translation
|
|
-----------------------------------
|
|
If you are the first contributor for the language XX, please fork this
|
|
repository, prepare and/or update the translated message file po/XX.po
|
|
(described later), and ask the l10n coordinator to pull your work.
|
|
|
|
If there are multiple contributors for the same language, please first
|
|
coordinate among yourselves and nominate the team leader for your
|
|
language, so that the l10n coordinator only needs to interact with one
|
|
person per language.
|
|
|
|
|
|
Translation Process Flow
|
|
------------------------
|
|
The overall data-flow looks like this:
|
|
|
|
+-------------------+ +------------------+
|
|
| Git source code | ---(1)---> | L10n coordinator |
|
|
| repository | <---(4)--- | repository |
|
|
+-------------------+ +------------------+
|
|
| ^
|
|
(2) (3)
|
|
V |
|
|
+------------------+
|
|
| Language Team XX |
|
|
+------------------+
|
|
|
|
* Translatable strings are marked in the source file.
|
|
* L10n coordinator pulls from the source (1)
|
|
* L10n coordinator updates the message template po/git.pot
|
|
* Language team pulls from L10n coordinator (2)
|
|
* Language team updates the message file po/XX.po
|
|
* L10n coordinator pulls from Language team (3)
|
|
* L10n coordinator asks the result to be pulled (4).
|
|
|
|
|
|
Maintaining the po/git.pot file
|
|
-------------------------------
|
|
|
|
(This is done by the l10n coordinator).
|
|
|
|
The po/git.pot file contains a message catalog extracted from Git's
|
|
sources. The l10n coordinator maintains it by adding new translations with
|
|
msginit(1), or update existing ones with msgmerge(1). In order to update
|
|
the Git sources to extract the messages from, the l10n coordinator is
|
|
expected to pull from the main git repository at strategic point in
|
|
history (e.g. when a major release and release candidates are tagged),
|
|
and then run "make pot" at the top-level directory.
|
|
|
|
Language contributors use this file to prepare translations for their
|
|
language, but they are not expected to modify it.
|
|
|
|
|
|
Initializing a XX.po file
|
|
-------------------------
|
|
|
|
(This is done by the language teams).
|
|
|
|
If your language XX does not have translated message file po/XX.po yet,
|
|
you add a translation for the first time by running:
|
|
|
|
msginit --locale=XX
|
|
|
|
in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR",
|
|
"zh_CN", etc.
|
|
|
|
Then edit the automatically generated copyright info in your new XX.po
|
|
to be correct, e.g. for Icelandic:
|
|
|
|
@@ -1,6 +1,6 @@
|
|
-# Icelandic translations for PACKAGE package.
|
|
-# Copyright (C) 2010 THE PACKAGE'S COPYRIGHT HOLDER
|
|
-# This file is distributed under the same license as the PACKAGE package.
|
|
+# Icelandic translations for Git.
|
|
+# Copyright (C) 2010 Ævar Arnfjörð Bjarmason <avarab@gmail.com>
|
|
+# This file is distributed under the same license as the Git package.
|
|
# Ævar Arnfjörð Bjarmason <avarab@gmail.com>, 2010.
|
|
|
|
And change references to PACKAGE VERSION in the PO Header Entry to
|
|
just "Git":
|
|
|
|
perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
|
|
|
|
Once you are done testing the translation (see below), commit the result
|
|
and ask the l10n coordinator to pull from you.
|
|
|
|
|
|
Updating a XX.po file
|
|
---------------------
|
|
|
|
(This is done by the language teams).
|
|
|
|
If you are replacing translation strings in an existing XX.po file to
|
|
improve the translation, just edit the file.
|
|
|
|
If there's an existing XX.po file for your language, but the repository
|
|
of the l10n coordinator has newer po/git.pot file, you would need to first
|
|
pull from the l10n coordinator (see the beginning of this document for its
|
|
URL), and then update the existing translation by running:
|
|
|
|
msgmerge --add-location --backup=off -U XX.po git.pot
|
|
|
|
in the po/ directory, where XX.po is the file you want to update.
|
|
|
|
Once you are done testing the translation (see below), commit the result
|
|
and ask the l10n coordinator to pull from you.
|
|
|
|
|
|
Testing your changes
|
|
--------------------
|
|
|
|
(This is done by the language teams, after creating or updating XX.po file).
|
|
|
|
Before you submit your changes go back to the top-level and do:
|
|
|
|
make
|
|
|
|
On systems with GNU gettext (i.e. not Solaris) this will compile your
|
|
changed PO file with `msgfmt --check`, the --check option flags many
|
|
common errors, e.g. missing printf format strings, or translated
|
|
messages that deviate from the originals in whether they begin/end
|
|
with a newline or not.
|
|
|
|
|
|
Marking strings for translation
|
|
-------------------------------
|
|
|
|
(This is done by the core developers).
|
|
|
|
Before strings can be translated they first have to be marked for
|
|
translation.
|
|
|
|
Git uses an internationalization interface that wraps the system's
|
|
gettext library, so most of the advice in your gettext documentation
|
|
(on GNU systems `info gettext` in a terminal) applies.
|
|
|
|
General advice:
|
|
|
|
- Don't mark everything for translation, only strings which will be
|
|
read by humans (the porcelain interface) should be translated.
|
|
|
|
The output from Git's plumbing utilities will primarily be read by
|
|
programs and would break scripts under non-C locales if it was
|
|
translated. Plumbing strings should not be translated, since
|
|
they're part of Git's API.
|
|
|
|
- Adjust the strings so that they're easy to translate. Most of the
|
|
advice in `info '(gettext)Preparing Strings'` applies here.
|
|
|
|
- If something is unclear or ambiguous you can use a "TRANSLATORS"
|
|
comment to tell the translators what to make of it. These will be
|
|
extracted by xgettext(1) and put in the po/*.po files, e.g. from
|
|
git-am.sh:
|
|
|
|
# TRANSLATORS: Make sure to include [y], [n], [e], [v] and [a]
|
|
# in your translation. The program will only accept English
|
|
# input at this point.
|
|
gettext "Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all "
|
|
|
|
Or in C, from builtin/revert.c:
|
|
|
|
/* TRANSLATORS: %s will be "revert" or "cherry-pick" */
|
|
die(_("%s: Unable to write new index file"), action_name(opts));
|
|
|
|
We provide wrappers for C, Shell and Perl programs. Here's how they're
|
|
used:
|
|
|
|
C:
|
|
|
|
- Include builtin.h at the top, it'll pull in gettext.h, which
|
|
defines the gettext interface. Consult with the list if you need to
|
|
use gettext.h directly.
|
|
|
|
- The C interface is a subset of the normal GNU gettext
|
|
interface. We currently export these functions:
|
|
|
|
- _()
|
|
|
|
Mark and translate a string. E.g.:
|
|
|
|
printf(_("HEAD is now at %s"), hex);
|
|
|
|
- Q_()
|
|
|
|
Mark and translate a plural string. E.g.:
|
|
|
|
printf(Q_("%d commit", "%d commits", number_of_commits));
|
|
|
|
This is just a wrapper for the ngettext() function.
|
|
|
|
- N_()
|
|
|
|
A no-op pass-through macro for marking strings inside static
|
|
initializations, e.g.:
|
|
|
|
static const char *reset_type_names[] = {
|
|
N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL
|
|
};
|
|
|
|
And then, later:
|
|
|
|
die(_("%s reset is not allowed in a bare repository"),
|
|
_(reset_type_names[reset_type]));
|
|
|
|
Here _() couldn't have statically determined what the translation
|
|
string will be, but since it was already marked for translation
|
|
with N_() the look-up in the message catalog will succeed.
|
|
|
|
Shell:
|
|
|
|
- The Git gettext shell interface is just a wrapper for
|
|
gettext.sh. Import it right after git-sh-setup like this:
|
|
|
|
. git-sh-setup
|
|
. git-sh-i18n
|
|
|
|
And then use the gettext or eval_gettext functions:
|
|
|
|
# For constant interface messages:
|
|
gettext "A message for the user"; echo
|
|
|
|
# To interpolate variables:
|
|
details="oh noes"
|
|
eval_gettext "An error occurred: \$details"; echo
|
|
|
|
In addition we have wrappers for messages that end with a trailing
|
|
newline. I.e. you could write the above as:
|
|
|
|
# For constant interface messages:
|
|
gettextln "A message for the user"
|
|
|
|
# To interpolate variables:
|
|
details="oh noes"
|
|
eval_gettextln "An error occurred: \$details"
|
|
|
|
More documentation about the interface is available in the GNU info
|
|
page: `info '(gettext)sh'`. Looking at git-am.sh (the first shell
|
|
command to be translated) for examples is also useful:
|
|
|
|
git log --reverse -p --grep=i18n git-am.sh
|
|
|
|
Perl:
|
|
|
|
- The Git::I18N module provides a limited subset of the
|
|
Locale::Messages functionality, e.g.:
|
|
|
|
use Git::I18N;
|
|
print __("Welcome to Git!\n");
|
|
printf __("The following error occurred: %s\n"), $error;
|
|
|
|
Run `perldoc perl/Git/I18N.pm` for more info.
|
|
|
|
|
|
Testing marked strings
|
|
----------------------
|
|
|
|
Even if you've correctly marked porcelain strings for translation
|
|
something in the test suite might still depend on the US English
|
|
version of the strings, e.g. to grep some error message or other
|
|
output.
|
|
|
|
To smoke out issues like these, Git tested with a translation mode that
|
|
emits gibberish on every call to gettext. To use it run the test suite
|
|
with it, e.g.:
|
|
|
|
cd t && GIT_TEST_GETTEXT_POISON=true prove -j 9 ./t[0-9]*.sh
|
|
|
|
If tests break with it you should inspect them manually and see if
|
|
what you're translating is sane, i.e. that you're not translating
|
|
plumbing output.
|
|
|
|
If not you should replace calls to grep with test_i18ngrep, or
|
|
test_cmp calls with test_i18ncmp. If that's not enough you can skip
|
|
the whole test by making it depend on the C_LOCALE_OUTPUT
|
|
prerequisite. See existing test files with this prerequisite for
|
|
examples.
|