Translate documentation with Po4a

Gnome and KDE are examples of what is possible for localization. Their developers have built the necessary localization infrastructure, and they utilize it to its fullest. For example, the existence of a German user interface is considered a matter of course.

Ideally, a German language manual would come with every German language interface, but this is often not the case. The open source community is trying to change this, however, at least with respect to suitable technical foundations. Po4a [1] counts among those efforts.

Localization Is Possible

The possibility for localizing documentation used in Unix handbooks also exists. The documentation in these handbooks is written using groff macros or in Mdoc format, with the latter used mostly by BSD. In reality, the state of affairs regarding localization of documentation is rather bleak. Most of the translated versions come from external projects, such as Manpages-de [2]. For example, Figure 1 shows the German language manual page for the chown command for the GNU Coreutils, produced by the Manpages-de project.

Figure 1: Localization is indeed possible. Here is the KDE help browser with its German language manpage.

Developers often treat the task of translating software into another language as the lowest priority on their list of things to do. This is true even for developers for whom English is not their native language. Po4a scripts [2] do not get a lot of use, which is unfortunate, because they are easy to use and they can handle numerous formats.

The failure to use Po4a may be partly due to the fact that the documentation for the program is both complicated and confusing. The developers do describe integration into a build system, but the description is one sided and limited to GNU autotools. Moreover, the developers include distractions in the form of references to methods that are basically no longer used, such as the processing of PO files into formats other than Unicode.

Again, this is unfortunate, because Po4a gets by with just a few shell commands, which, when used inside a suitable script, alleviate the complexity of processing the files and localizing them into various languages. Consider, for example, a project named linuxuser , which delivers a file called linuxuser.1 , API documentation in linuxuser.3 , and a description of the configuration options in file linuxuser.conf.5 . All three of the files are located in the subdirectory man . Listing 1 shows a script that creates a common translation template from the files and appends the file suffix .pot . This template will later serve as the basis for the PO files.

#!/bin/sh
po4a-updatepo -f man \
-m man/linuxuser.1 \
-m man/linuxuser.3 \
-m man/linuxuser.conf.5 \
-p linuxuser-man.pot

The -f man switch determines the format in which the files to be translated are found. The question of whether the format is Groff or Mdoc is not important. Whether it is simple text, Texinfo, LaTeX, POD, or XML, (almost) anything is possible. Some formats are still waiting for implementation, such as the increasingly popular reStructuredText [3] format. If necessary, you can do a workaround via the -f text -o markdown option (using the Markdown format, which is very similar).

The Pot file now needs to be published somewhere. Independent pools like Transifex [4], Zanata [5], and the old-fashioned GNU Translationproject.org [6] are especially well suited for this purpose. Launchpad, on the other hand, is a less desirable choice, because projects devoted entirely to translation are not well received. Therefore, if your project is not already at home on this server, you should spare yourself the trouble of trying to host it there.

Usually, sites like Transifex only require you to make a Pot file available. The infrastructure on the site takes care of converting this file into actual PO files and later updating them with any new templates. Thanks to a command-line interface, there is also a convenient connection to the shell. The advantage is that you will not need to store the individual files in a source code management system. Instead, you can simply pull them from the server as needed via Rsync. As a rule, you will only need to do this when creating a tar archive.

Alignment

Once the first PO files are available, you can for example use the GNU translation project to synchronize the files on the server with those on the local system using the command from Listing 2. This assumes that you have already created a man-po directory. Listing 3 shows a script that creates the native language versions of the documentation.

$ rsync -Lrtvz  translationproject.org::tp/latest/linuxuser/  man-po

#!/bin/sh
cd man-po
for lang in *.po
  do
  if [ -d ${lang%.*} ] ; then
  echo "${lang%.*}: directory exists, will be reused"
  else
    mkdir ${lang%.*}
  fi
    po4a-translate -f man -m ../man/linuxuser.1 -p ${lang} -l ${lang%.*}/linuxuser.1
    po4a-translate -f man -m ../man/linuxuser.3 -p ${lang} -l ${lang%.*}/linuxuser.3
    po4a-translate -f man -m ../man/linuxuser.conf.5 -p ${lang} -l ${lang%.*}/linuxuser.conf.5
done

So far so good. Depending on the original format, files with formatted code are available in subdirectories that have been named according to the native language code. Now all you have to do is incorporate the files when building the binary package and when installing the program.

To create the translated files via Cmake and integrate them into the system, you should first add a code section like the one found in Listing 4 to your CMakeLists.txt file at the top level. The cmake invocation then creates a typical makefile and also processes the manpages. It would be especially nifty to rewrite the script in the syntax for the system, which would however limit reuse of the code. Other build systems offer similar functions for incorporating external scripts so that correctness is always guaranteed when the script is used in a standalone manner.

add_custom_command(
  OUTPUT
  COMMAND ./create-po.sh
  DEPENDS linuxuser.1 linuxuser.3 linuxuser.conf.5
  )