Mit Po4a haben Sie alle notwendigen Werkzeuge an der Hand, um Dokumentationen an eine Landessprache anzupassen.

Gnome und KDE machen es vor: Die Entwickler verfügen über die nötige Infrastruktur zum Lokalisieren und setzen sie intensiv ein. So gilt eine deutschsprachige Oberfläche hier als Selbstverständlichkeit.

In gewisser Weise steht einem Benutzer, der eine deutsche Programmoberfläche bekommt, auch ein deutsches Handbuch zu – obwohl dieser Anspruch manchmal ins Leere läuft. Es ist jedoch ein Ideal, dem sich die Open-Source-Community anzunähern versucht, zumindest durch die geeigneten technischen Voraussetzungen. Zu diesen zählt auch Po4a [1].

Man spricht deutsch?

Die Möglichkeit zum Lokalisieren von Dokumentationen steht für die in Groff-Makros oder im meist von BSD verwendeten Mdoc-Format geschriebenen Unix-Handbuchseiten ebenfalls offen. In der Praxis sieht es allerdings etwas trübe aus: Die meisten übersetzten Versionen stammen von externen Projekten wie Manpages-de [2]. Abbildung 1 zeigt die deutsche Handbuchseite zum Befehl chown aus den GNU Coreutils – die deutsche Variante kommt aus dem Projekt Manpages-de.

Abbildung 1: Es geht doch: der KDE-Hilfebrowser mit einer deutschen Manpage.

Die Aufgabe, Software in andere Sprachen zu übersetzen, schieben viele Entwickler ans Ende ihrer Prioritätenliste – selbst solche, deren eigene Muttersprache nicht Englisch ist. Obwohl die Po4a-Skripte zahlreiche Formate verarbeiten und sich recht leicht handhaben lassen, kommen sie erst spärlich zum Einsatz.

Das liegt unter Umständen daran, dass die Dokumentation zu Po4a selbst ebenso unübersichtlich wie verwirrend ausfällt: Die Entwickler beschreiben zwar das Einbinden in ein Build-System, beschränken sich dabei aber sehr einseitig auf die GNU Autotools. Weiterhin irritieren Verweise auf Methoden, die heute kaum zum Einsatz kommen, wie das Verarbeiten von PO-Dateien in anderen Formaten als Unicode.

Dabei kommt Po4a mit wenigen Shell-Befehlen aus, die Ihnen innerhalb eines passenden Skripts alles abnehmen, was für das Verarbeiten der Dateien und das Übertragen in die verschiedenen Sprachen nötig ist.

Angenommen, ein Projekt namens linuxuser liefert eine Datei linuxuser.1 und zusätzlich eine API-Dokumentation in linuxuser.3 sowie eine Beschreibung der Konfigurationsoptionen namens linuxuser.conf.5 aus. Alle drei befinden sich im Unterverzeichnis man. Listing 1 zeigt nun ein Skript, das aus diesen Dateien eine gemeinsame Übersetzungsvorlage mit der Endung .pot erstellt, aus der später die PO-Dateien entstehen.

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

Der Schalter -f man bestimmt das Format, in dem die zu übersetzenden Dateien vorliegen – ob Groff oder Mdoc spielt hier keine Rolle. Ob einfacher Text, Texinfo, LaTeX, POD, XML – (fast) alles ist möglich. Manche Formate harren noch der Implementation wie das immer beliebtere ReStructuredText [3]. Hier weichen Sie notfalls mit der Option -f text -o markdown auf das recht ähnliche Markdown aus.

Die Pot-Datei gilt es nun, irgendwo zu veröffentlichen. Dazu eignen sich besonders unabhängige Pools wie Transifex [4], Zanata [5] oder das GNU-Urgestein Translationproject.org [6]. Launchpad gilt hier dagegen als zweite Wahl: Ein Projekt, das sich nur dem Übersetzen widmet, sieht man dort nicht gern. Falls also Ihr Projekt nicht ohnehin schon dort angesiedelt ist, sparen Sie sich den steinigen Weg am besten.

In der Regel stellen Seiten wie Transifex nur die Forderung, dass Sie eine Pot-Datei bereitstellen. Um das Übertragen in tatsächliche PO-Dateien und deren späteres Aktualisieren anhand neuer Vorlagen kümmert sich die dortige Infrastruktur. Dank Schnittstelle zur Kommandozeile besteht darüber hinaus eine komfortable Anbindung an die Shell. Der Vorteil: Sie brauchen die einzelnen Dateien nicht selbst in einem Quellcode-Managementsystem vorrätig zu halten, sondern ziehen sie einfach bei Bedarf per Rsync vom Server – in der Regel erst beim Erstellen eines Tar-Archivs.

