i18n of git man pages

i18n of git man pages

[Helge Kreutzmann]

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

Hello,
I'm maintainer of manpages-l10n[1], a collection of translations of man
pages for over 100 projects into many languages. 

Our policy is to move translations into the upstream project where
possible. Only where projects are not interested in maintaining the
translations for their man pages themselves we host them[2].

Recently one of our translators approached me to translate the man
pages for git. Before adding them, I want to check with you if you are
interested in adding translations of the man pages directly in the git
project. 

(Technically, po4a has been proven to be a good tool to maintain
man page translations).

Thanks for considering i18n your man page part.

Greetings

         Helge


[1]
https://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html

[2] We collected many translated man pages from the web in the past
    and transferring them upstream is a (very) slow process.
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: i18n of git man pages

[Junio C Hamano]

Cc'ing folks who have shown interest in translated manual pages.

cf. 
https://lore.kernel.org/git/cb74f3b-c2e9-947f-8f89-f51e79b17825@softwolves.pp.se/
https://lore.kernel.org/git/11498572.Kui42GGras@cayenne/

Thanks.

Helge Kreutzmann <debian@helgefjell.de> writes:

> Hello,
> I'm maintainer of manpages-l10n[1], a collection of translations of man
> pages for over 100 projects into many languages. 
>
> Our policy is to move translations into the upstream project where
> possible. Only where projects are not interested in maintaining the
> translations for their man pages themselves we host them[2].
>
> Recently one of our translators approached me to translate the man
> pages for git. Before adding them, I want to check with you if you are
> interested in adding translations of the man pages directly in the git
> project. 
>
> (Technically, po4a has been proven to be a good tool to maintain
> man page translations).
>
> Thanks for considering i18n your man page part.
>
> Greetings
>
>          Helge
>
>
> [1]
> https://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html
>
> [2] We collected many translated man pages from the web in the past
>     and transferring them upstream is a (very) slow process.

Re: i18n of git man pages

[Helge Kreutzmann]

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

Hello Junio,
thanks.

Am Wed, May 08, 2024 at 10:26:35AM -0700 schrieb Junio C Hamano:
> cf. 
> https://lore.kernel.org/git/cb74f3b-c2e9-947f-8f89-f51e79b17825@softwolves.pp.se/
> https://lore.kernel.org/git/11498572.Kui42GGras@cayenne/

This mentions https://github.com/jnavila/git-manpages-l10n, so I can
point our translator to this source.

This should be shipped somehow, of course, by the distributions.

And the problem mentioned in this post can be solved by carefully
designed compendia, so that translations are reused whenever possible.

Also the "problem" about line numbers and diffs is not problem at all,
if you set up po4a approriately, I'm happy diffing po files all the
time (and git blame remains meaningful as well). 

Greetings

          Helge
-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: i18n of git man pages

[Junio C Hamano]

Helge Kreutzmann <debian@helgefjell.de> writes:

> This mentions https://github.com/jnavila/git-manpages-l10n, so I can
> point our translator to this source.

That is a good move.

Perhaps we should make the manpage l10n project easier to discover
on our end to help volunteers.

Possible places are the "SubmittingPatches" document in our tree,
and "the Notes from the maintainer" letter that are sent out after
major releases.

Jean-Noël, how does the following look?

Thanks.

 Documentation/SubmittingPatches | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index 384893be1c..b36b3d9919 100644
--- c/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -562,6 +562,13 @@ repositories.
 
 Patches to these parts should be based on their trees.
 
+- The "Git documentation translations" project, led by Jean-Noël
+  Avila, translates our documentation pages.  Theire work products are
+  maintained separately from this project:
+
+	https://github.com/jnavila/git-manpages-l10n/
+
+
 [[patch-flow]]
 == An ideal patch flow
 

Re: i18n of git man pages

[Peter Krefting]

Junio C Hamano:

>> This mentions https://github.com/jnavila/git-manpages-l10n, so I can
>> point our translator to this source.
> That is a good move.
>
> Perhaps we should make the manpage l10n project easier to discover
> on our end to help volunteers.

Should it also be merged into the git.git repository as well, so that 
translation can be synced with the upstream version? The problem with 
an external project is that it is easy to forget about.


Looks like I had cloned the repo and intended to do a Swedish 
translation back in 2019, but never got around to. I guess the lack of 
visibility made me forget all about it.

-- 
\\// Peter - http://www.softwolves.pp.se/

Re: i18n of git man pages

[Junio C Hamano]

Peter Krefting <peter@softwolves.pp.se> writes:

> Should it also be merged into the git.git repository as well, so that
> translation can be synced with the upstream version? The problem with
> an external project is that it is easy to forget about.

