Translations in Git release?

Translations in Git release?

[Dill]

Is there a plan to include translations of the Documentation within
Git or should they exist outside of the project?

Re: Translations in Git release?

[Jeff King]

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

Re: Translations in Git release?

[Johannes Gilger]

On 2009-01-25, Dill <sarpulhu@gmail.com> 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 <heipei@hackvalue.de>
http://hackvalue.de/heipei/
GPG-Key: 0x42F6DE81
GPG-Fingerprint: BB49 F967 775E BB52 3A81  882C 58EE B178 42F6 DE81

Re: Translations in Git release?

[Peter Krefting]

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/

Re: Translations [of Documentation] in Git release?

[Jakub Narebski]

Dill <sarpulhu@gmail.com> 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

Re: Translations [of Documentation] in Git release?

[Peter Krefting]

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/

Re: Translations [of Documentation] in Git release?

[Miklos Vajna]

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

On Mon, Jan 26, 2009 at 02:27:17PM +0100, Peter Krefting <peter@softwolves.pp.se> 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.

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

Re: Translations [of Documentation] in Git release?

[Jakub Narebski]

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

Re: Translations [of Documentation] in Git release?

[Mike Hommey]

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

Re: Translations [of Documentation] in Git release?

[Sverre Rabbelier]

On Mon, Jan 26, 2009 at 17:23, Mike Hommey <mh@glandium.org> 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

Re: Translations [of Documentation] in Git release?

[Peter Krefting]

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/

Re: Translations [of Documentation] in Git release?

[Jakub Narebski]

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

Re: Translations [of Documentation] in Git release?

[Peter Krefting]

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/

Re: Translations [of Documentation] in Git release?

[Dill]

I was thinking of handling it like the Linux kernel documentation...?

On 1/26/09, Jakub Narebski <jnareb@gmail.com> 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
>

Re: Translations [of Documentation] in Git release?

[Junio C Hamano]

Dill <sarpulhu@gmail.com> writes:

> On 1/26/09, Jakub Narebski <jnareb@gmail.com> 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.