{"thread":{"id":"61435","subject":"i18n of git man pages","startedAt":"2024-05-08T16:35:18Z","lastAt":"2024-05-10T16:33:14Z","messageCount":10,"participants":["Helge Kreutzmann","Junio C Hamano","Jean-Noël AVILA","Peter Krefting"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"494326","messageId":"Zjuokc2H0zI1JCVH@meinfjell.helgefjelltest.de","threadId":"61435","inReplyTo":null,"subject":"i18n of git man pages","fromName":"Helge Kreutzmann","fromEmail":"debian@helgefjell.de","sentAt":"2024-05-08T16:30:09Z","receivedAt":"2024-05-08T16:35:18Z","isPatch":false,"sender":{"key":"debian@helgefjell.de","avatar":null},"body":"Hello,\nI'm maintainer of manpages-l10n[1], a collection of translations of man\npages for over 100 projects into many languages. \n\nOur policy is to move translations into the upstream project where\npossible. Only where projects are not interested in maintaining the\ntranslations for their man pages themselves we host them[2].\n\nRecently one of our translators approached me to translate the man\npages for git. Before adding them, I want to check with you if you are\ninterested in adding translations of the man pages directly in the git\nproject. \n\n(Technically, po4a has been proven to be a good tool to maintain\nman page translations).\n\nThanks for considering i18n your man page part.\n\nGreetings\n\n Helge\n\n\n[1]\nhttps://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html\n\n[2] We collected many translated man pages from the web in the past\n and transferring them upstream is a (very) slow process.\n-- \n Dr. Helge Kreutzmann debian@helgefjell.de\n Dipl.-Phys. http://www.helgefjell.de/debian.php\n 64bit GNU powered gpg signed mail preferred\n Help keep free software \"libre\": http://www.ffii.de/\n"},{"id":"494329","messageId":"xmqqjzk4xlis.fsf@gitster.g","threadId":"61435","inReplyTo":"Zjuokc2H0zI1JCVH@meinfjell.helgefjelltest.de","subject":"Re: i18n of git man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-08T17:26:35Z","receivedAt":"2024-05-08T17:26:46Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Cc'ing folks who have shown interest in translated manual pages.\n\ncf. \nhttps://lore.kernel.org/git/cb74f3b-c2e9-947f-8f89-f51e79b17825@softwolves.pp.se/\nhttps://lore.kernel.org/git/11498572.Kui42GGras@cayenne/\n\nThanks.\n\nHelge Kreutzmann writes:\n\n> Hello,\n> I'm maintainer of manpages-l10n[1], a collection of translations of man\n> pages for over 100 projects into many languages. \n>\n> Our policy is to move translations into the upstream project where\n> possible. Only where projects are not interested in maintaining the\n> translations for their man pages themselves we host them[2].\n>\n> Recently one of our translators approached me to translate the man\n> pages for git. Before adding them, I want to check with you if you are\n> interested in adding translations of the man pages directly in the git\n> project. \n>\n> (Technically, po4a has been proven to be a good tool to maintain\n> man page translations).\n>\n> Thanks for considering i18n your man page part.\n>\n> Greetings\n>\n> Helge\n>\n>\n> [1]\n> https://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html\n>\n> [2] We collected many translated man pages from the web in the past\n> and transferring them upstream is a (very) slow process.\n"},{"id":"494331","messageId":"ZjvHoykzIo34YJaT@meinfjell.helgefjelltest.de","threadId":"61435","inReplyTo":"xmqqjzk4xlis.fsf@gitster.g","subject":"Re: i18n of git man pages","fromName":"Helge Kreutzmann","fromEmail":"debian@helgefjell.de","sentAt":"2024-05-08T18:42:43Z","receivedAt":"2024-05-08T18:42:45Z","isPatch":false,"sender":{"key":"debian@helgefjell.de","avatar":null},"body":"Hello Junio,\nthanks.\n\nAm Wed, May 08, 2024 at 10:26:35AM -0700 schrieb Junio C Hamano:\n> cf. \n> https://lore.kernel.org/git/cb74f3b-c2e9-947f-8f89-f51e79b17825@softwolves.pp.se/\n> https://lore.kernel.org/git/11498572.Kui42GGras@cayenne/\n\nThis mentions https://github.com/jnavila/git-manpages-l10n, so I can\npoint our translator to this source.\n\nThis should be shipped somehow, of course, by the distributions.\n\nAnd the problem mentioned in this post can be solved by carefully\ndesigned compendia, so that translations are reused whenever possible.\n\nAlso the \"problem\" about line numbers and diffs is not problem at all,\nif you set up po4a approriately, I'm happy diffing po files all the\ntime (and git blame remains meaningful as well). \n\nGreetings\n\n Helge\n-- \n Dr. Helge Kreutzmann debian@helgefjell.de\n Dipl.-Phys. http://www.helgefjell.de/debian.php\n 64bit GNU powered gpg signed mail preferred\n Help keep free software \"libre\": http://www.ffii.de/\n"},{"id":"494332","messageId":"xmqqedacxdv1.fsf@gitster.g","threadId":"61435","inReplyTo":"ZjvHoykzIo34YJaT@meinfjell.helgefjelltest.de","subject":"Re: i18n of git man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-08T20:12:02Z","receivedAt":"2024-05-08T20:12:07Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Helge Kreutzmann writes:\n\n> This mentions https://github.com/jnavila/git-manpages-l10n, so I can\n> point our translator to this source.\n\nThat is a good move.\n\nPerhaps we should make the manpage l10n project easier to discover\non our end to help volunteers.\n\nPossible places are the \"SubmittingPatches\" document in our tree,\nand \"the Notes from the maintainer\" letter that are sent out after\nmajor releases.\n\nJean-Noël, how does the following look?\n\nThanks.\n\n Documentation/SubmittingPatches | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches\nindex 384893be1c..b36b3d9919 100644\n--- c/Documentation/SubmittingPatches\n+++ w/Documentation/SubmittingPatches\n@@ -562,6 +562,13 @@ repositories.\n \n Patches to these parts should be based on their trees.\n \n+- The \"Git documentation translations\" project, led by Jean-Noël\n+ Avila, translates our documentation pages. Theire work products are\n+ maintained separately from this project:\n+\n+\thttps://github.com/jnavila/git-manpages-l10n/\n+\n+\n [[patch-flow]]\n == An ideal patch flow\n \n\n\n"},{"id":"494347","messageId":"8450777.T7Z3S40VBb@cayenne","threadId":"61435","inReplyTo":"Zjuokc2H0zI1JCVH@meinfjell.helgefjelltest.de","subject":"Re: i18n of git man pages","fromName":"Jean-Noël AVILA","fromEmail":"avila.jn@gmail.com","sentAt":"2024-05-09T14:56:18Z","receivedAt":"2024-05-09T15:04:59Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Wednesday, 8 May 2024 18:30:09 CEST Helge Kreutzmann wrote:\n> Hello,\n> I'm maintainer of manpages-l10n[1], a collection of translations of man\n> pages for over 100 projects into many languages. \n> \n> Our policy is to move translations into the upstream project where\n> possible. Only where projects are not interested in maintaining the\n> translations for their man pages themselves we host them[2].\n> \n> Recently one of our translators approached me to translate the man\n> pages for git. Before adding them, I want to check with you if you are\n> interested in adding translations of the man pages directly in the git\n> project. \n> \n> (Technically, po4a has been proven to be a good tool to maintain\n> man page translations).\n> \n> Thanks for considering i18n your man page part.\n> \n> Greetings\n> \n> Helge\n> \n> \n> [1]\n> https://manpages-l10n-team.pages.debian.net/manpages-l10n/index.html\n> \n> [2] We collected many translated man pages from the web in the past\n> and transferring them upstream is a (very) slow process.\n> \n\nHello,\n\nI took in charge to provide translation of the man pages of git. The projects \nlives on https://github.com/jnavila/git-manpages-l10n \n\nAs explained in the README file, the strategy has been to translate the sources \nasciidoc files, instead of managing the resulting man pages. Translating the \nsource files of the man pages is needed in order to publish them on git-\nscm.com (single source principle), as well as because the sources files use \nasciidoc features such as dedicated macros, conditionals and includes. In \norder to lower the difficulty for translators, the repo is coupled with the \nonline translation tool weblate[1] . \n\nRight now, I'm using a slightly modified version of po4a for asciidoc (merge \nrequest pending). This translation gave also way to some improvements of \nasciidoc support for po4a. That's a two way development.\n\nThe project was submitted for inclusion in Debian, but lacking more support, \nthe process was never achieved. I would be delighted to have the git-manpages \nincluded in the main distros. For Windows, the inclusion in the main package \nwas rejected as it would make it even fatter.\n\n\nJean-Noël\n\n[1] https://hosted.weblate.org/projects/git-manpages/\n\n\n"},{"id":"494348","messageId":"d130d861-0071-33ef-5d40-9fd703ff97f6@softwolves.pp.se","threadId":"61435","inReplyTo":"xmqqedacxdv1.fsf@gitster.g","subject":"Re: i18n of git man pages","fromName":"Peter Krefting","fromEmail":"peter@softwolves.pp.se","sentAt":"2024-05-09T14:39:41Z","receivedAt":"2024-05-09T15:12:01Z","isPatch":false,"sender":{"key":"peter@softwolves.pp.se","avatar":"https://avatars.githubusercontent.com/u/990764?v=4"},"body":"Junio C Hamano:\n\n>> This mentions https://github.com/jnavila/git-manpages-l10n, so I can\n>> point our translator to this source.\n> That is a good move.\n>\n> Perhaps we should make the manpage l10n project easier to discover\n> on our end to help volunteers.\n\nShould it also be merged into the git.git repository as well, so that \ntranslation can be synced with the upstream version? The problem with \nan external project is that it is easy to forget about.\n\n\nLooks like I had cloned the repo and intended to do a Swedish \ntranslation back in 2019, but never got around to. I guess the lack of \nvisibility made me forget all about it.\n\n-- \n\\\\// Peter - http://www.softwolves.pp.se/\n"},{"id":"494353","messageId":"xmqqr0ebuft5.fsf@gitster.g","threadId":"61435","inReplyTo":"d130d861-0071-33ef-5d40-9fd703ff97f6@softwolves.pp.se","subject":"Re: i18n of git man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-09T16:10:30Z","receivedAt":"2024-05-09T16:10:33Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Peter Krefting writes:\n\n> Should it also be merged into the git.git repository as well, so that\n> translation can be synced with the upstream version? The problem with\n> an external project is that it is easy to forget about.\n\nCarrying an extra tree that has been (and I suspect will continue to\nbe) managed in a separate workflow and by a separate group does\nincur coordination cost.\n\n> Looks like I had cloned the repo and intended to do a Swedish\n> translation back in 2019, but never got around to. I guess the lack of\n> visibility made me forget all about it.\n\nIt is exactly why you are seeing a proposed solution to raise the\nvisibility that is much lightweight and has less chance of doing\nunnecessary harm than merging of the project into ours. The help\nthe would-be translators need will be there. To end-users, I do\nnot think it matters in today's world where the manpages come from.\nThe distro folks are there to absorb different ways translated\nmanual pages are done by different projects, and I can hardly\nbelieve that our project is in any way unique.\n\nI would like to hear from Jean-Noël how the manpage translation\nproject wants to proceed. I do not fundamentally object to taking\nan approach similar to the one we use to manage the po/ part of our\nproject, where I can normally be unaware of what happens in that\ndirectory and leave it to i18n coordinator, but I have a feeling\nthat even such a light-weight integration might affect their\nworkflows at the manpage translation project side, which may or may\nnot be acceptable on their end. Also to go from the work product\nthey have to what our \"make -C Documentation all\" produces, it may\nrequire more build dependencies (like a version of po4a with a patch\nor two that are yet to be accepted by the upstream), plus updates to\nDocumentation/Makefile, on our side, which might turn out to be an\noverly high cost relative to the benefits both projects gain. These\nunknowns need to be resolved before we consider heavier proposals.\n\nThanks.\n"},{"id":"494394","messageId":"3298196.44csPzL39Z@cayenne","threadId":"61435","inReplyTo":"xmqqr0ebuft5.fsf@gitster.g","subject":"Re: i18n of git man pages","fromName":"Jean-Noël AVILA","fromEmail":"avila.jn@gmail.com","sentAt":"2024-05-10T07:39:02Z","receivedAt":"2024-05-10T07:39:05Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Thursday, 9 May 2024 18:10:30 CEST Junio C Hamano wrote:\n> Peter Krefting writes:\n> \n> > Should it also be merged into the git.git repository as well, so that\n> > translation can be synced with the upstream version? The problem with\n> > an external project is that it is easy to forget about.\n> \n> Carrying an extra tree that has been (and I suspect will continue to\n> be) managed in a separate workflow and by a separate group does\n> incur coordination cost.\n\nI totally agree with Junio. The workflow is different and it is already quite \ndifficult to mix the long-running process of translation with the fast-paced \nlife of patches in the documentation. Moreover, the translation needs to be \nopened to contributor who are not techno-friends and will not be able to \n\n> \n> > Looks like I had cloned the repo and intended to do a Swedish\n> > translation back in 2019, but never got around to. I guess the lack of\n> > visibility made me forget all about it.\n> \n> It is exactly why you are seeing a proposed solution to raise the\n> visibility that is much lightweight and has less chance of doing\n> unnecessary harm than merging of the project into ours. The help\n> the would-be translators need will be there. To end-users, I do\n> not think it matters in today's world where the manpages come from.\n> The distro folks are there to absorb different ways translated\n> manual pages are done by different projects, and I can hardly\n> believe that our project is in any way unique.\n\nIt is not unique in using asciidoc as a single source for documentation. In \nother projects that I know of, the documentation is a sister project in a \ndedicated repository. \n\nI try to present the translation of the man pages as coupled with the \ntranslation of git itself, for consistency purpose. The translation of git is \nalready a large bite in itself (15481 segments at the moment), but the \ntranslation of the documentation (which only concerns a subset of the whole \ndocumentation) is really a beast: 73976 segment! \n\nThe absence of visibility is mainly an issue from my side, due to a lack of \ncommunication. I could propose as a reminder to publish the translation stats \nfor each new Git release, if it helps remind developers of the presence of \nthis project. Honestly, this is not really the targeted audience for this kind \nof work. Currently the main source of translators has been through the little \nad on https://git-scm.com, with most of the contributions coming from Weblate. \nGiving more visibility to the presence of translated content and to the \nproject on git-scm.com or in the community of translators may have more impact \nthan on the git mailing list.\n \n> \n> I would like to hear from Jean-Noël how the manpage translation\n> project wants to proceed. I do not fundamentally object to taking\n> an approach similar to the one we use to manage the po/ part of our\n> project, where I can normally be unaware of what happens in that\n> directory and leave it to i18n coordinator, but I have a feeling\n> that even such a light-weight integration might affect their\n> workflows at the manpage translation project side, which may or may\n> not be acceptable on their end. Also to go from the work product\n> they have to what our \"make -C Documentation all\" produces, it may\n> require more build dependencies (like a version of po4a with a patch\n> or two that are yet to be accepted by the upstream), plus updates to\n> Documentation/Makefile, on our side, which might turn out to be an\n> overly high cost relative to the benefits both projects gain. These\n> unknowns need to be resolved before we consider heavier proposals.\n> \n\nNormally, I would synchronize to the releases of git, by updating the po files \nand opening an update window when a rc is tagged. At the end of the release \nwindow, I would push a new version of translated asciidoc sources.\n\nThe translation process is not fully synchronous with the releases of Git. If \na large chunk of translation changes has been proposed on weblate, I can push \nupdated versions to the project and publish them on git-scm.com. Note that I'm \nnot polyglot enough to be able to review the submissions, so except for checks \non the asciidoc formatting itself (which is mostly scripted now), the \nsubmissions are accepted as-is, like in most translation projects.\n\nThe size of the translation files already gives some weight to the project. The \ncurrent repo size is 50MB.\n\nAll this tells me that, except for the missing visibility, the current way of \nworking is good, and trying to merge the doc translation of Git into the main \nrepo would make more trouble than needed.\n\nRegards,\n\nJN\n\n\n"},{"id":"494470","messageId":"xmqqseyp657h.fsf@gitster.g","threadId":"61435","inReplyTo":"3298196.44csPzL39Z@cayenne","subject":"Re: i18n of git man pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-10T15:45:38Z","receivedAt":"2024-05-10T15:45:46Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA writes:\n\n> Giving more visibility to the presence of translated content and to the \n> project on git-scm.com or in the community of translators may have more impact \n> than on the git mailing list.\n\nYeah, I agree that the set of people who read this message has only\na very small overlap with our target audience whose majority are\nelsewhere. But a small overlap is still an overlap, so...\n\n> All this tells me that, except for the missing visibility, the current way of \n> working is good, and trying to merge the doc translation of Git into the main \n> repo would make more trouble than needed.\n\nThanks.\n"},{"id":"494474","messageId":"1968476.PYKUYFuaPT@cayenne","threadId":"61435","inReplyTo":"xmqqedacxdv1.fsf@gitster.g","subject":"Re: i18n of git man pages","fromName":"Jean-Noël AVILA","fromEmail":"avila.jn@gmail.com","sentAt":"2024-05-10T16:33:11Z","receivedAt":"2024-05-10T16:33:14Z","isPatch":false,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Hi Junio,\n\nOn Wednesday, 8 May 2024 22:12:02 CEST Junio C Hamano wrote:\n> Helge Kreutzmann writes:\n> \n> > This mentions https://github.com/jnavila/git-manpages-l10n, so I can\n> > point our translator to this source.\n> \n> That is a good move.\n> \n> Perhaps we should make the manpage l10n project easier to discover\n> on our end to help volunteers.\n> \n> Possible places are the \"SubmittingPatches\" document in our tree,\n> and \"the Notes from the maintainer\" letter that are sent out after\n> major releases.\n> \n> Jean-Noël, how does the following look?\n> \n> Thanks.\n> \n> Documentation/SubmittingPatches | 7 +++++++\n> 1 file changed, 7 insertions(+)\n> \n> diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches\n> index 384893be1c..b36b3d9919 100644\n> --- c/Documentation/SubmittingPatches\n> +++ w/Documentation/SubmittingPatches\n> @@ -562,6 +562,13 @@ repositories.\n> \n> Patches to these parts should be based on their trees.\n> \n> +- The \"Git documentation translations\" project, led by Jean-Noël\n> + Avila, translates our documentation pages. Theire work products are\n> + maintained separately from this project:\n> +\n> +\thttps://github.com/jnavila/git-manpages-l10n/\n> +\n> +\n> [[patch-flow]]\n> == An ideal patch flow\n> \n> \n> \n> \n\nThis looks good to me. At some point, the repo should migrate to a dedicated organization (maybe git).\n\nBest regards,\n\nJN\n\n\n"}]}