Menu
▾
▴
#47 Clarifying handling of localized man pages
Hello Phil,
hello Bernd,
I'm the Debian maintainer for manpages-l10n, a collection of man page
translations (from over 100 sources).
Recently the German translation of ethers.5 was added, however, it was
discovered that you as upstream already ship it. As this is a file
conflict, manpages-de will not ship it but only you as upstream. See
e.g. https://bugs.debian.org/1017006 for details.
manpages-l10n also contains a Spanish translation of ether.5. And
manpages-ja (not related to manpages-l10n) contains it as well.
I noticed that you ship several translations, namely German, French
and Brazilian Portugese, however, without any support for keeping the
translations in sync with the original (e.g. using po4a, itstool, ..).
There are three options how to resolve this:
1. You keep only the translations as is and maybe work with me and
Ralf (in CC) how to update the translation of ether.5, as it
contains a few "bugs". The Spanish translations would come from
manpages-es, as before. For your other manpages I would contact you
if translations into any of "your" languages would appear.
-
You don't ship any translation and manpages-l10n would import the
current set. In the future, manpages-de, manpages-fr and
manpages-pt_BR would maintain and ship these manpages. As we use
po4a, they would be aligned with your changes, but of course with a
delay (from a few weeks up to several months). Of course we would
invite the previous translators to join manpages-l10n and keep
working on them, if they like. -
You integrate po4a to properly maintain language translations (this
is not difficult and would need to extend your current manpage
generation Makefile).
Pending on my time, I could help you on this, but I would
definitely help you integrate the German and Spanish translations.
This way translators would work with you directly and you always
ship up to date translations yourself (depending on the availability
of the translators, of course).
My preference would be 3., followed by 2., followed by 1. (I would
really love to avoid 1.).
If you have any further questions regarding these options, please let
me know.
If I don't hear from you by mid October, I assume option 1. is valid.
If so, I would approach Ralf to work on the translation for
ether.5
Greetings
Helge
if the canonical ethers(5) is maintained in net-tools, then it makes sense to include translations in here too
Hello,
I don’t really have a plan or idea about translations. We regularly accept pull requests but have no means to verify or refresh them. If you have a better source in Debian feel free toexclude those files from the package. However i would feel the natural place to keep those contributions would be in the upstream project. So if you have a fixed ether.5 please send the patch.
same is probably true for adding po4a (but i dont know what it is and what it is used for)
Gruss
Bernd
Hello Bernd,
as far as I can see Debian is shipping your English man pages and your translated man pages. As do other distributions as well. So while I'm taking the example of Debian, there is nothing specific in respect to Debian here.
For me, having you handle the translations alongside your English version is a good option.
As translations get outdated over time (as you work on the English original), you need a tool to manage the translations and provide yourself, your translators and your users reading the translated version a good experience.
Po4a is a common tool for this. Essentially, it takes your English original man pages, automatically transforms it into an intermediate representation (po files) which are easy to handle for translators. When preparing a release, po4a automatically creates the translated version. For each paragraph it checks if a current translation is present. If so, it is used, if not, the English text is used. This way, your users get as much translation as possible, but never outdated content. (There are a few more details, but this is the basics).
If you are interested, I can help you integrate po4a , integrate the translations from manpages-l10n and convert your current translations. If you want, I can have a look at your build system next weekend.
You can find Po4a here: https://www.po4a.org/
Once you have the infrastructure in place, it is rather easy to add new man pages or drop retried ones.
hello Helge,
we are not doing translations ourself, we just merged request from helpful contributors. how they do the translation or corrections I am not sure. They might have used po4a before. They can always run the tool themself.
but if you think we can aid that process with an addition to the makefile, i am all for it. i will merge such a patch (i am just not planning to read up on this translation tool. keep in mind net-tools is mostly obsolete these days.)
but i think that was not the point of the initial issue. the initial question was if we want to ship our translated manpages and i think the answer is, yes, if we have them. for ether(5) we need to decide if we need a new owner. alternatively we can just keep shipping it but fistributions are free to replace all files with better versions (ideally contribute them back).
gruss
bernd
Yes, the translations themselves come from contributors. However, currently they cannot detect (easily) if you changed the original. With po4a and the po format it is straightforward.
However, po4a is nothing to be used by translators. For this system to work, your project needs to include po4a and ship the po(t) files. Then a translator of a new language provides you with the correct po file (e.g. fi.po for Finnish) and you simply drop it in the right place and the next time the package is built, Finnish pages are created. Existing translator easily see which paragraphs need an update and update e.g. fr.po and the next time someone compiles your package they get the updated (French) translation.
So I can have a look at the weekend how to include po4a for your project.
And yes, this answers the original question. If you ship it distros will not provide you with updates (typically). If you don't want to ship the translations then manpages-l10n would be the ideal candidate to do so. It has it downsides (possible delays, users might not detect the translated version), but if you decide to go that route I would spare the work to include po4a for your project and you would need to remove (after transfer) your existing translations. Mixing this (some here, some in manpages-l10n) is not really feasibly and creates a mess.
Greetings/Gruss
Hello Bernd,
hello other developers,
Essentially it is ready now (except for some small bugs, of course :-))
I attached it. I can be extracted in man/
How it works:
I added the generation part as sub directory to man/ and extended man/Makefile such that the localized man pages are generated, updated, cleaned etc. after the static translated man pages. This is supposed to be temporary, in the long run the static ones should be removed.
Please note, that for clarity, I copied Makefile to Makefile.new. Of course, in production Makefile.new should replace Makefile.
All the build process and translations are handled then within man/po. Of course, this can be changed. But I think this layout is quite a good start.
Why did I create it this way?
When installing, first the static translations are installed. If the generated man pages also exist, then they replace the static version as they are newer (and probably also improved). Then in the long run, the static translated man pages are no longer shipped.
To start, I converted the static translations into po format. As they are outdated and the conversion is roughly, a native speaker needs to review and update the translations. For German, I can do this myself, if you approve this patch, I will approach the French and Brazilian Portuguese teams and the previous translators to update their part. As long as this has not happened, no translation will be generated. But for this case you still have (and ship) the static translations.
As this translation update part may take time, I cannot tell you when you will receive the updated po files. And thus when you can remove the static versions.
The next step (after providing you the files) would be your tests and feedback. Once I get your ok for inclusion, the update of translations (see above) would be initiated by me and I would also start including the further languages from manpages-l10n.
Whats missing as of now:
-I did not try a full build yet
-I did not try a full install yet
-I did not try a full clean yet
-I did not yet include further translations from manpages-l10n, e.g. the Spanish one.
patches are easier to review. can you just use normal
git difforgit amoutput ?process-wise, i would expect this target to be something developers have to invoke manually, not something that would be automatic. that way it wouldn't show up for random non-net-tools developers, just people trying to e.g. build from git. some sort of
make update-translationsor something. and we'd update our release docs to include that step before doing a final release.Hello Mike,
currently, the build target will not be called automatically, since up to now nothing needed to be done for "building". So in fact, it is not already the case. But to make this more clear, I can of course rename the make target, no problem.
For review:
This is all new code except that I copied the man/Makefile and made some small additions. Hence the diff is empty, i.e. nothing to compare. So simply extract my tarball and look at the (new) code.
Comparing the two make files yields:
Hope this helps.
Last edit: Helge Kreutzmann 2022-09-27
Hello Mike,
I added the requested target(s). They are called "update-po" and "pot". The first updates the po files (those used by translators), the second one updates the pot file and is probably not needed, but might help testing.
I also worked on the German translation a little bit and prepared the fr.po and pt_BR.po as much as I could (using strings from manpages-l10n).
Please review.
Once you agree with the fundamental idea I can request the French and Brazilian Portugese teams to update their strings and work on the German one (potentially with the previous translators). Since this involves quite a bit of work it needs to be sure that the work is used.
And of course, fine tuning the make files would be the final step including adding them to your overall makefile system.
Greetings
Hello Mike,
hello Bernd,
did you have a chance to review the latest version? Any further shortcomings or questions?
If you agree with the principles, I suggest I review the original man pages (taking into account Bug 41) and afterwards initiate a call for updated translations to the French and Brazilian Portuguese Teams (I would handle German myself).
Since by design my patch is non-intrusive (i.e. does not change anything unless explicitly called) it would be good to commit it and then everyone could more easily start testing?
Thanks!
Greetings
Hello Mike,
hello Bernd,
ping?
Do you think this can be integrated in principle?
Please let me know any issues you have.
Also if you approve the general idea, translation teams can work on updating their text (can happen in parallel to the inclusion).
Thanks!
Hello Mike,
hello Bernd,
how do we want to proceed?
Thanks for your reply.
Hello Mike,
hello Bernd,
how do you suggest to proceed?
I really love to resolve the file conflicts with manpages-l10n, and I'm glad to help you with po4a integration; however, your last response is from September 2022, about half a year ago, so I'm unsure what to do next.
Greetings
oh just a comment, given that sooner or later net-tools is optional package it makes sense to move some of tne more generic manpages out of it. i dont know where they would go, is the manpwges project used for those base pages? in that case ether(5) feel free to adopt them, i would then delete all languages from this package. however the tools specific pages should remain. This is asuming other tools besides arp(8) would use the file, not really sure about that. they should then be added as links in the see-also section.
Last edit: Bernd Eckenfels 2022-09-18
is /etc/ethers used by anything other than the net-tools arp daemons ? i wasn't sure if it was really generic enough to consider shifting to the upstream man-pages project.
yes good point (just changed my domment). i am not sure but i thought wireshark, tcpdump (ibm manpage says so, linux manpage does not) and arpd also use it.
Last edit: Bernd Eckenfels 2022-09-18
while searching around looks like old init ecripts used the file to prepopulate arp tables, not sure of this is a good thing but since RH issued an errata for it... https://bugzilla.redhat.com/show_bug.cgi?id=696788 (but thats very old rhel6)
Last edit: Bernd Eckenfels 2022-09-18
just to mention another conflict, the hostname package has its own manpage, its a fork of net-tools.
that one makes sense though i think. it's a diff tool provided by a diff project with diff command line options. afaik, they maintain their own translations too.
that would be a good argument for keeping translations of hostname man pages in net-tools itself. which i guess would extrapolate to all man pages we have (and intend on "keeping" vs moving to the man-pages project).