Translate documentation with Po4a

Po4a Internals

P04a may very well produce gettext strings, which cause the translator program to generate poor results. You should pay attention to certain rules when putting the original materials together, because the code parsers for Po4a were specially constructed for the demands of natural language translation. Consequently, they are more susceptible to errors than the parsers used in various converter utilities between formats.

Groff code can be extended with various macros. Such macro definitions constitute one of the pitfalls for Po4a. So, you should either avoid macros altogether, or if this is not possible, use both po4a-updatepo and po4a-translate with the option --option groff_code=verbatim . This will ensure that the scripts will not try to parse unintelligible sections and will instead output them unchanged.

Tables can also pose problems. The formatting instructions shown in Listing 5, which is taken from ps.1 , causes Po4a to add nonsensical line and string breaks after each section that has been formatted via .BR in bold face. This results in strange fragments of gettext strings, leading inevitably to errors. Thus, it's preferable to use the plain version in Listing 6 (xz.1 ), which is just as good in terms of output.

.SS "Integer suffixes and special values"
In most places where an integer argument is expected,
an optional suffix is supported to easily indicate large integers.
There must be no space between the integer and the suffix.
.TP
.B KiB
Multiply the integer by 1,024 (2^10).
.BR Ki ,
.BR k ,
.BR kB ,
.BR K ,
and
.B KB
are accepted as synonyms for
.BR KiB .

lB1 lB1 lBw(\n[ColSize]n)
lB1 l1  l.
CODE    HEADER  DESCRIPTION
%cpu    %CPU    T{
cpu utilization of the process in "##.#" format. Currently, it is the CPU
time used divided by the time the process has been running (cputime/realtime
ratio), expressed as a percentage. It will not add up to 100% unless you are
lucky.  (alias
.BR pcpu ).
T}
%mem    %MEM    T{
ratio of the process's resident set size  to the physical memory on the
machine, expressed as a percentage.  (alias
.BR pmem ).
T}

Generally, Po4a tolerates a lot but the software delivers much more reliable results when code is switched to a simpler format like Markdown or POD, the Perl documentation format. Also, problems finding errors can arise when macros from Groff are used. These have become more and more convoluted over time. Po4a works better with formats that more closely resemble simple text.

Conclusion

Clearly, Po4a is the first choice for localization of documentation. Of course, some specialty tools are masters of a particular format, but Po4a gets high marks for versatility even if it often lags behind parsers specifically written for a particular syntax.

Translations are possible provided a template is available. Nonetheless, many translators are overwhelmed when Po4a is integrated into a project. Progress can be made in this regard if project members will commit to doing the work required.