# Antwort: git-gui i18n introductory document 6 messages from 2007-07-26 to 2007-07-27. Participants: Christian Stimming, Junio C Hamano, しらいしななこ, VMiklos. Thread: https://gitlist.dev/t/9239 ## Christian Stimming, 2007-07-26 08:13 Subject: Antwort: git-gui i18n introductory document Message-ID: URL: https://gitlist.dev/e/OF1A666782.07EBF99C-ONC1257324.002B5B63-C1257324.002D39E0%40sick.de In-Reply-To: <7vir87adzo.fsf@assigned-by-dhcp.cox.net> ``` Junio C Hamano 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 ``` ## Junio C Hamano, 2007-07-26 23:31 Subject: git-gui: i18n introductory document (2nd draft) Message-ID: <7v4pjq7net.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7v4pjq7net.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <7vir87adzo.fsf@assigned-by-dhcp.cox.net> ``` 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 , 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 \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 "$" + between '%' and the conversion ('s', 'd', etc.) to say "-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. + ``` ## しらいしななこ, 2007-07-27 08:02 Subject: Re: git-gui: i18n introductory document (2nd draft) Message-ID: <200707270802.l6R82YpC013213@mi1.bluebottle.com> URL: https://gitlist.dev/e/200707270802.l6R82YpC013213%40mi1.bluebottle.com In-Reply-To: <7v4pjq7net.fsf@assigned-by-dhcp.cox.net> ``` Quoting Junio C Hamano : > 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 ``` ## VMiklos, 2007-07-27 11:13 Subject: Re: git-gui: i18n introductory document (2nd draft) Message-ID: <20070727111345.GY31655@genesis.frugalware.org> URL: https://gitlist.dev/e/20070727111345.GY31655%40genesis.frugalware.org In-Reply-To: <7v4pjq7net.fsf@assigned-by-dhcp.cox.net> ``` Hello, Na Thu, Jul 26, 2007 at 04:31:06PM -0700, Junio C Hamano pisal(a): > + $ cd git-gui-i18n.git this should be git-gui-i18n (no .git), if i'm not wrong :) - VMiklos ``` ## Christian Stimming, 2007-07-27 15:21 Subject: Re: git-gui: i18n introductory document (2nd draft) Message-ID: URL: https://gitlist.dev/e/OFE65F8F6D.096D98A3-ONC1257325.0052CC69-C1257325.0054663B%40sick.de In-Reply-To: <7v4pjq7net.fsf@assigned-by-dhcp.cox.net> ``` Junio C Hamano 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 "$" > + between '%' and the conversion ('s', 'd', etc.) to say "-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 ``` ## Junio C Hamano, 2007-07-27 23:18 Subject: Re: git-gui: i18n introductory document (2nd draft) Message-ID: <7vmyxhwi42.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7vmyxhwi42.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <7v4pjq7net.fsf@assigned-by-dhcp.cox.net> ``` 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). ```