Subject: Re: i18n of git man pages

From: Jean-Noël AVILA <[email-masked]>
Date: Fri, 10 May 2024 09:39:02 +0200

On Thursday, 9 May 2024 18:10:30 CEST Junio C Hamano wrote:
> Peter Krefting <[email-masked]> 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