Skip to content

Translate man pages via Transifex with po4a (+ Romanian man pages) - #5208

Open
lucianpopovici wants to merge 5 commits into
MidnightCommander:masterfrom
lucianpopovici:man-pages-transifex
Open

lucianpopovici wants to merge 5 commits into
MidnightCommander:masterfrom
lucianpopovici:man-pages-transifex

Conversation

@lucianpopovici

@lucianpopovici lucianpopovici commented Oct 27, 2026 •

Copy link
Copy Markdown

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 Transifex

  • maint/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 generates doc/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.py is generalized; the generated po4a configuration for mc.hint is 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 report empty X command ignored.
  • New step in .github/workflows/transifex.yml and a section in maint/sync-transifex/README.md.

doc: add Romanian man pages

  • doc/man/ro/*.1.in (generated by the script above) and doc/man/ro/Makefile.am, which builds all four pages (mcedit.1 and mcdiff.1 only if enabled).
  • ro added to ALL_DOC_LINGUAS and AC_CONFIG_FILES in configure.ac, and to DIST_SUBDIRS in doc/man/Makefile.am.
  • The translation is Arthur Țițeică's 2013 Romanian translation from the old Transifex resources (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 pages

src/man2hlp reads 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:

\X'mclink:Menu Bar'menu bar line\&.\X'mclink'

Translators translate the link text and keep the marker; after generation both are turned back into comments. Lines that po4a rewrote from .B text to \fBtext\fP are turned back into macros as well, because man2hlp counts the font escapes as text.

doc: add Romanian template of the built-in help

ro is in ALL_DOC_LINGUAS, but there was no doc/hlp/ro, which the help build and the doctest from #5213 expect. Adds doc/hlp/ro/xnc.hlp (start, query box and help viewer screens translated, the license kept in English) and wires it into configure.ac and doc/hlp/Makefile.am. The README now also lists doc/hlp/LANG among the steps for adding a language.

Things to know before merging

  • The Transifex resources mc-man--master, mcedit-man--master, mcview-man--master and mcdiff-man--master do not exist yet. Until they are created, the new CI step fails on master. The old mc_man_1, mcedit_man_1 and mcview_man_1 resources 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.
  • The Romanian man page POs are ready but not uploaded to Transifex yet; once the new resources exist, the first man-from-transifex.py ro run should reproduce the pages in this PR.
  • The link marker format (\X'mclink:Target'text\X'mclink') is what translators will see in every language, so if it should change, this is the time.
  • The man pages of the other languages are untouched. Converting them still needs the merge of their existing translations, which needs reviewers who speak those languages.

Testing

  • maint/doctest.py passes (groff style checks, mandoc and man2hlp), including the four Romanian pages.

  • ./autogen.sh generates doc/man/ro/Makefile.in with the expected conditionals and DIST_SUBDIRS.

  • With a stand-in configure.ac that uses the real doc/man tree: all four Romanian pages build, with and without --disable-edit --disable-diff; installed in .../man/ro/man1/; included by make dist.

  • The sync scripts were run with the tx calls 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/ 👈

  • I have referenced the issue(s) resolved by this PR (if any)
  • I have signed-off my contribution with git commit --amend -s
  • Lint and unit tests pass locally with my changes (make indent && make check)
  • I have added tests that prove my fix is effective or that my feature works
  • I have added the necessary documentation (if appropriate)

🤖 Generated with Claude Code

https://claude.ai/code/session_01HtvL2VEq2gyujN6AfW2GDb

@github-actions github-actions Bot added needs triage Needs triage by maintainers prio: medium Has the potential to affect progress labels Oct 27, 2026
@github-actions github-actions Bot added this to the Future Releases milestone Oct 27, 2026
@lucianpopovici
lucianpopovici marked this pull request as ready for review October 29, 2026 09:05
@lucianpopovici

Copy link
Copy Markdown
Author

@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 mc-man--master, mcedit-man--master, mcview-man--master and mcdiff-man--master have to be created before the new CI step can succeed on master (see "Things to know before merging" in the description). Thanks!

@zyv

zyv commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

@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.

Expect delays measured in weeks/months due to current load, sorry.

One thing that needs a maintainer: the Transifex resources mc-man--master, mcedit-man--master, mcview-man--master and mcdiff-man--master have to be created before the new CI step can succeed on master (see "Things to know before merging" in the description). Thanks!

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 man translations? This is the part that prevented me from finishing this task when I have re-written the rest (strings/hints), and not the technical part of the story.

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.

  • I think even POs of blocked resources are visible for you on Transifex, but if they aren’t, I can just download the state for you and attach it to the message here or transfer it to you otherwise.

  • The state in the repo you already have, and the open PR for Spanish I have mentioned. From this, an initial merged state has to be produced for the first upload to Transifex, and if something doesn't map with most minor changes, the sentence has to be dropped (my understanding is "left in English" in Gettext terms - not deleted!) for the translators to do it, instead of filling it in with bad LLM translation.

  • Also, if some translations are not there on Transifex, they have to be requested/created.

  • Are you on Transifex already? Can you request to add yourself to your native languages?

  • Is Romanian your native language, and did you supervise what Claude auto-translated here if it is Claude auto-translation and not your work? I barely understand Romanian, so I can't judge the quality.

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.

@lucianpopovici

Copy link
Copy Markdown
Author

Expect delays measured in weeks/months due to current load, sorry.

No problem, thanks for the detailed answer.

whether you have the time and are willing to put the work into a proper 3-way merge of the existing man translations?

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:

  • Transifex: I'm already in the mc project and can see the blocked man resources (mc_man_1, mcedit_man_1, mcview_man_1), so you don't need to send me anything. As you said, those POs are old and there is also currently no Romanian reviewer.
  • Romanian: It's my native language. Claude made the first translation, and I reviewed and corrected all of it. I can also review Romanian on Transifex if that helps.

Here's how I'd do the merge. Please correct me if it doesn't match what you have in mind:

  1. Collect the sources for each language: the PO from the blocked Transifex resource, the man page in the repo, and any pending update (e.g. Spanish man&help long term update, part 1 mc-old#193 for Spanish, and Ticket #4898: update Serbian translation #4898 is already in for Serbian).
  2. Gettextize the repo translations with po4a-gettextize against the English man page from the same point in git history as the translation, not current master. Otherwise the alignment breaks on old files.
  3. Map everything onto the current POT. If a string matches exactly, or differs only trivially (whitespace, markup, a typo fix), it's kept. If the sources disagree, I use the one that matches the current English. Anything that doesn't map cleanly is left untranslated for the translators. No LLM-filled translations anywhere except Romanian, which I can check myself.
  4. Write a report for each language (kept / dropped / conflicts) so the result can be checked before upload. I'd do one language at a time, starting with the ones that have the freshest translations.
  5. Request the Transifex languages that are missing.

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.

@lucianpopovici

Copy link
Copy Markdown
Author

I rebased on master after #5213 and added three commits on top:

  1. maint: keep the links of the built-in help in translated man pages. Running the new man2hlp check on the Romanian page turned up a pipeline problem that affects every language, not just Romanian. po4a treats the .\"LINK2" / .\"NODE / .\"TOPICS comments as notes for translators and moves them in front of the paragraph, so every help link in a po4a-generated page was broken (98 man2hlp errors in ro/mc.1.in). The scripts now turn the directives into macros that po4a leaves in place, and each link into an inline marker. Both go back to the original comments when the page is generated. Translators see a link like this:

    The topmost line is the \X'mclink:Menu Bar'menu bar line\&.\X'mclink' The menu bar ...
    

    They translate the link text and keep the marker. I checked this by running the English page through po4a and back: the generated help has the same links and nodes as the original. If you'd prefer a different marker format, now is a good time to change it, before anything is uploaded.

  2. doc: add Romanian template of the built-in help. ro was in ALL_DOC_LINGUAS but had no doc/hlp/ro, which the new doctest requires (and the help build expects).

  3. doc: regenerate the Romanian man pages with the current English, including the doc: fix errors and style warnings to unblock CI #5213 fixes. maint/doctest.py passes locally, with mandoc included.

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 #, fuzzy?

@ossilator

Copy link
Copy Markdown
Contributor

should near-matches be dropped (left untranslated) or kept as #, fuzzy?

i don't understand why you are even asking. that's exactly what fuzzies are for, no?

@lucianpopovici
lucianpopovici force-pushed the man-pages-transifex branch 2 times, most recently from 6902afb to 0b9c9db Compare November 8, 2026 16:26
@ossilator

Copy link
Copy Markdown
Contributor

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.

@lucianpopovici
lucianpopovici force-pushed the man-pages-transifex branch 4 times, most recently from 3dd22ba to 8b790f9 Compare November 9, 2026 13:47
@lucianpopovici

Copy link
Copy Markdown
Author

@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 #, fuzzy when a PO file is uploaded (docs), so on Transifex they end up untranslated either way.

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 (mc_man_1, mcedit_man_1, mcview_man_1) have a Romanian translation by Arthur Țițeică from 2013, made against the 2011 English. Mapped onto the current English:

  • 649 strings: English unchanged and the PR's translation already identical to Arthur's (the first draft was built on his work), so nothing to decide.
  • 157 strings: reviewed one by one: 13 where the two translations differ, 36 where the English changed but the Romanian was still Arthur's 2013 text, and 108 where both the English and the translations differ. I kept the reviewed translation everywhere, confirmed 34 old ones as still correct and edited 7.
  • Arthur's strings for English that no longer exists aren't used.

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. maint/doctest.py passes, mandoc included.

Romanian interface (Transifex mc.pot). Checking the Romanian UI in a local build turned up typos, missing diacritics, cedilla ş/ţ instead of ș/ț, untranslated strings and many hotkey clashes (two items with the same & letter in one menu or dialog, counting the OK/Cancel buttons added by QUICK_BUTTONS_OK_CANCEL and the search type radios). I uploaded the corrections to Transifex today: 100 strings, built on the current Transifex state so that nobody's newer translations were overwritten. After that, a scan of all 84 menus and dialogs finds no hotkey clashes and no missing hotkeys in Romanian. One string can't be fixed yet: "Use COW file cloning" (added in March) isn't in the Transifex template, so it needs a POT update first. Its translation will be "Folosește clonarea fișierelor COW".

Questions:

  1. Upload: once you're happy with the PR, should the Romanian man page POs go to the new resources from the sync scripts (mc-man--master etc.), and what should happen with the blocked mc_man_1 / mcedit_man_1 / mcview_man_1? I'd keep them until the new ones are in place, since they hold the other languages' old translations.
  2. Could you push an updated mc.pot to Transifex when convenient, so the COW string can be translated?
  3. The link marker format from my previous comment (\X'mclink:Target'text\X'mclink') is what translators will see in every language, so if you'd like it changed, now is the time.

@ossilator

Copy link
Copy Markdown
Contributor

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.

@lucianpopovici

Copy link
Copy Markdown
Author

@ossilator you were right to ask: the docs are misleading. I tested it on Romanian mc-hint--master: I uploaded the current file with one already translated string changed slightly and marked #, fuzzy.

  • The translation itself didn't change, and the string doesn't count as changed in the stats. That's the part the docs describe ("our parser ignores this translation").
  • But the fuzzy text was not thrown away: it shows up in the editor as a suggestion for that string, with the uploader as its author ("Added by … 5 minutes ago", 1 vote). Translators see it next to the string and can accept it or vote on it.
  • It did not go into the translation memory. The TM matches for that string are only the old, saved translations.

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 #, fuzzy in the POs, they don't show up as finished translations, and translators get them as suggestions to review. One side effect: the suggestions will carry my name as the author, even when the text is an older translator's. The merge report keeps the attribution.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs triage Needs triage by maintainers prio: medium Has the potential to affect progress

Development

Successfully merging this pull request may close these issues.

3 participants