Antwort: git-gui i18n introductory document

Antwort: git-gui i18n introductory document

[Christian Stimming]

Junio C Hamano <gitster@pobox.com> schrieb am 26.07.2007 08:14:03:
> I also noticed that po/ directory lacks
> any guidance document for translators.  Here is an attempt to
> add po/README.

Thanks for this write-up. This is very nice, and I agree it is helpful for
everyone working on the translations.

FYI, in the gnucash project we have a similar write-up, only that over time
we were asked to cover pretty much any subject that came up, so the
document ended up quite long. See http://wiki.gnucash.org/wiki/Translation

One topic that hasn't been covered but should be added is the po/glossary/
directory. I'd suggest to point new translators to there *first*, because
getting the glossary right is a necessary condition for achieving a
high-quality translation.

> I understand that Christian's stance on this issue, to put it
> bluntly, is that you should not be in the l10n business if you
> are not versed with gettext toolchain.

I wouldn't require someone to be "versed". But I would indeed require
someone to 1. have the gettext toolchain *installed* (after all, that
person also must have git installed), and 2. I'd strongly recommend to work
on the po files with one of the specialized *po file editors* instead of a
plain text editor. There are so many editors available: emacs po-mode,
KBabel, poedit, GTranslator; it definitely shouldn't be difficult to use at
least one of them.

Nevertheless, explaining the po file structure here in the README is a good
thing in itself.

Some comments on your explanation in the file itself:

> +0. Getting started.
> +
> +You would first need to have a working "git".  Your distribution
> +may have git-core package (do not get "GNU Interactive Tools" --
> +that is a different "git").  Please install it.

You should mention the gettext package (required for .msg creation) and one
of the po editors here as well.

> + - Control characters, such as newlines, are written in
> +   backslash sequence
> +
> + - A long message can be split across multiple lines by ending
> +   the string with a doublequote, and starting another string on
> +   the next line with another doublequote.

Good points. Additionally, we need to explain the [format...] arguments
here, i.e. what to do with a "%s" or "%i" or "%%" in the string.

> +You can test the result by running "make", which would create
> +po/af.msg file, and then running the resulting git-gui in your
> +locale:
> +
> +   $ make install
> +   $ LANG=af git-gui

Does the latter line give the newly created translation for you, even
without "make install"? For me and from what I understand from the code,
the message catalogs are searched for in the subdirectory msgs/ of the lib/
directory, which means they wouldn't be found in an unmodified checkout.
But you can create a symlink of that name to have the checkout use directly
the po/ directory, like so:

   cd lib
   ln -s ../po msgs
   cd ..
   LANG=jp ./git-gui.sh

and I also have to call the local git-gui with ./ because . is not in my
PATH, which is probably the same for some people out there as well.

> +   $ edit po/af.po
> +   ... be sure to update Last-Translator: and
> +   ... PO-Revision-Date: lines.

Yes, thanks for the reminder here.

> + - The original text in English of an older message you already
> +   translated might have been changed.  You will notice a
> +   comment line that begins with "#, fuzzy" in front of such a
> +   message.  msgmerge tool made its best effort to match your
> +   old translation with the message from the updated software,
> +   but you will find it matched your old translated message to a
> +   new msgid that does not make any sense -- you would need to
> +   fix them.

Yes. You should also mention here that a msgstr marked as "#, fuzzy" will
be treated as if no translation existed at all by msgfmt. Hence, the
instructions for the translators should be something like this: "Messages
which are marked as fuzzy will not be used in the program. You have to
check the msgstr, fix it to match the msgid message, and remove the #,
fuzzy line."

Overall, this is a nice writeup and it is very helpful. Thanks a lot.

Christian

IBEO Automobile Sensor GmbH - Sitz: Hamburg - Handelsregister: Hamburg HRB
67903
Geschäftsführer: Dr. Ulrich S. Lages

git-gui: i18n introductory document (2nd draft)

[Junio C Hamano]

This short note is to help a translation contributor to help us
localizing git-gui message files by covering the basics.

I have tried to address issues raised in Christian's comments on
the first draft that was circulated privately.  There are a few
remaining issues I could not decide myself, which are marked
with NEEDSWORK in the text.

