# Translations in Git release? 15 messages from 2009-01-25 to 2009-01-27. Participants: Dill, Jeff King, Johannes Gilger, Peter Krefting, Jakub Narebski, Miklos Vajna, Mike Hommey, Sverre Rabbelier, Junio C Hamano. Thread: https://gitlist.dev/t/17353 ## Dill, 2009-01-25 17:41 Subject: Translations in Git release? Message-ID: <60646ee10901250941s34f7accem1b74fc201e895a41@mail.gmail.com> URL: https://gitlist.dev/e/60646ee10901250941s34f7accem1b74fc201e895a41%40mail.gmail.com ``` Is there a plan to include translations of the Documentation within Git or should they exist outside of the project? ``` ## Jeff King, 2009-01-25 18:54 Subject: Re: Translations in Git release? Message-ID: <20090125185447.GB12727@sigill.intra.peff.net> URL: https://gitlist.dev/e/20090125185447.GB12727%40sigill.intra.peff.net In-Reply-To: <60646ee10901250941s34f7accem1b74fc201e895a41@mail.gmail.com> ``` On Sun, Jan 25, 2009 at 10:41:02AM -0700, Dill wrote: > Is there a plan to include translations of the Documentation within > Git or should they exist outside of the project? I don't recall seeing any discussion on documentation translations previously. But there is some precedent for having translations in the tree, as git-gui's messages are translated into quite a few languages. -Peff ``` ## Johannes Gilger, 2009-01-26 09:54 Subject: Re: Translations in Git release? Message-ID: URL: https://gitlist.dev/e/glk19g%242f5%241%40ger.gmane.org In-Reply-To: <60646ee10901250941s34f7accem1b74fc201e895a41@mail.gmail.com> ``` On 2009-01-25, Dill wrote: > Is there a plan to include translations of the Documentation within > Git or should they exist outside of the project? My oppinion on localization of software (and its documentation) is generally a negative one. - People who use software like git are (in my experience) people who have a solid foundation of english, especially when it comes to computer-topics. - The effort that goes into translating the vast git documentation and keeping it up-to-date isn't small, energy better spent in other areas. - Translating a lot of technical terms into a language like german is really ugly and not fun to read. I always prefer reading english documentation and using non-localized versions of programs as it enables me to easier partake in discussions about it and also enables me to google for error messages without trying every different language the message could be in ;) But thats just me, if you want to start a translation effort knock yourself out Greetings, Jojo -- Johannes Gilger http://hackvalue.de/heipei/ GPG-Key: 0x42F6DE81 GPG-Fingerprint: BB49 F967 775E BB52 3A81 882C 58EE B178 42F6 DE81 ``` ## Peter Krefting, 2009-01-26 10:07 Subject: Re: Translations in Git release? Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0901261104060.7798%40ds9.cixit.se In-Reply-To: ``` Johannes Gilger: > My oppinion on localization of software (and its documentation) is > generally a negative one. That's the normal response from tech-savvy people. They usually dislike translations because they think it cannot convey the same ideas as the original. However, for a lot of less techy people, having to use software and read documentation in a non-native language *is* a big hurdle for using computers. That is especially true when it comes to complex software, such as Git. I would very much like to see the core git commands translated. The command-line svn client already talks Swedish to me (cvs does not, though), and I would be very happy to teach git the same. I already did translate git-gui and gitk, which was as much for my own benefit as others. -- \\// Peter - http://www.softwolves.pp.se/ ``` ## Jakub Narebski, 2009-01-26 12:31 Subject: Re: Translations [of Documentation] in Git release? Message-ID: URL: https://gitlist.dev/e/m3hc3mxn9d.fsf%40localhost.localdomain In-Reply-To: <60646ee10901250941s34f7accem1b74fc201e895a41@mail.gmail.com> ``` Dill writes: > Is there a plan to include translations of the Documentation within > Git or should they exist outside of the project? First, you should have mention that you are talking about translating _Documentation_, because there are at least three areas which can be translated: * GUI (gtik and git-gui), which is being done * Documentation, which leads to translated manpages and HTML docs * git command messages (but only porcelain, as scripts parse git command output) Second, the problem with translating Documentation is twofold. There is fundamental problem with translated documentation becoming out of sync (stale) unless you have people ready to follow changes to main documentation. This is less of a problem with GUI messages, as they change less frequently, there are shorter, and there is less volume of them. And there is technical problem of how to organize translations. With GUI translations we just use gettext conventions. I don't know any such convention for docs: there is suffix convention used by Apache to serve var language files (filename.txt.de, filename.txt.ja.euc-jp), and there is gettext-like convention of separate directories used by manpages (en/filename.txt, ja/filename.txt). And there is question where to put untranslated original... And to enhance Makefile to put translations in correct place. And possibly alter RPM .spec file to put translations in separate packages. So I am not sure if translated documentation should be not maintained out of tree... -- Jakub Narebski Poland ShadeHawk on #git ``` ## Peter Krefting, 2009-01-26 13:27 Subject: Re: Translations [of Documentation] in Git release? Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0901261426350.7798%40ds9.cixit.se In-Reply-To: ``` Jakub Narebski: > With GUI translations we just use gettext conventions. I don't know > any such convention for docs: There is a lot of documentation being translated using PO files. po4a - http://po4a.alioth.debian.org/ - is a nice starting point for that. -- \\// Peter - http://www.softwolves.pp.se/ ``` ## Miklos Vajna, 2009-01-26 13:34 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <20090126133420.GK21473@genesis.frugalware.org> URL: https://gitlist.dev/e/20090126133420.GK21473%40genesis.frugalware.org In-Reply-To: ``` On Mon, Jan 26, 2009 at 02:27:17PM +0100, Peter Krefting wrote: > There is a lot of documentation being translated using PO files. po4a - > http://po4a.alioth.debian.org/ - is a nice starting point for that. Actually it supports asciidoc files as well, but only the CVS version, so probably the po4a version installed on most machines (as a distro package) is not capable of managing asciidoc files. ``` ## Jakub Narebski, 2009-01-26 15:31 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <200901261631.18157.jnareb@gmail.com> URL: https://gitlist.dev/e/200901261631.18157.jnareb%40gmail.com In-Reply-To: ``` On Mon, 26 Jan 2009, Peter Krefting wrote: > Jakub Narebski wrote: > > > With GUI translations we just use gettext conventions. I don't know > > any such convention for docs: > > There is a lot of documentation being translated using PO files. po4a - > http://po4a.alioth.debian.org/ - is a nice starting point for that. I'm not sure if XLIFF wouldn't be better format to use to translate _documents_. Gettext was meant to translate, I think, not very long messages in programs. Also I am not sure how much support this idea has. True, in last Git User's Survey[1] 63% to 76% wanted (parts of) Documentation... but that was out of 325 people who answered this question, with 3236 responses to survey in total, so numbers are more like 6% - 8%. [1] http://git.or.cz/gitwiki/GitSurvey2008 [2] http://translate.sourceforge.net/wiki/ -- Jakub Narebski Poland ``` ## Mike Hommey, 2009-01-26 16:23 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <20090126162351.GA8911@glandium.org> URL: https://gitlist.dev/e/20090126162351.GA8911%40glandium.org In-Reply-To: <200901261631.18157.jnareb@gmail.com> ``` On Mon, Jan 26, 2009 at 04:31:17PM +0100, Jakub Narebski wrote: > On Mon, 26 Jan 2009, Peter Krefting wrote: > > Jakub Narebski wrote: > > > > > With GUI translations we just use gettext conventions. I don't know > > > any such convention for docs: > > > > There is a lot of documentation being translated using PO files. po4a - > > http://po4a.alioth.debian.org/ - is a nice starting point for that. > > I'm not sure if XLIFF wouldn't be better format to use to translate > _documents_. Gettext was meant to translate, I think, not very long > messages in programs. > > Also I am not sure how much support this idea has. True, in last Git > User's Survey[1] 63% to 76% wanted (parts of) Documentation... but that > was out of 325 people who answered this question, with 3236 responses > to survey in total, so numbers are more like 6% - 8%. On the other hand, the people who would really need the translations didn't answer the survey at all, since they couldn't read it. Mike ``` ## Sverre Rabbelier, 2009-01-26 19:30 Subject: Re: Translations [of Documentation] in Git release? Message-ID: URL: https://gitlist.dev/e/bd6139dc0901261130ic64f767gddc960ebe3dfecf2%40mail.gmail.com In-Reply-To: <20090126162351.GA8911@glandium.org> ``` On Mon, Jan 26, 2009 at 17:23, Mike Hommey wrote: > On the other hand, the people who would really need the translations > didn't answer the survey at all, since they couldn't read it. Perhaps the basics can be translated at least, the documents that do not require much change because they represent stable concepts? -- Cheers, Sverre Rabbelier ``` ## Dill, 2009-01-26 19:58 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <60646ee10901261158w65b539dida26d2bd3bae6903@mail.gmail.com> URL: https://gitlist.dev/e/60646ee10901261158w65b539dida26d2bd3bae6903%40mail.gmail.com In-Reply-To: <200901261631.18157.jnareb@gmail.com> ``` I was thinking of handling it like the Linux kernel documentation...? On 1/26/09, Jakub Narebski wrote: > On Mon, 26 Jan 2009, Peter Krefting wrote: >> Jakub Narebski wrote: >> >> > With GUI translations we just use gettext conventions. I don't know >> > any such convention for docs: >> >> There is a lot of documentation being translated using PO files. po4a - >> http://po4a.alioth.debian.org/ - is a nice starting point for that. > > I'm not sure if XLIFF wouldn't be better format to use to translate > _documents_. Gettext was meant to translate, I think, not very long > messages in programs. > > Also I am not sure how much support this idea has. True, in last Git > User's Survey[1] 63% to 76% wanted (parts of) Documentation... but that > was out of 325 people who answered this question, with 3236 responses > to survey in total, so numbers are more like 6% - 8%. > > [1] http://git.or.cz/gitwiki/GitSurvey2008 > [2] http://translate.sourceforge.net/wiki/ > > -- > Jakub Narebski > Poland > ``` ## Junio C Hamano, 2009-01-26 20:38 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <7vskn54xbt.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vskn54xbt.fsf%40gitster.siamese.dyndns.org In-Reply-To: <60646ee10901261158w65b539dida26d2bd3bae6903@mail.gmail.com> ``` Dill writes: > On 1/26/09, Jakub Narebski wrote: >> On Mon, 26 Jan 2009, Peter Krefting wrote: >>> Jakub Narebski wrote: >>> >>> > With GUI translations we just use gettext conventions. I don't know >>> > any such convention for docs: >>> >>> There is a lot of documentation being translated using PO files. po4a - >>> http://po4a.alioth.debian.org/ - is a nice starting point for that. >> >> I'm not sure if XLIFF wouldn't be better format to use to translate >> _documents_. Gettext was meant to translate, I think, not very long >> messages in programs. >> >> Also I am not sure how much support this idea has. True, in last Git >> User's Survey[1] 63% to 76% wanted (parts of) Documentation... but that >> was out of 325 people who answered this question, with 3236 responses >> to survey in total, so numbers are more like 6% - 8%. >> >> [1] http://git.or.cz/gitwiki/GitSurvey2008 >> [2] http://translate.sourceforge.net/wiki/ >> ... > I was thinking of handling it like the Linux kernel documentation...? By this, I understand you mean the model that lets the authors of the original English documentation be unaware of the presense of translations, and resulting translated files are placed in Documentation/??_??/ (where "??_??" are ja_JP, zh_CN, etc.) subdirectory. The approach obviously risks the translations to go stale very easily, but gives a nice separation of reponsibility and does not slow down the way the original documents are updated. I would actually prefer a directory structure "Documentation/translated/??_??/" so that people who are not involved in the translation do not have to see anything below _one_ directory (i.e. "translated"). If you step in as the Documentation translation coordinator to maintain such a tree structure that I can have as a submodule (or subtree merge) to git.git tree, you could talk me into updating my tree from time to time from your tree, but at that point we might actually want to have such a translation project as a separate and unrelated project. By the way, http://github.com/yasuaki/git-manual-jp.git/ has some Japanese translations (no, I am not involved in this any way, and I do not know about its current status). If you look at files in Documentation/ (not Documentation.ja) in that repository, you can see how they tried to make it easier to update the translation to match the original documentation set when the original gets updated. I do not know how well the approach works in practice, though. ``` ## Peter Krefting, 2009-01-27 07:01 Subject: Re: Translations [of Documentation] in Git release? Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0901270800100.26770%40ds9.cixit.se In-Reply-To: ``` Sverre Rabbelier: > Perhaps the basics can be translated at least, the documents that do > not require much change because they represent stable concepts? I usually start out translating the program output, then manual pages, and then, time permitting, documentation. Git is a bit special in that regard since "--help" gets hardwired to display the manual page, so one can't just translate the help screen. -- \\// Peter - http://www.softwolves.pp.se/ ``` ## Jakub Narebski, 2009-01-27 11:16 Subject: Re: Translations [of Documentation] in Git release? Message-ID: <200901271216.59687.jnareb@gmail.com> URL: https://gitlist.dev/e/200901271216.59687.jnareb%40gmail.com In-Reply-To: ``` On Tue, 27 Jan 2009, Peter Krefting wrote: > Sverre Rabbelier: > > > Perhaps the basics can be translated at least, the documents that do > > not require much change because they represent stable concepts? > > I usually start out translating the program output, then manual pages, > and then, time permitting, documentation. The problem with translating program output (program messages) in Git is twofold: fundamental and technical. Fundamental, that program output is considered API (at least for plumbing commands) and used when scripting (this might be ameliorated with "I am script" switch or environmental variable). Technical, because Git is mixture of programs in C, shell scripts, and Perl scripts, and you have to come with technical means of translating messages in all three of them. > Git is a bit special in that regard since "--help" gets hardwired to > display the manual page, so one can't just translate the help screen. Not in all cases. Sometimes it shows "long usage". Perhaps that should be made more consistent? -- Jakub Narebski Poland ``` ## Peter Krefting, 2009-01-27 14:45 Subject: Re: Translations [of Documentation] in Git release? Message-ID: URL: https://gitlist.dev/e/Pine.LNX.4.64.0901271541250.26770%40ds9.cixit.se In-Reply-To: <200901271216.59687.jnareb@gmail.com> ``` Jakub Narebski: > Fundamental, that program output is considered API (at least for > plumbing commands) and used when scripting (this might be ameliorated > with "I am script" switch or environmental variable). That's a bug. Protocol data (which one could consider the plumbing output to be) should never be forwarded to the end-user, except for debugging purposes. It is the porcelain's task here to translate the messages for the user. Plumbing commands could still output semi-readable English, but it is still to be considered protocol, and be hidden from the user. Having low-level protocol data filter through to the end-user is a common mistake in software, unfortunately, and makes internationalization and localization a lot harder. Of course, if the user insists on calling the plumbing commands directly, he will not get translated output. That's expected behaviour. > Technical, because Git is mixture of programs in C, shell scripts, > and Perl scripts, and you have to come with technical means of > translating messages in all three of them. Gettext has succesfully been used to translate messages in all of these environments, so that should not be a big problem. > Not in all cases. Sometimes it shows "long usage". Perhaps that > should be made more consistent? Consistency is good. -- \\// Peter - http://www.softwolves.pp.se/ ```