doc: describe git svn init --ignore-refs
[git/git-svn.git] / po / README
blobfef4c0f0b5ae15e98b8a5913afe60783a701f40a
1 Core GIT Translations
2 =====================
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.
8 The localization (l10n) coordinator, Jiang Xin <worldhello.net@gmail.com>,
9 coordinates our localization effort in the l10 coordinator repository:
11         https://github.com/git-l10n/git-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.
17 Contributing to an existing translation
18 ---------------------------------------
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.
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.
31 Creating a new language translation
32 -----------------------------------
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.
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.
43 Translation Process Flow
44 ------------------------
45 The overall data-flow looks like this:
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                                      +------------------+
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).
67 Maintaining the po/git.pot file
68 -------------------------------
70 (This is done by the l10n coordinator).
72 The po/git.pot file contains a message catalog extracted from Git's
73 sources. The l10n coordinator maintains it by adding new translations with
74 msginit(1), or update existing ones with msgmerge(1).  In order to update
75 the Git sources to extract the messages from, the l10n coordinator is
76 expected to pull from the main git repository at strategic point in
77 history (e.g. when a major release and release candidates are tagged),
78 and then run "make pot" at the top-level directory.
80 Language contributors use this file to prepare translations for their
81 language, but they are not expected to modify it.
84 Initializing a XX.po file
85 -------------------------
87 (This is done by the language teams).
89 If your language XX does not have translated message file po/XX.po yet,
90 you add a translation for the first time by running:
92     msginit --locale=XX
94 in the po/ directory, where XX is the locale, e.g. "de", "is", "pt_BR",
95 "zh_CN", etc.
97 Then edit the automatically generated copyright info in your new XX.po
98 to be correct, e.g. for Icelandic:
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.
109 And change references to PACKAGE VERSION in the PO Header Entry to
110 just "Git":
112     perl -pi -e 's/(?<="Project-Id-Version: )PACKAGE VERSION/Git/' XX.po
114 Once you are done testing the translation (see below), commit the result
115 and ask the l10n coordinator to pull from you.
118 Updating a XX.po file
119 ---------------------
121 (This is done by the language teams).
123 If you are replacing translation strings in an existing XX.po file to
124 improve the translation, just edit the file.
126 If there's an existing XX.po file for your language, but the repository
127 of the l10n coordinator has newer po/git.pot file, you would need to first
128 pull from the l10n coordinator (see the beginning of this document for its
129 URL), and then update the existing translation by running:
131     msgmerge --add-location --backup=off -U XX.po git.pot
133 in the po/ directory, where XX.po is the file you want to update.
135 Once you are done testing the translation (see below), commit the result
136 and ask the l10n coordinator to pull from you.
139 Testing your changes
140 --------------------
142 (This is done by the language teams, after creating or updating XX.po file).
144 Before you submit your changes go back to the top-level and do:
146     make
148 On systems with GNU gettext (i.e. not Solaris) this will compile your
149 changed PO file with `msgfmt --check`, the --check option flags many
150 common errors, e.g. missing printf format strings, or translated
151 messages that deviate from the originals in whether they begin/end
152 with a newline or not.
155 Marking strings for translation
156 -------------------------------
158 (This is done by the core developers).
160 Before strings can be translated they first have to be marked for
161 translation.
163 Git uses an internationalization interface that wraps the system's
164 gettext library, so most of the advice in your gettext documentation
165 (on GNU systems `info gettext` in a terminal) applies.
167 General advice:
169  - Don't mark everything for translation, only strings which will be
170    read by humans (the porcelain interface) should be translated.
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.
177  - Adjust the strings so that they're easy to translate. Most of the
178    advice in `info '(gettext)Preparing Strings'` applies here.
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:
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 "
190    Or in C, from builtin/revert.c:
192        /* TRANSLATORS: %s will be "revert" or "cherry-pick" */
193        die(_("%s: Unable to write new index file"), action_name(opts));
195 We provide wrappers for C, Shell and Perl programs. Here's how they're
196 used:
200  - Include builtin.h at the top, it'll pull in gettext.h, which
201    defines the gettext interface. Consult with the list if you need to
202    use gettext.h directly.
204  - The C interface is a subset of the normal GNU gettext
205    interface. We currently export these functions:
207    - _()
209     Mark and translate a string. E.g.:
211         printf(_("HEAD is now at %s"), hex);
213    - Q_()
215     Mark and translate a plural string. E.g.:
217         printf(Q_("%d commit", "%d commits", number_of_commits));
219     This is just a wrapper for the ngettext() function.
221    - N_()
223     A no-op pass-through macro for marking strings inside static
224     initializations, e.g.:
226         static const char *reset_type_names[] = {
227             N_("mixed"), N_("soft"), N_("hard"), N_("merge"), N_("keep"), NULL
228         };
230     And then, later:
232         die(_("%s reset is not allowed in a bare repository"),
233                _(reset_type_names[reset_type]));
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.
239 Shell:
241  - The Git gettext shell interface is just a wrapper for
242    gettext.sh. Import it right after git-sh-setup like this:
244        . git-sh-setup
245        . git-sh-i18n
247    And then use the gettext or eval_gettext functions:
249        # For constant interface messages:
250        gettext "A message for the user"; echo
252        # To interpolate variables:
253        details="oh noes"
254        eval_gettext "An error occurred: \$details"; echo
256    In addition we have wrappers for messages that end with a trailing
257    newline. I.e. you could write the above as:
259        # For constant interface messages:
260        gettextln "A message for the user"
262        # To interpolate variables:
263        details="oh noes"
264        eval_gettextln "An error occurred: \$details"
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:
270        git log --reverse -p --grep=i18n git-am.sh
272 Perl:
274  - The Git::I18N module provides a limited subset of the
275    Locale::Messages functionality, e.g.:
277        use Git::I18N;
278        print __("Welcome to Git!\n");
279        printf __("The following error occurred: %s\n"), $error;
281    Run `perldoc perl/Git/I18N.pm` for more info.
284 Testing marked strings
285 ----------------------
287 Even if you've correctly marked porcelain strings for translation
288 something in the test suite might still depend on the US English
289 version of the strings, e.g. to grep some error message or other
290 output.
292 To smoke out issues like these Git can be compiled with gettext poison
293 support, at the top-level:
295     make GETTEXT_POISON=YesPlease
297 That'll give you a git which emits gibberish on every call to
298 gettext. It's obviously not meant to be installed, but you should run
299 the test suite with it:
301     cd t && prove -j 9 ./t[0-9]*.sh
303 If tests break with it you should inspect them manually and see if
304 what you're translating is sane, i.e. that you're not translating
305 plumbing output.
307 If not you should replace calls to grep with test_i18ngrep, or
308 test_cmp calls with test_i18ncmp. If that's not enough you can skip
309 the whole test by making it depend on the C_LOCALE_OUTPUT
310 prerequisite. See existing test files with this prerequisite for
311 examples.