Ævar Arnfjörð Bjarmason [off-list ref] writes:
Hi, since you didn't pick this up in the last push I fixed it up a bit
more.
I rebased ab/i18n-all-continue on the new master:
git fetch git://github.com/avar/git +ab/i18n-all-continue:ab/i18n
But you probably want this instead:
git fetch git://github.com/avar/git +ab/i18n-all-continue-with-hindi:ab/i18n
I took the liberty of adding Ramkumar Ramachandra's hi.po patch to the
series.
I think that the latter is "i18n-continue-with-hindi" (no "all"), and also
suspect that ab/i18n-all-continue either hasn't be pushed out or is stale?
The copy of "all-continue" I just fetched ends with 2b5170f (gettextize:
git-shortlog basic messages, 2010-09-05) while hindi^ is at c4adf2e
(gettextize: git-am printf(1) message to eval_gettext, 2010-09-07).
I haven't formed an opinion as to what to do with the *.po files after the
series hits 'next' (or anything more stable than 'pu'); my preference is
to delegate that part of the system to somebody who volunteers as an i18n
coordinator, and pull from him/her from time to time, just like the way
gitk and git-gui are managed.
For now, I'll queue the whole thing and merge that to 'pu', but we would
want to squash l10n commits after (but not including) 8d65a35 (gettext
tests: test re-encoding with a UTF-8 msgid under Shell, 2010-08-30) that
touch only one file in po/*.po into one commit per language, move them
near the tip after all the infrastructure enhancements (and fix-ups to the
infrastructure, if necessary) and individual command i18ns, to make the
end result a reasonably complete and clean "first cut for public testing"
of the series before it hits 'next'.
As a companion update to 6495411 (gettext docs: add po/README file
documenting Git's gettext, 2010-09-03), we would need a file in
Documentation/ directory to describe the use of _() and N_() for
programmers and point it from CodingGuidelines. We might also want to
move po/README to Documentation/ but I don't have strong preference either
way.
Thanks.
On Fri, Sep 10, 2010 at 16:01, Junio C Hamano [off-list ref] wrote:
Ævar Arnfjörð Bjarmason [off-list ref] writes:
quoted
Hi, since you didn't pick this up in the last push I fixed it up a bit
more.
I rebased ab/i18n-all-continue on the new master:
git fetch git://github.com/avar/git +ab/i18n-all-continue:ab/i18n
But you probably want this instead:
git fetch git://github.com/avar/git +ab/i18n-all-continue-with-hindi:ab/i18n
I took the liberty of adding Ramkumar Ramachandra's hi.po patch to the
series.
I think that the latter is "i18n-continue-with-hindi" (no "all")
Yes, sorry. It's just "ab/i18n-continue-with-hindi".
and also suspect that ab/i18n-all-continue either hasn't be pushed
out or is stale?
Yes sorry, I pushed to "ab/i18n-continue"
instead. "ab/i18n-all-continue" is now up-to-date (equivalent to
"ab/i18n-continue"). Sorry abuot the mixup.
The copy of "all-continue" I just fetched ends with 2b5170f (gettextize:
git-shortlog basic messages, 2010-09-05) while hindi^ is at c4adf2e
(gettextize: git-am printf(1) message to eval_gettext, 2010-09-07).
The hindi^ one was the right tip.
I haven't formed an opinion as to what to do with the *.po files after the
series hits 'next' (or anything more stable than 'pu'); my preference is
to delegate that part of the system to somebody who volunteers as an i18n
coordinator, and pull from him/her from time to time, just like the way
gitk and git-gui are managed.
We could certainly set up something like that. I going to wait and see
if we needed it before proposing such a thing.
After an initial spur of translation submissions po/ will probably
quiet down quickly. We aren't adding new strings that often, so
updating translations shouldn't represent much PATCH traffic on-list.
But it could be split up if that's preferred too.
For now, I'll queue the whole thing and merge that to 'pu', but we would
want to squash l10n commits after (but not including) 8d65a35 (gettext
tests: test re-encoding with a UTF-8 msgid under Shell, 2010-08-30) that
touch only one file in po/*.po into one commit per language, move them
near the tip after all the infrastructure enhancements (and fix-ups to the
infrastructure, if necessary) and individual command i18ns, to make the
end result a reasonably complete and clean "first cut for public testing"
of the series before it hits 'next'.
I can move those around, I didn't do so already because their position
in the series is semantically meaningful. I.e. at the time is.po is
added it's pretty much a 100% translation, but more strings are added
after that.
That's a trivial minor issue with msgmerge and msgfmt --statistics to
find out how much is translated though. So I've re-arranged them and
squashed 'em for you here:
git://github.com/avar/git.git ab/i18n-for-junio
As a companion update to 6495411 (gettext docs: add po/README file
documenting Git's gettext, 2010-09-03), we would need a file in
Documentation/ directory to describe the use of _() and N_() for
programmers and point it from CodingGuidelines.
I can add that to ab/i18n-for-junio, but haven't already. Isn't it
better if I send that to the list for review instead of just tucking
something at the end of the series. I can do either.
We might also want to move po/README to Documentation/ but I don't
have strong preference either way.
I'd like to make it a manpage (as mentioned before), but i can't
figure out a good git-*.txt name for it.
On Fri, Sep 10, 2010 at 17:17, Ævar Arnfjörð Bjarmason [off-list ref] wrote:
On Fri, Sep 10, 2010 at 16:01, Junio C Hamano [off-list ref] wrote:
quoted
As a companion update to 6495411 (gettext docs: add po/README file
documenting Git's gettext, 2010-09-03), we would need a file in
Documentation/ directory to describe the use of _() and N_() for
programmers and point it from CodingGuidelines.
I can add that to ab/i18n-for-junio, but haven't already. Isn't it
better if I send that to the list for review instead of just tucking
something at the end of the series. I can do either.
Here it is on top of ab/i18n-for-junio. These can also be fetched
from:
git://github.com/avar/git.git ab/i18n-for-junio-with-docs
Ævar Arnfjörð Bjarmason (5):
gettext docs: add a "Testing your changes" section to po/README
gettext docs: add "Marking strings for translation" section in
po/README
gettext docs: the gettext.h C interface
gettext docs: the git-sh-i18n.sh Shell interface
gettext docs: the Git::I18N Perl interface
Documentation/CodingGuidelines | 7 ++
git-sh-i18n.sh | 16 +-----
po/README | 125 +++++++++++++++++++++++++++++++++++++++-
3 files changed, 133 insertions(+), 15 deletions(-)
--
1.7.2.3.313.gcd15
Change po/README to tell translators that they should do `make` at the
top-level before submitting their translations. Many common errors
will be caught with the `msgfmt --check` run that the Makefile will
compile the message catalogs with.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
po/README | 14 ++++++++++++++
1 files changed, 14 insertions(+), 0 deletions(-)
diff --git a/po/README b/po/README
index cca8012..4d23ca6 100644
--- a/po/README
+++ b/po/README
@@ -66,3 +66,17 @@ But then you need remember to remove the comments before you submit
the file upstream:
perl -pi -e 's/^#: .*\n//' XX.po
+
+
+Testing your changes
+--------------------
+
+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.--
1.7.2.3.313.gcd15
Change po/README's "Marking strings for translation" section so that
it covers the gettext.h C interface.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
po/README | 36 ++++++++++++++++++++++++++++++++++++
1 files changed, 36 insertions(+), 0 deletions(-)
diff --git a/po/README b/po/README
index 372cb9c..ac12637 100644
--- a/po/README
+++ b/po/README
@@ -119,3 +119,39 @@ General advice:
/* TRANSLATORS: %s will be "revert" or "cherry-pick" */
die(_("%s: Unable to write new index file"), me);
+
+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 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);
+
+ - 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.--
1.7.2.3.313.gcd15
Change po/README's "Marking strings for translation" section so that
it covers the git-sh-i18n.sh Shell interface.
The existing documentation in git-sh-i18n.sh has been moved to the
README file, to avoid them drifting in apart..
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
git-sh-i18n.sh | 16 ++--------------
po/README | 23 +++++++++++++++++++++++
2 files changed, 25 insertions(+), 14 deletions(-)
diff --git a/git-sh-i18n.sh b/git-sh-i18n.sh
index b8b645a..f8dd43a 100644
--- a/git-sh-i18n.sh
+++ b/git-sh-i18n.sh
@@ -2,20 +2,8 @@
#
# Copyright (c) 2010 Ævar Arnfjörð Bjarmason
#
-# This is Git's interface to gettext.sh. Use it right after
-# git-sh-setup as:
-#
-# . git-sh-setup
-# . git-sh-i18n
-#
-# # For constant interface messages:
-# gettext "A message for the user"; echo
-#
-# # To interpolate variables:
-# details="oh noes"
-# eval_gettext "An error occured: \$details"; echo
-#
-# See "info '(gettext)sh'" for the full manual.
+# This is Git's interface to gettext.sh. See po/README for usage
+# instructions.
# Export the TEXTDOMAIN* data that we need for Git
TEXTDOMAIN=git
diff --git a/po/README b/po/README
index ac12637..513cf32 100644
--- a/po/README
+++ b/po/README
@@ -155,3 +155,26 @@ C:
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 occured: \$details"; echo
+
+ 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=gettextize git-am.sh--
1.7.2.3.313.gcd15
Change po/README's "Marking strings for translation" section so that
it covers the Git::I18N Perl interface.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
po/README | 11 +++++++++++
1 files changed, 11 insertions(+), 0 deletions(-)
diff --git a/po/README b/po/README
index 513cf32..0d1cfa0 100644
--- a/po/README
+++ b/po/README
@@ -178,3 +178,14 @@ Shell:
command to be translated) for examples is also useful:
git log --reverse -p --grep=gettextize 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 occured: %s\n"), $error;
+
+ Run `perldoc perl/Git/I18N.pm` for more info.--
1.7.2.3.313.gcd15
Add a "Marking strings for translation" section to po/README and
mention it in Documentation/CodingGuidelines.
This section documents how the maintainers of Git's source code should
go about properly marking strings for translation.
Signed-off-by: Ævar Arnfjörð Bjarmason <redacted>
---
Documentation/CodingGuidelines | 7 ++++++
po/README | 41 +++++++++++++++++++++++++++++++++++++++-
2 files changed, 47 insertions(+), 1 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index b8bf618..2e114d6 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -70,6 +70,10 @@ For shell scripts specifically (not exhaustive):
are ERE elements not BRE (note that \? and \+ are not even part
of BRE -- making them accessible from BRE is a GNU extension).
+ - Use Git's gettext wrappers in git-sh-i18n to make the user
+ interface translatable. See "Marking strings for translation" in
+ po/README.
+
For C programs:
- We use tabs to indent, and interpret tabs as taking up to@@ -132,3 +136,6 @@ For C programs:
- When we pass <string, length> pair to functions, we should try to
pass them in that order.
+
+ - Use Git's gettext wrappers to make the user interface
+ translatable. See "Marking strings for translation" in po/README.diff --git a/po/README b/po/README
index 4d23ca6..372cb9c 100644
--- a/po/README
+++ b/po/README
@@ -2,7 +2,8 @@ Core GIT Translations
=====================
This directory holds the translations for the core of Git. This
-document describes how to add to and maintain these translations.
+document describes how to add to and maintain these translations, and
+how to mark source strings for translation.
Generating a .pot file
@@ -80,3 +81,41 @@ 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
+-------------------------------
+
+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. These strings
+ should not be translated.
+
+ - 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"), me);--
1.7.2.3.313.gcd15
On Fri, Sep 10, 2010 at 19:35, Ævar Arnfjörð Bjarmason [off-list ref] wrote:
On Fri, Sep 10, 2010 at 17:17, Ævar Arnfjörð Bjarmason [off-list ref] wrote:
quoted
On Fri, Sep 10, 2010 at 16:01, Junio C Hamano [off-list ref] wrote:
quoted
As a companion update to 6495411 (gettext docs: add po/README file
documenting Git's gettext, 2010-09-03), we would need a file in
Documentation/ directory to describe the use of _() and N_() for
programmers and point it from CodingGuidelines.
I can add that to ab/i18n-for-junio, but haven't already. Isn't it
better if I send that to the list for review instead of just tucking
something at the end of the series. I can do either.
Here it is on top of ab/i18n-for-junio. These can also be fetched
from:
git://github.com/avar/git.git ab/i18n-for-junio-with-docs
I fixed the wording on this as suggested by Junio, and a trivial
whitespace issue, but not the N_() example.
This ref can replace the existing ab/i18n ref in pu.