As a maintainer, I’ve always been a little sad that my man pages were not translated. Nor where my user help documentation (docbook files). They weren’t translated mainly because:
- intltool doesn’t support those formats (well, intltool does xml, but not specifically docbook) and
- the usage is slightly different — help docs need to be generated from po files, but normally those po files are just installed onto the system
Traditionally, projects like GNOME have translators handle docbooks separately from the rest of translations. Partly because of the problems above and partly because docbooks often have images which must be recreated in the correct locale. Gettext just isn’t equipped for that.
But I’m willing to concede the screenshot point. I’m OK with user docs that don’t have screenshots for my simple apps. After all, they’re usually just used to walk through the UI that the user can already see. They don’t generally explain anything.
So, how to integrate documentations to my existing gettext system?
Desired Solution
First, let me briefly review what I want the end product to look like:
- I don’t want the documentation translations to end up installed on users’ systems in the compiled .mo files. That just wastes lots of space.
- But I want all the translations to be in the same domain. Multiple domains is a pain for both translators and maintainers. Translators have to go translate two files, not one (I suspect most translators won’t bother-to-translate/notice the other domain), and the domains will have duplicated strings (meaning translators will duplicate work). This means one .pot file and consequently one .po file for each language. This would appear at odds with the previous desire.
- Man pages and docbook are funky formats. There’s all sorts of syntax that makes breaking the content into logical paragraphs or phrases difficult. I want a tool that can handle that while spitting out gettext files. Intltool’s xml module, for example, doesn’t have enough docbook-specific smarts to make that happen, although it does integrate nicely with gettext.
Enter po4a
There’s a program called po4a that can handle some of the more unusual formats well while consuming po files and generating pot files. It does a really great job, but it has a few shortcomings:
- it likes to own the .po files
- it likes to own the .pot file
- it uses its own list of languages (not po/LINGUAS)
All of those shortcomings will make it hard to have one pot file.
Enter Lots of Makefile Magic
I stole the original bits of Makefile goodness for po4a from dpkg, which used it for its man pages. But I added a bit more to meet my desired goals above.
Basically the sequence is as follows when making a distribution tarball (make dist):
- Copy all the .po files from po/ to the help/ directory
- Import the contents of po/LINGUAS to po4a’s configuration file in the help directory
- Run po4a, generating compiled, translated help documentation from the base versions and the copied po files. This will generate a .pot file.
- Filter all the po/*.po files through the standard .pot file, dropping all their help documentation translations. This is so we don’t distribute space-wasting translations that we already ship in the compiled version above.
- Merge the generated help .pot file with the standard .pot file in po/ for shipping and distributing to translators.
Ta-da! It’s a bit convoluted, but means that I can have all the benefits of translated help documentation, with none of the disadvantages of multiple .pot files. Of course, I more than doubled my string count, but I assume translators prefer better coverage than not.
The code is mostly in Déjà Dup‘s help/Makefile.am, help/po4a.cfg, and Makefile.am. I encourage you to steal it and use it for your own projects. Too few man pages are translated.
If there are better tools or more elegant methods, I’d love to hear them!