Carrying an extra tree that has been (and I suspect will continue to
be) managed in a separate workflow and by a separate group does
incur coordination cost.

> Looks like I had cloned the repo and intended to do a Swedish
> translation back in 2019, but never got around to. I guess the lack of
> visibility made me forget all about it.

It is exactly why you are seeing a proposed solution to raise the
visibility that is much lightweight and has less chance of doing
unnecessary harm than merging of the project into ours.  The help
the would-be translators need will be there.   To end-users, I do
not think it matters in today's world where the manpages come from.
The distro folks are there to absorb different ways translated
manual pages are done by different projects, and I can hardly
believe that our project is in any way unique.

I would like to hear from Jean-Noël how the manpage translation
project wants to proceed.  I do not fundamentally object to taking
an approach similar to the one we use to manage the po/ part of our
project, where I can normally be unaware of what happens in that
directory and leave it to i18n coordinator, but I have a feeling
that even such a light-weight integration might affect their
workflows at the manpage translation project side, which may or may
not be acceptable on their end.  Also to go from the work product
they have to what our "make -C Documentation all" produces, it may
require more build dependencies (like a version of po4a with a patch
or two that are yet to be accepted by the upstream), plus updates to
Documentation/Makefile, on our side, which might turn out to be an
overly high cost relative to the benefits both projects gain.  These
unknowns need to be resolved before we consider heavier proposals.

Thanks.

Re: i18n of git man pages

[Jean-Noël AVILA]

On Thursday, 9 May 2024 18:10:30 CEST Junio C Hamano wrote:
> Peter Krefting <peter@softwolves.pp.se> writes:
> 
> > Should it also be merged into the git.git repository as well, so that
> > translation can be synced with the upstream version? The problem with
> > an external project is that it is easy to forget about.
> 
> Carrying an extra tree that has been (and I suspect will continue to
> be) managed in a separate workflow and by a separate group does
> incur coordination cost.

I totally agree with Junio. The workflow is different and it is already quite 
difficult to mix the long-running process of translation with the fast-paced 
life of patches in the documentation. Moreover, the translation needs to be 
opened to contributor who are not techno-friends and will not be able to 

> 
> > Looks like I had cloned the repo and intended to do a Swedish
> > translation back in 2019, but never got around to. I guess the lack of
> > visibility made me forget all about it.
> 
> It is exactly why you are seeing a proposed solution to raise the
> visibility that is much lightweight and has less chance of doing
> unnecessary harm than merging of the project into ours.  The help
> the would-be translators need will be there.   To end-users, I do
> not think it matters in today's world where the manpages come from.
> The distro folks are there to absorb different ways translated
> manual pages are done by different projects, and I can hardly
> believe that our project is in any way unique.

It is not unique in using asciidoc as a single source for documentation. In 
other projects that I know of, the documentation is a sister project in a 
dedicated repository. 

I try to present the translation of the man pages as coupled with the 
translation of git itself, for consistency purpose. The translation of git is 
already a large bite in itself (15481 segments at the moment), but the 
translation of the documentation (which only concerns a subset of the whole 
documentation) is really a beast:  73976 segment! 

The absence of visibility is mainly an issue from my side, due to a lack of 
communication. I could propose as a reminder to publish the translation stats 
for each new Git release, if it helps remind developers of the presence of 
this project. Honestly, this is not really the targeted audience for this kind 
of work. Currently the main source of translators has been through the little 
ad on https://git-scm.com, with most of the contributions coming from Weblate. 
Giving more visibility to the presence of translated content and to the 
project on git-scm.com or in the community of translators may have more impact 
than on  the git mailing list.
 
> 
> I would like to hear from Jean-Noël how the manpage translation
> project wants to proceed.  I do not fundamentally object to taking
> an approach similar to the one we use to manage the po/ part of our
> project, where I can normally be unaware of what happens in that
> directory and leave it to i18n coordinator, but I have a feeling
> that even such a light-weight integration might affect their
> workflows at the manpage translation project side, which may or may
> not be acceptable on their end.  Also to go from the work product
> they have to what our "make -C Documentation all" produces, it may
> require more build dependencies (like a version of po4a with a patch
> or two that are yet to be accepted by the upstream), plus updates to
> Documentation/Makefile, on our side, which might turn out to be an
> overly high cost relative to the benefits both projects gain.  These
> unknowns need to be resolved before we consider heavier proposals.
> 

Normally, I would synchronize to the releases of git, by updating the po files 
and  opening an update window when a rc is tagged. At the end of the release 
window, I would push a new version of translated asciidoc sources.

