Repository navigation
Translate man pages via Transifex with po4a (+ Romanian man pages) - #5208
lucianpopovici wants to merge 5 commits into
Conversation
9c01c4c to
752e730
Compare
2a284f8 to
9f7cad6
Compare
|
@zyv @mc-worker could you please take a look when you have a chance? The branch is rebased on current master and all checks pass. One thing that needs a maintainer: the Transifex resources |
Expect delays measured in weeks/months due to current load, sorry.
The crucial question for me before I look at the code, which is not great in the current form but can be easily improved, I think, is whether you have the time and are willing to put the work into a proper 3-way merge of the existing The problem is, we already have a resource on Transifex, and it was being worked on by the translators on the basis of an outdated POT many years ago for years, until I blocked the resource. Then, we have the files in the repository— some are very fresh— like Serbian (#4898); some are not very up to date, but there is an existing update that needs to be integrated (MidnightCommander/mc-old#193); some are older in the repository than on Transifex; and some are older or newer depending on the sentence. With Claude, this merge problem is solvable, I think, with a few orders of magnitude less effort than human-only, but you need to prompt it correctly and supervise properly.
If you aren't willing to put the time and effort into supervision, but only tokens, then it will be easier for us to fix the issue ourselves eventually. That's why I'm asking these questions first before taking the time to comment on anything else. |
No problem, thanks for the detailed answer.
Yes. I'm willing to do the merge and supervise it properly, not just hand it to Claude. I see this PR as the tooling part, and the merge as the actual work that has to happen before the first upload. Answers to your questions:
Here's how I'd do the merge. Please correct me if it doesn't match what you have in mind:
One question: for strings that almost match but not quite, do you want them dropped completely, or kept as #, fuzzy entries? Fuzzy entries aren't used in the generated pages, but translators would see the old translation as a starting point. And I'm happy to rework the code here, whenever you have time to point out what you'd like changed. |
9f7cad6 to
43aa0dc
Compare
|
I rebased on master after #5213 and added three commits on top:
This affects the merge: old translations of strings that contain links can't be exact matches any more, because the new strings have the markers. I'd treat a string as an exact match when it differs only by the markers, and add the markers around the translated link text myself. For the languages I can't read, that may not always be possible. In those cases I'd follow the answer to my earlier question: should near-matches be dropped (left untranslated) or kept as |
i don't understand why you are even asking. that's exactly what fuzzies are for, no? |
6902afb to
0b9c9db
Compare
|
don't delete comments; instead, add an "EDIT:" with corrections (and strike-through the original text). otherwise it's really confusing for those who follow email notifications. looking at the commits, it seems that the addition and re-generation of the translated pages probably should be squashed to reduce churn. |
3dd22ba to
8b790f9
Compare
|
@ossilator thanks, noted: from now on I'll correct comments with an "EDIT:" instead of deleting them. Sorry for the confusion, I read wrong your comment so my comment was useless. in short: yes, that's what they are for, but Transifex ignores entries marked I also squashed "doc: add Romanian man pages" and "doc: regenerate the Romanian man pages" into one commit, as you suggested. @zyv a progress update, and a change of plan I need to be upfront about. Scope: Romanian only. I offered to do the merge for every language, but I can't judge the translations in languages I don't speak, and that is exactly the supervision you asked for. So I'll do Romanian properly and leave the other languages to people who can review them. I did Spanish as a trial run: repo page + MidnightCommander/mc-old#193 (3-way merged with the later commits), aligned against the current English, with a per-string report of what was kept, what became fuzzy and what was left untranslated. The Transifex Spanish POs were empty. I'm happy to hand the scripts and the report to whoever looks after Spanish (@dhmartin David Martín would be the natural reviewer), but I won't upload it on my own. Romanian: 3-way merge with the old Transifex translation. The blocked resources (
While reviewing I also made the terminology consistent across the four Romanian pages and the built-in help: "ghid" for the help viewer (instead of "vizualizatorul de ajutor"), the dialog and option names as the interface shows them (e.g. "Dispunere" for Layout and "Aspect" for Appearance, which were both "Aspect" before), and "GNU General Public License" in the license notes. Romanian interface (Transifex Questions:
|
|
did you test what tx actually does with fuzzies? it would be entirely reasonable if it automatically fed them into its translation memory, and this wouldn't contradict a loose reading of the docu. in either case, as you noted yourself, they don't hurt. |
|
@ossilator you were right to ask: the docs are misleading. I tested it on Romanian
So fuzzy entries do reach translators, as suggestions. I couldn't test strings with no translation yet: the old man resources refuse uploads (409, "accept translations" is off), and the resources that accept uploads are 100% translated in Romanian. I'd expect the same behaviour there. That's the best outcome for the merge: the near-matches stay |
Add scripts to upload the source strings of the man pages to Transifex and to generate the translated man pages from the translations pulled from there, using po4a. This is the same approach as the one used for the hints, with one Transifex resource per man page (mc.1, mcedit.1, mcview.1 and mcdiff.1). man-from-transifex.py requires the languages to be named explicitly, because the man pages of the existing languages are maintained by hand and must not be overwritten. It also fixes two things po4a breaks when it rewraps a translated man page: the quotes around the date argument of the .TH macro, and the single-line \X'tty: link URL' hyperlink commands. The Transifex resources mc-man--master, mcedit-man--master, mcview-man--master and mcdiff-man--master have to be created first, otherwise the new step of the transifex workflow fails. Ref: MidnightCommander#2665. Assisted-By: Claude Sonnet 5.5 Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
Add the Romanian translation of the mc, mcedit, mcview and mcdiff man pages, generated with maint/sync-transifex/man-from-transifex.py, and wire the new doc/man/ro directory into the build: ALL_DOC_LINGUAS and AC_CONFIG_FILES in configure.ac, and DIST_SUBDIRS in doc/man/Makefile.am. Unlike the other languages, doc/man/ro/Makefile.am builds all four man pages; mcedit.1 and mcdiff.1 only if the editor and the diff viewer are enabled. The translation is based on the existing Romanian translation of the man pages on Transifex by Arthur Țițeică, merged with the current English pages (including the fixes from MidnightCommander#5213) and reviewed string by string. The terms follow the Romanian interface, e.g. "ghid" for the help viewer and the dialog and option names as the program shows them. Assisted-By: Claude Opus 5.5 Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
src/man2hlp reads the links and nodes of the built-in help from roff
comments (.\"LINK2", .\"NODE, .\"TOPICS, .\"SKIP_SECTION and
.\"DONT_SPLIT). po4a treats comments as notes for the translators and
moves them in front of the next paragraph, so all links in the generated
pages pointed nowhere and man2hlp reported them as stale.
Before extracting the strings, turn the directives into macros that po4a
keeps in place, and every link into an inline marker that stays inside
its paragraph:
\X'mclink:Menu Bar'menu bar line\&.\X'mclink'
The translators translate the link text and keep the marker. After the
translated page has been generated, turn both back into comments.
Also turn lines that po4a rewrote from ".B text" to "\fBtext\fP" back
into macros, because man2hlp counts the font escapes as text and the
tags of .TP paragraphs no longer fit their column.
Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
The help is built from mc.1 for every language in DOC_LINGUAS, and ro was already listed in ALL_DOC_LINGUAS without a doc/hlp/ro directory. Add it, with the start, query box and help viewer screens translated (the license is kept in English), and wire it into the build. Assisted-By: Claude Opus 5.5 Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
8b790f9 to
7647660
Compare
Proposed changes
Add the missing pieces to translate the man pages through Transifex with po4a, the same way the hints are already handled (see #2665), and use them to add the Romanian man pages and built-in help.
maint: add synchronization of man pages with Transifexmaint/sync-transifex/man-to-transifex.py(for CI) uploads the source strings, one Transifex resource per page:mc.1,mcedit.1,mcview.1,mcdiff.1.maint/sync-transifex/man-from-transifex.py LANG...(run by hand) pulls the translations and generatesdoc/man/LANG/*.1.in. The languages have to be named explicitly, so the hand-maintained man pages of the existing languages cannot be overwritten.translation_utils.pyis generalized; the generated po4a configuration formc.hintis unchanged.fix_man_page()repairs two things po4a breaks when it rewraps a translated page: it drops the quotes around%DATE_OF_MAN_PAGE%in.TH(the date contains a space in most languages), and it splits the single-line\X'tty: link URL'hyperlink commands, which makes groff reportempty X command ignored..github/workflows/transifex.ymland a section inmaint/sync-transifex/README.md.doc: add Romanian man pagesdoc/man/ro/*.1.in(generated by the script above) anddoc/man/ro/Makefile.am, which builds all four pages (mcedit.1andmcdiff.1only if enabled).roadded toALL_DOC_LINGUASandAC_CONFIG_FILESinconfigure.ac, and toDIST_SUBDIRSindoc/man/Makefile.am.mc_man_1,mcedit_man_1,mcview_man_1), merged with the current English pages (including the doc: fix errors and style warnings to unblock CI #5213 fixes) and reviewed string by string by a native speaker. The terms follow the Romanian interface, e.g. "ghid" for the help viewer and the dialog and option names as the program shows them.maint: keep the links of the built-in help in translated man pagessrc/man2hlpreads the links and nodes of the built-in help from roff comments (.\"LINK2",.\"NODE,.\"TOPICS, ...). po4a moves comments in front of the next paragraph as translator notes, so every link in a generated page pointed nowhere. Before the strings are extracted, the directives become macros that po4a keeps in place, and each link becomes an inline marker inside its paragraph:Translators translate the link text and keep the marker; after generation both are turned back into comments. Lines that po4a rewrote from
.B textto\fBtext\fPare turned back into macros as well, because man2hlp counts the font escapes as text.doc: add Romanian template of the built-in helprois inALL_DOC_LINGUAS, but there was nodoc/hlp/ro, which the help build and the doctest from #5213 expect. Addsdoc/hlp/ro/xnc.hlp(start, query box and help viewer screens translated, the license kept in English) and wires it intoconfigure.acanddoc/hlp/Makefile.am. The README now also listsdoc/hlp/LANGamong the steps for adding a language.Things to know before merging
mc-man--master,mcedit-man--master,mcview-man--masterandmcdiff-man--masterdo not exist yet. Until they are created, the new CI step fails onmaster. The oldmc_man_1,mcedit_man_1andmcview_man_1resources are not used by the scripts; they still hold the old translations of the other languages, so I'd keep them until the new resources are in place.man-from-transifex.py rorun should reproduce the pages in this PR.\X'mclink:Target'text\X'mclink') is what translators will see in every language, so if it should change, this is the time.Testing
maint/doctest.pypasses (groff style checks, mandoc and man2hlp), including the four Romanian pages../autogen.shgeneratesdoc/man/ro/Makefile.inwith the expected conditionals andDIST_SUBDIRS.With a stand-in
configure.acthat uses the realdoc/mantree: all four Romanian pages build, with and without--disable-edit --disable-diff; installed in.../man/ro/man1/; included bymake dist.The sync scripts were run with the
txcalls replaced, against the real po4a configuration.Not tested: a real round trip with Transifex (the new resources don't exist yet).
Related: Translate MAN-pages via Transifex #2665 (this does not resolve it)
Checklist
👉 Our coding style can be found here: https://midnight-commander.org/coding-style/ 👈
git commit --amend -smake indent && make check)🤖 Generated with Claude Code
https://claude.ai/code/session_01HtvL2VEq2gyujN6AfW2GDb