---
diff --git a/po/README b/po/README
new file mode 100644
index 0000000..974cce4
--- /dev/null
+++ b/po/README
@@ -0,0 +1,203 @@
+Localizing git-gui for your language
+====================================
+
+This short note is to help you, who reads and writes English and your
+own language, help us getting git-gui localized for more languages.  It
+does not try to be a comprehensive manual of GNU gettext, which is the
+i18n framework we use, but tries to help you get started by covering the
+basics and how it is used in this project.
+
+1. Getting started.
+
+You would first need to have a working "git".  Your distribution may
+have it as "git-core" package (do not get "GNU Interactive Tools" --
+that is a different "git").  You would also need GNU gettext toolchain
+to test the resulting translation out.  It also is a good idea to have
+specialized so-called "po file editors" (e.g. emacs po-mode, KBabel,
+poedit, GTranslator).  Please install them.
+
+You would then need to clone the git-gui internationalization project
+repository, so that you can work on it:
+
+	$ git clone mob@repo.or.cz:/srv/git/git-gui/git-gui-i18n.git/
+	$ cd git-gui-i18n.git
+	$ git checkout --track -b mob origin/mob
+	$ git config remote.origin.push mob
+
+The "git checkout" command creates a 'mob' branch from upstream's
+corresponding branch and makes it your current branch.  You will be
+working on this branch.
+
+The "git config" command records in your repository configuration file
+that you would push "mob" branch to the upstream when you say "git
+push".
+
+
+2. Starting a new language.
+
+In the git-gui-i18n.git directory is a po/ subdirectory.  It has a
+handful files whose names end with ".po".  Is there a file that has
+messages in your language?
+
+If you do not know what your language should be named, you need to find
+it.  This currently follows ISO 639-1 two letter codes:
+
+	http://www.loc.gov/standards/iso639-2/php/code_list.php
+
+For example, if you are preparing a translation for Afrikaans, the
+language code is "af".  If there already is a translation for your
+language, you do not have to perform any step in this section, but keep
+reading, because we are covering the basics.
+
+If you did not find your language, you would need to start one yourself.
+Copy po/git-gui.pot file to po/af.po (replace "af" with the code for
+your language).  Edit the first several lines to match existing *.po
+files to make it clear this is a translation table for git-gui project,
+and you are the primary translator.  The result of your editing would
+look something like this:
+
+    # Translation of git-gui to Afrikaans
+    # Copyright (C) 2007 Shawn Pearce
+    # This file is distributed under the same license as the git-gui package.
+    # YOUR NAME <YOUR@E-MAIL.ADDRESS>, 2007.
+    #
+    #, fuzzy
+    msgid ""
+    msgstr ""
+    "Project-Id-Version: git-gui\n"
+    "Report-Msgid-Bugs-To: \n"
+    "POT-Creation-Date: 2007-07-24 22:19+0300\n"
+    "PO-Revision-Date: 2007-07-25 18:00+0900\n"
+    "Last-Translator: YOUR NAME <YOUR@E-MAIL.ADDRESS>\n"
+    "Language-Team: Afrikaans\n"
+    "MIME-Version: 1.0\n"
+    "Content-Type: text/plain; charset=UTF-8\n"
+    "Content-Transfer-Encoding: 8bit\n"
+
+You will find many pairs of a "msgid" line followed by a "msgstr" line.
+These pairs define how messages in git-gui application are translated to
+your language.  Your primarily job is to fill in the empty double quote
+pairs on msgstr lines with the translation of the strings on their
+matching msgid lines.  A few tips:
+
+ - Control characters, such as newlines, are written in backslash
+   sequence similar to string literals in the C programming language.
+   When the string given on a msgid line has such a backslash sequence,
+   you would typically want to have corresponding ones in the string on
+   your msgstr line.
+
+ - Often the messages being translated are format strings given to
+   "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
+   translated messages match the original.
+
+   When you have to change the order of words, you can add "<number>$"
+   between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
+   parameter to the format string is used at this point".  For example,
+   if the original message is like this:
+
+	"Length is %d, Weight is %d"
+	
+   and if for whatever reason your translation needs to say weight first
+   and then length, you can say something like:
+
+	"WEIGHT IS %2$d, LENGTH IS %1$d"
+
+   [NEEDSWORK: this whole "parameter permutation" part needs to be
+   verified if it works with Tcl at all]
+
+ - A long message can be split across multiple lines by ending the
+   string with a double quote, and starting another string on the next
+   line with another double quote.  They will be concatenated in the
+   result.  For example:
+
+   #: lib/remote_branch_delete.tcl:189
+   #, tcl-format
+   msgid ""
+   "One or more of the merge tests failed because you have not fetched the "
+   "necessary commits.  Try fetching from %s first."
+   msgstr ""
+   "HERE YOU WILL WRITE YOUR TRANSLATION OF THE ABOVE LONG "
+   "MESSAGE IN YOUR LANGUAGE."
+
+You can test your translation by running "make install", which would
+create po/af.msg file and installs the result, and then running the
+resulting git-gui under your locale:
+
+	$ make install
+	$ LANG=af git-gui
+
+There is a trick to test your translation without first installing, if
+you prefer.  First, create this symbolic link in the source tree:
+
+	$ ln -s ../po lib/msgs
+
+After setting up such a symbolic link, you can:
+
+	$ make
+	$ LANG=af ./git-gui
+
+[NEEDSWORK: this symlink trick needs to be verified if it works.]
+
+When you are satisfied with your translation, commit your changes, and
+push it back to the 'mob' branch:
+
+	$ edit po/af.po
+	... be sure to update Last-Translator: and
+	... PO-Revision-Date: lines.
+	$ git add po/af.po
+	$ git commit -m 'Started Afrikaans translation.'
+	$ git push
+
+
+3. Updating your translation.
+
+There may already be a translation for your language, and you may want
+to contribute an update.  This may be because you would want to improve
+the translation of existing messages, or because the git-gui software
+itself was updated and there are new messages that need translation.
+
+In any case, make sure you are up-to-date before starting your work:
+
+	$ git pull
+
+In the former case, you will edit po/af.po (again, replace "af" with
+your language code), and after testing and updating the Last-Translator:
+and PO-Revision-Date: lines, "add/commit/push" as in the previous
+section.
+
+By comparing "POT-Creation-Date:" line in po/git-gui.pot file and
+po/af.po file, you can tell if there are new messages that need to be
+translated.  You would need the GNU gettext package to perform this
+step.
+
+	$ msgmerge -U po/af.po po/git-gui.pot
+
+[NEEDSWORK: who is responsible for updating po/git-gui.pot file by
+running xgettext?  IIRC, Christian recommended against running it
+nilly-willy because it can become a source of unnecessary merge
+conflicts.  Perhaps we should mention something like "
+
+The po/git-gui.pot file is updated by the internationalization
+coordinator from time to time.  You _could_ update it yourself, but
+translators are discouraged from doing so because we would want all
+language teams to be working off of the same version of git-gui.pot.
+
+" here?]
+
+This updates po/af.po (again, replace "af" with your language
+code) so that it contains msgid lines (i.e. the original) that
+your translation did not have before.  There are a few things to
+watch out for:
+
+ - The original text in English of an older message you already
+   translated might have been changed.  You will notice a comment line
+   that begins with "#, fuzzy" in front of such a message.  msgmerge
+   tool made its best effort to match your old translation with the
+   message from the updated software, but you may find cases that it
+   matched your old translated message to a new msgid and the pairing
+   does not make any sense -- you would need to fix them, and then
+   remove the "#, fuzzy" line from the message.
+
+ - New messages added to the software will have msgstr lines
+   with empty strings.  You would need to translate them.
+

Re: git-gui: i18n introductory document (2nd draft)

[しらいしななこ]

Quoting Junio C Hamano <gitster@pobox.com>:

> This short note is to help a translation contributor to help us
> localizing git-gui message files by covering the basics.

Thank you for this document, and thank you for helping me the
other day with my translations.

I tried to follow your message and updated my Japanese
translation.  Almost everything worked as described, but this
part.

> +After setting up such a symbolic link, you can:
> +
> +	$ make
> +	$ LANG=af ./git-gui
> +
> +[NEEDSWORK: this symlink trick needs to be verified if it works.]

I used LANG=ja instead; this did not work.  A "fatal error"
dialog said:

	couldn't open "/home/nanako/git/share/git-gui/lib/tclIndex":
	no such file or directory

But this worked:

	$ LANG=ja ./git-gui.sh

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Get a free email address with REAL anti-spam protection.
http://www.bluebottle.com/tag/1

Re: git-gui: i18n introductory document (2nd draft)

[VMiklos]

[-- Attachment #1: Type: text/plain, Size: 192 bytes --]

Hello,

Na Thu, Jul 26, 2007 at 04:31:06PM -0700, Junio C Hamano <gitster@pobox.com> pisal(a):
> +	$ cd git-gui-i18n.git

this should be git-gui-i18n (no .git), if i'm not wrong :)

- VMiklos

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: git-gui: i18n introductory document (2nd draft)

[Christian Stimming]

Junio C Hamano <gitster@pobox.com> schrieb am 27.07.2007 01:31:06:
> I have tried to address issues raised in Christian's comments on
> the first draft that was circulated privately.

Yes, this looks very nice, concise, and good to read. Thanks.

> +to test the resulting translation out.  It also is a good idea to have
> +specialized so-called "po file editors" (e.g. emacs po-mode, KBabel,
> +poedit, GTranslator).  Please install them.

I'd rephrase the very last sentence into: Please install at least one of
them, whichever you feel comfortably with.

> + - Often the messages being translated are format strings given to
> +   "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
> +   translated messages match the original.
> +
> +   When you have to change the order of words, you can add "<number>$"
> +   between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
> +   parameter to the format string is used at this point".  For example,
> +   if the original message is like this:
> +
> +   "Length is %d, Weight is %d"
> +
> +   and if for whatever reason your translation needs to say weight first
> +   and then length, you can say something like:
> +
> +   "WEIGHT IS %2$d, LENGTH IS %1$d"
> +
> +   [NEEDSWORK: this whole "parameter permutation" part needs to be
> +   verified if it works with Tcl at all]

I agree it needs to be verified, although the msgcat documentation claims
it works. Nevertheless I'd rather question whether this text is helpful at
this point in the document. How about moving the "positional codes" issues
to a separate section at the end, under the topic "Advanced translation
tips" or something like this?

> +You can test your translation by running "make install", which would
> +create po/af.msg file and installs the result, and then running the
> +resulting git-gui under your locale:
> +
> +   $ make install
> +   $ LANG=af git-gui

Right, this should always work.

> +There is a trick to test your translation without first installing, if
> +you prefer.  First, create this symbolic link in the source tree:
> +
> +   $ ln -s ../po lib/msgs
> +
> +After setting up such a symbolic link, you can:
> +
> +   $ make
> +   $ LANG=af ./git-gui
> +
> +[NEEDSWORK: this symlink trick needs to be verified if it works.]

It does work, but as Nanako Shiraishi already pointed out, one has to call
./git-gui.sh in contrast to the version without suffix.

> +   $ msgmerge -U po/af.po po/git-gui.pot
> +
> +[NEEDSWORK: who is responsible for updating po/git-gui.pot file by
> +running xgettext?  IIRC, Christian recommended against running it
> +nilly-willy because it can become a source of unnecessary merge
> +conflicts.  Perhaps we should mention something like "
> +
> +The po/git-gui.pot file is updated by the internationalization
> +coordinator from time to time.  You _could_ update it yourself, but
> +translators are discouraged from doing so because we would want all
> +language teams to be working off of the same version of git-gui.pot.
> +
> +" here?]

I wouldn't have put git-gui.pot into git to start with. Translators who can
msgmerge their translation by definition have the gettext toolchain
available, so they could very well just have git-gui.pot generated
themselves. We can just as well give instructions here on how to regenerate
git-gui.pot: "make po/git-gui.pot"; in gnucash, we added a separate rule
"make pot" because that one is easier to type.

As for merging the po file: I would encourage every *translator* to
"msgmerge" their po file as often as they like. This rule will only run
into problems if translators forget to merge their po file regularly, and
continue to work on the old string; so far I have no solution to this
problem.  I spoke up a few days ago to ask the maintainers not to merge the
*po* files, because this is where the translators work with, and merging
conflicts here will make translators unhappy. But this concerns the *po
file*. The pot file can just as well be updated by the maintainers or the
translators, but it would be best not to have it in SCM at all.

> + - The original text in English of an older message you already
> +   translated might have been changed.  You will notice a comment line
> +   that begins with "#, fuzzy" in front of such a message.  msgmerge
> +   tool made its best effort to match your old translation with the
> +   message from the updated software, but you may find cases that it
> +   matched your old translated message to a new msgid and the pairing
> +   does not make any sense -- you would need to fix them, and then
> +   remove the "#, fuzzy" line from the message.

I would add the sentence (because people frequently forget about the
implications of the fuzzy marker): A translation prepended by the '#,
fuzzy" line will not show up in the program. Gettext will treat this
message as if no translation existed.

Overall this is very nice. Thanks a lot.

Christian

IBEO Automobile Sensor GmbH - Sitz: Hamburg - Handelsregister: Hamburg HRB
67903
Geschäftsführer: Dr. Ulrich S. Lages

Re: git-gui: i18n introductory document (2nd draft)

[Junio C Hamano]

My thanks go to Nana, VMiklos, Christian and Brett for their
feedbacks to the draft.

It quickly gets cumbersome, both for myself and reviewers, to go
back and forth sending the whole of Nth draft every time on the
mailing list.  At the same time, I can not really afford to be
in the translation business myself, so I'd like to let this
document go in the best shape I could make, and have people more
competent around gettext than me to take it over.

I've updated the document somewhat and pushed it out to the mob
branch.  The issues I addressed:

 * "Running without installing does not work with ./git-gui, but
   with ./git-gui.sh" (Nana).

 * After the initial cloning, resulting local directory is
   git-gui-i18n, not git-gui-i18n.git (VMiklos).

 * "Please install them" (Christian).  I meant by "them", git,
   gettext and any one of po editors.  I reworded the example
   enumeration of available po editors to make it clear the
   translator needs only one.

 * "Parameter permutation needs $ sign quoted" (Brett).

 * "Message marked with '# ,fuzzy' are not used -- remove the
   fuzzy marker when you are done" (Christian).

I did not address the following issues, not because I did not
agree with the comments, but because I felt Christian is more
qualified to do these kinds of things.

 * "Parameter permutation" should be in a separate "Advanced
   translation" section (Christian). 

 * "po/git-gui.pot" should be generated by translators any time,
   and other workflow improvements regarding merging of the po
   files (Christian).

Re: git-gui: i18n introductory document (2nd draft)

[Brett Schwarz]

> ----- Original Message ----
> From: Christian Stimming <Christian.Stimming@ibeo-as.com>
> To: Junio C Hamano <gitster@pobox.com>
> Cc: git@vger.kernel.org; Irina Riesen <irina.riesen@gmail.com>; Johannes Schindelin <johannes.schindelin@gmx.de>; Nanako Shiraishi <nanako3@bluebottle.com>; Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>; Shawn O. Pearce <spearce@spearce.org>; Xudong Guan <xudong.guan@gmail.com>; stimming@tuhh.de
> Sent: Friday, July 27, 2007 8:21:58 AM
> Subject: Re: git-gui: i18n introductory document (2nd draft)
>
> Junio C Hamano <gitster@pobox.com> schrieb am 27.07.2007 01:31:06:
> > I have tried to address issues raised in Christian's comments on
> > the first draft that was circulated privately.
>

<snip>

>
> > + - Often the messages being translated are format strings given to
> > +   "printf()"-like functions.  Make sure "%s", "%d", and "%%" in your
> > +   translated messages match the original.
> > +
> > +   When you have to change the order of words, you can add "<number>$"
> > +   between '%' and the conversion ('s', 'd', etc.) to say "<number>-th
> > +   parameter to the format string is used at this point".  For example,
> > +   if the original message is like this:
> > +
> > +   "Length is %d, Weight is %d"
> > +
> > +   and if for whatever reason your translation needs to say weight first
> > +   and then length, you can say something like:

> > +
> > +   "WEIGHT IS %2$d, LENGTH IS %1$d"

Since we are using quotes for the strings, and Tcl will do a round of substitutions
 and will think those $d's are variables, you might want to change that to:

        "WEIGHT IS %2\$d, LENGTH IS %1\$d"

You also may want to add a note about why the backslash

> > +
> > +   [NEEDSWORK: this whole "parameter permutation" part needs to be
> > +   verified if it works with Tcl at all]
>

bschwarz@desk1:~$ tclsh
% package require msgcat
1.3.4
% namespace import ::msgcat::*
% mcset en_us_brett "L is %d, W is %d" "WEIGHT IS %2\$d, LENGTH IS %1\$d" 
WEIGHT IS %2$d, LENGTH IS %1$d
% mcset en_us "L is %d, W is %d" "Length is %d, Weight is %d"
Length is %d, Weight is %d
% mclocale en_us
en_us
% set length 74
74
% set weight 220
220
% mc "L is %d, W is %d" $length $weight
Length is 74, Weight is 220
% mclocale en_us_brett
en_us_brett
% mc "L is %d, W is %d" $length $weight
WEIGHT IS 220, LENGTH IS 74
% 

Seems to work...

Regards,
     --brett




       
____________________________________________________________________________________
Get the free Yahoo! toolbar and rest assured with the added security of spyware protection.
http://new.toolbar.yahoo.com/toolbar/features/norton/index.php