The translation process is not fully synchronous with the releases of Git. If 
a large chunk of translation changes has been proposed on weblate, I can push 
updated versions to the project and publish them on git-scm.com. Note that I'm 
not polyglot enough to be able to review the submissions, so except for checks 
on the asciidoc formatting itself (which is mostly scripted now), the 
submissions are accepted as-is, like in most translation projects.

The size of the translation files already gives some weight to the project. The 
current repo size is 50MB.

All this tells me that, except for the missing visibility, the current way of 
working is good, and trying to merge the doc translation of Git into the main 
repo would make more trouble than needed.

Regards,

JN

Re: i18n of git man pages

[Junio C Hamano]

Jean-Noël AVILA <avila.jn@gmail.com> writes:

> Giving more visibility to the presence of translated content and to the 
> project on git-scm.com or in the community of translators may have more impact 
> than on  the git mailing list.

Yeah, I agree that the set of people who read this message has only
a very small overlap with our target audience whose majority are
elsewhere.  But a small overlap is still an overlap, so...

> All this tells me that, except for the missing visibility, the current way of 
> working is good, and trying to merge the doc translation of Git into the main 
> repo would make more trouble than needed.

Thanks.

Re: i18n of git man pages

[Jean-Noël AVILA]

Hi Junio,

On Wednesday, 8 May 2024 22:12:02 CEST Junio C Hamano wrote:
> Helge Kreutzmann <debian@helgefjell.de> writes:
> 
> > This mentions https://github.com/jnavila/git-manpages-l10n, so I can
> > point our translator to this source.
> 
> That is a good move.
> 
> Perhaps we should make the manpage l10n project easier to discover
> on our end to help volunteers.
> 
> Possible places are the "SubmittingPatches" document in our tree,
> and "the Notes from the maintainer" letter that are sent out after
> major releases.
> 
> Jean-Noël, how does the following look?
> 
> Thanks.
> 
>  Documentation/SubmittingPatches | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
> index 384893be1c..b36b3d9919 100644
> --- c/Documentation/SubmittingPatches
> +++ w/Documentation/SubmittingPatches
> @@ -562,6 +562,13 @@ repositories.
>  
>  Patches to these parts should be based on their trees.
>  
> +- The "Git documentation translations" project, led by Jean-Noël
> +  Avila, translates our documentation pages.  Theire work products are
> +  maintained separately from this project:
> +
> +	https://github.com/jnavila/git-manpages-l10n/
> +
> +
>  [[patch-flow]]
>  == An ideal patch flow
>  
> 
> 
> 

This looks good to me. At some point, the repo should migrate to a dedicated organization (maybe git).

Best regards,

JN

Re: i18n of git man pages

[Jean-Noël AVILA]

On Wednesday, 8 May 2024 18:30:09 CEST Helge Kreutzmann wrote:
> Hello,
> I'm maintainer of manpages-l10n[1], a collection of translations of man
> pages for over 100 projects into many languages. 
> 
> Our policy is to move translations into the upstream project where
> possible. Only where projects are not interested in maintaining the
> translations for their man pages themselves we host them[2].
> 
> Recently one of our translators approached me to translate the man
> pages for git. Before adding them, I want to check with you if you are
> interested in adding translations of the man pages directly in the git
> project. 
> 
> (Technically, po4a has been proven to be a good tool to maintain
> man page translations).
> 
> Thanks for considering i18n your man page part.
> 
> Greetings
> 
>          Helge
> 
> 
> [1]
> https://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html
> 
> [2] We collected many translated man pages from the web in the past
>     and transferring them upstream is a (very) slow process.
> 

Hello,

I took in charge to provide translation of the man pages of git. The projects 
lives on https://github.com/jnavila/git-manpages-l10n 

As explained in the README file, the strategy has been to translate the sources 
asciidoc files, instead of managing the resulting man pages. Translating the 
source files of the man pages  is needed in order to publish them on git-
scm.com (single source principle), as well as because the sources files use 
asciidoc features such as dedicated macros, conditionals and includes. In 
order to lower the difficulty for translators, the repo is coupled with the 
online translation tool weblate[1] . 

Right now, I'm using a slightly modified version of po4a  for asciidoc (merge 
request pending). This translation gave also way to some improvements of 
asciidoc support for po4a. That's a two way development.

The project was submitted for inclusion in Debian, but lacking more support, 
the process was never achieved. I would be delighted to have the git-manpages 
included in the main distros. For Windows, the inclusion in the main package 
was rejected as it would make it even fatter.


Jean-Noël

[1] https://hosted.weblate.org/projects/git-manpages/