Auf ganzer Linie

Liegen die ersten PO-Dateien vor, dann gleichen Sie für das GNU Translation Project mit dem Befehl aus Listing 2 die Dateien des Servers mit dem lokalen System ab. Das setzt jedoch voraus, dass Sie vorher das Verzeichnis man-po angelegt haben. Listing 3 zeigt ein Skript, das nun die nativen Varianten der Dokumentation erzeugt.

$ 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 weit, so gut. Nun liegt entsprechend des Ausgangsformats formatierter Code in den anhand der Sprachcodes benannten Unterverzeichnissen bereit. Jetzt müssen Sie nur noch beim Bau des Binärpakets oder dem Installieren des Programms die Dateien berücksichtigen. Da alles schon in der erforderlichen Verzeichnisstruktur vorliegt, liefern Sie das Skript direkt im Tarball mit und rufen es während der Installation auf.

Um beispielsweise die übersetzten Dateien mit Cmake zu erzeugen und ins System einzubinden, fügen Sie zunächst einen Abschnitt wie in Listing 4 zu Ihrer Datei CMakeLists.txt der obersten Ebene hinzu. Der Aufruf von cmake erzeugt dann wie gehabt ein gewöhnliches Makefile und verarbeitet die Manpages gleich mit.

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

Besonders elegant wäre es, das Skript in die Syntax des Systems umzuschreiben, was jedoch die Wiederverwendbarkeit des Codes einschränkt. Andere Build-Systeme bieten ähnliche Funktionen zum Einbinden externer Skripte, sodass die Funktionalität stets gewährleistet bleibt, wenn das Skript als solches bestehen bleibt.

Po4a intern

Es mag durchaus passieren, dass Po4a Gettext-Strings produziert, die dem Übersetzer die Schweißperlen auf die Stirn treiben. Einige Regeln sollten Sie schon beim Verfassen des Ausgangsmaterials beachten, denn die Code-Parser von Po4a sind speziell auf die Erfordernisse beim Übersetzen ausgelegt und fallen hinsichtlich Anfälligkeit bei Fehlern oft hinter echten Parsern zurück, wie sie in diversen Konvertern zwischen Formaten zum Einsatz kommen.

Groff-Code erlaubt es, diesen nach Belieben um eigene Makros zu erweitern. Solche Definitionen bringen den Pager zwar keineswegs aus dem Tritt, sind aber einer der typischsten Fallstricke für Po4a. Entweder Sie verzichten ganz darauf, oder geben, wenn es anders nicht klappt, sowohl po4a-updatepo als auch po4a-translate die Option --option groff_code=verbatim mit auf den Weg. Sie sorgt dafür, dass die Skripten von unverständlichen Teilen gar nicht erst Notiz nehmen und diese unverändert durchreichen.

Tabellen erweisen sich manchmal ebenfalls als Problem. Eine Formatierung wie in Listing 5 (entnommen aus ps.1) verleitet Po4 dazu, nach den mit .BR fett formatierten Teilen jeweils einen Zeilen- und String-Umbruch einzufügen, der dort gar nicht hingehört. So entstehen seltsam gestückelte Gettext-Strings, die Fehler geradezu heraufbeschwören. Besser ist die schlichtere, aber in der Ausgabe genauso gut aussehende Variante aus Listing 6 (xz.1).

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}

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

Allgemein verträgt Po4a zwar eine ganze Menge, aber wenn Sie Code auf ein simpleres Format wie Markdown oder das Perl-Dokumentationsformat POD umstellen, dankt die Software es mit zuverlässigeren Ergebnissen. Nicht zuletzt fällt die Suche nach Fehlern in den über Jahrzehnte mit ihren Aufgaben gewachsenen Makros von Groff meist schwerer als in Formaten, die näher am einfachen Text bleiben.

Fazit

Po4a ist erste Wahl für das Lokalisieren von Dokumentationen, so viel steht fest. Zwar existieren spezialisierte Werkzeuge, die ein ganz bestimmtes Format besonders gut beherrschen, doch Po4a punktet durch Vielseitigkeit. Allerdings hinkt es vollwertigen Parsern für die jeweilige Syntax oft hinterher.

In der Vergangenheit hat sich immer wieder gezeigt, dass das Potenzial zum Übersetzen durchaus da ist, wenn erst einmal eine Vorlage bereitsteht. Doch das Integrieren von Po4a in ein Projekt überfordert die allermeisten Übersetzer. Hier wäre die Einsicht und Arbeit der Projektmitglieder notwendig, um schneller voranzukommen.