Ubuntu Manpage: Po4a - Rahmenwerk zur Übersetzung von Dokumentation und anderen Materialien

NAME

       Po4a - Rahmenwerk zur Übersetzung von Dokumentation und anderen Materialien

Einleitung

       Das Projektziel von Po4a (PO für alles) ist es, die Übersetzung (und interessanter, die Wartung der
       Übersetzung) zu vereinfachen, indem die Gettext-Werkzeuge auch für Gebiete verwendet werden, wo diese
       nicht erwartet werden, wie Dokumentation.

Inhaltsverzeichnis

Das Dokument ist wie folgt organisiert:

1. Warum sollte ich Po4a verwenden? Wofür ist es gut?
Dieses einleitende Kapitel erklärt die Motivation des Projekts und seine Philosophie. Sie sollten es
zuerst lesen, falls Sie gerade dabei sind, Po4a für Ihre eigene Übersetzungen zu untersuchen.

2. Wie wird Po4a verwandt?
Dieses Kapitel ist eine Art Referenzhandbuch. Es versucht, die Fragen der Benutzer zu beantworten und
ihnen ein besseres Verständnis des gesamten Prozesses zu vermitteln. Hier wird eingeführt, wie Po4a
mit den Dingen umgeht und es dient als Einleitung zur Dokumentation der speziellen Werkzeuge.

HOWTO: Wie wird eine neue Übersetzung begonnen?
HOWTO: Wie wird die Übersetzung zurück in eine Dokumentationsdatei zurücküberführt?
HOWTO: Wie wird eine Po4a-Übersetzung aktualisiert?
HOWTO: Wie wird eine existierende Übersetzung nach Po4a konvertiert?
HOWTO: Wie wird zusätzlicher Text zu Übersetzungen (wie der Name des Übersetzers) hinzugefügt?
HWOTO: Wie erfolgt alles dies in einem Programmaufruf?
HOWTO: Wie wird Po4a angepasst?
3. Wie funktioniert es?
Dieses Kapitel gibt Ihnen einen kurzen Überblick über die Interna von Po4a, so dass Sie sich sicherer
fühlen, es zu warten und zu verbessern. Es könnte Ihnen auch dabei helfen, zu verstehen, warum es
nicht das tut, was Sie erwarten, und wie Sie Ihre Probleme beheben können.

4. FAQ
Dieses Kapitel gruppiert die häufig gestellten Fragen (»Frequently Asked Questions«). In der Tat
könnten derzeit die meisten dieser Fragen wie folgt formuliert werden: »Warum wurde es auf diese
Weise entwickelt und nicht auf eine andere?«. Falls Sie glauben, Po4a ist nicht die richtige Lösung
zur Übersetzung von Dokumentation, sollten Sie diesen Abschnitt lesen. Falls er Ihre Frage nicht
beantwortet, nehmen Sie auf unserer Mailingliste <devel@lists.po4a.org> mit uns (auf Englisch)
Kontakt auf. Wir freuen uns über Rückmeldungen.

5. Spezielle Hinweise zu Modulen
Dieses Kapitel stellt die Besonderheiten jedes Moduls vor, jeweils aus dem Blickwinkel des
Übersetzers und ursprünglichen Autors. Lesen Sie diesen Abschnitt, um die Syntax kennenzulernen, die
Ihnen beim Übersetzen in diesem Modul begegnen wird oder die Regeln, denen Sie in ihrem
Originaldokument folgen sollten, um das Leben der Übersetzer zu erleichtern.

Tatsächlich ist dieser Abschnitt nicht wirklich Teil dieses Dokuments. Stattdessen befindet er sich
in jeder Modul-Beschreibung. Dies stellt sicher, das die Information aktuell ist, indem die
Dokumentation und der Code zusammengehalten werden.

Warum sollte ich Po4a verwenden? Wofür ist es gut?

Ich finde die Idee der Open-Source-Software gut, die jedem Zugriff auf die Software und ihre Quellen
erlaubt. Als Franzose ist mir aber auch klar, dass die Lizenz nicht die einzige Beschränkung der
Offenheit von Software ist: nicht übersetzte freie Software ist für Personen, die kein Englisch sprechen,
nutzlos und wir haben noch einiges zu tun, um diese für jeden da draußen verfügbar zu machen.

Die Wahrnehmung dieser Situation hat sich bei den Akteuren im Bereich Open Source in den letzten Jahren
dramatisch verbessert. Wir, die Übersetzer, haben den ersten Kampf gewonnen und jeden von der Bedeutung
der Übersetzungen überzeugt. Unglücklicherweise war dies der leichte Teil. Jetzt haben wir was zu tun,
und tatsächlich all dieses Zeug zu übersetzen.

Tatsächlich profitiert Open-Source-Software selbst von einem eher anständigen Übersetzungsniveau, Dank
der wundervollen Gettext-Werkzeugsammlung. Diese ist in der Lage, zu übersetzende Zeichenketten aus dem
Programm herauszulösen, sie in einem einheitlichen Format dem Übersetzer anzubieten und dann das Ergebnis
dessen Arbeit zur Laufzeit zur Anzeige übersetzter Meldungen an den Benutzer zu verwenden.

Die Situation ist etwas ganz anderes, wenn es um Dokumentation geht. Viel zu oft ist die übersetzte
Dokumentation nicht sichtbar genug (sie wird nicht als Teil des Programms vertrieben), nur teilweise oder
nicht aktuell. Letzteres ist die schlimmst mögliche Situation. Eine veraltete Übersetzung kann sich als
schlimmer erweisen als überhaupt keine Übersetzung, da sie den Benutzern altes Programmverhalten
beschreibt, das nicht mehr in Benutzung ist.

Das zu lösende Problem
Die Übersetzung von Dokumentation ist an sich nicht sehr schwierig. Texte sind deutlich länger als
Programmmeldungen und die Übersetzung dauert daher länger, allerdings werden dazu keine besonderen
Fähigkeiten benötigt. Die Schwierigkeit liegt im Warten der Übersetzungsarbeit. Es ist sehr schwierig,
fehleranfällig und unangenehm, herauszufinden, welche Teile sich geändert haben und aktualisiert werden
müssen. Ich denke, das erklärt, warum so viele übersetzte Dokumentationen da draußen veraltet sind.

Die Antworten von Po4a
Daher besteht der ganze Sinn von Po4a darin, die Dokumentationsübersetzungen wartbar zu halten. Die Idee
ist, die Gettext-Methodologie für dieses neue Feld zu nutzen. Wie bei Gettext werden Texte aus ihren
ursprünglichen Stellen herausgelöst, um in einem einheitlichen Format den Übersetzern präsentiert zu
werden. Die klassischen Gettext-Werkzeuge helfen dann beim Aktualisieren ihrer Arbeiten, wenn eine neue
Veröffentlichung des Originals herauskommt. Im Gegensatz zum klassichen Gettext-Modell werden die
Übersetzungen dann wieder in die Struktur des ursprünglichen Dokuments eingefügt, so dass es wie die
ursprüngliche (englische) Version verarbeitet und verteilt werden kann.

Daher wird die Ermittlung der geänderten (und daher zu aktualisierenden) Teile des Dokuments sehr leicht.
Ein anderer Pluspunkt liegt darin, dass die Werkzeuge fast die gesamte Arbeit übernehmen, wenn die
Struktur des Originals fundamental neu organisiert wird und wenn Kapitel herumgeschoben, zusammengefasst
oder geteilt werden. Indem der zu übersetzende Text aus der Dokumentenstruktur herausgelöst wird, hält
Sie dies auch von der Komplexität der Textformatierung fern und reduziert das Risiko, dass Sie ein
defektes Dokument erhalten (selbst wenn das nicht vollständig verhindert wird).

Bitte lesen Sie auch die FAQ weiter unten in diesem Dokument für eine komplette Liste der Vor- und
Nachteile dieser Vorgehensweise.

Unterstützte Formate
Derzeit wurde diese Vorgehensweise erfolgreich für mehrere Arten von Textformatierungsformaten umgesetzt:

man

Das gute alte Handbuchformat, verwandt von vielen Programmen da draußen. Die Unterstützung durch Po4a
wird hier sehr begrüßt, da dieses Format etwas schwierig zu benutzen und für Neulinge nicht wirklich
einladend ist. Das Modul Locale::Po4a::Man(3pm) unterstütz das Format »mdoc«, das von den BSD-
Handbuchseiten verwandt wird (diese sind auch unter Linux recht häufig anzutreffen).

pod

Das ist das »Perl Online Documentation«-Format. Die Sprache und Erweiterungen selbiger sind auf diese Art
dokumentiert sowie die meisten existierenden Perl-Skripte. Sie erleichtert es, die Dokumentation nahe
beim eigentlichen Code zu halten, indem beide in die gleiche Datei eingebettet werden. Es erleichtert
Programmierern die Arbeit, aber unglücklicherweise nicht den Übersetzern.

sgml

Obwohl dieses Format heutzutage etwas von XML verdrängt wurde, wird es noch recht oft für Dokumente
verwandt, die mehr als ein paar Bildschirmseiten lang sind. Es ermöglicht es Ihnen, komplette Bücher zu
erstellen. Die Übersetzung so langer Dokumente zu aktualisieren kann zu einem echten Alptraum werden.
diff stellt sich oft als nutzlos raus, wenn der ursprüngliche Text nach der Aktualisierung neu eingerückt
wurde. Glücklicherweise kann Ihnen Po4a bei diesem Prozess helfen.

Derzeit werden nur die DebianDoc- und DocBook-DTD unterstützt, aber das Hinzufügen einer Unterstützung
für eine neue DTD ist wirklich leicht. Es ist sogar möglich, Po4a für eine unbekannte SGML-DTD zu
verwenden, ohne den Code zu verändern, indem die benötigten Informationen auf der Befehlszeile übergeben
werden. Lesen Sie Locale::Po4a::Sgml(3pm) für weitere Details.

TeX / LaTeX

Das LaTeX-Format ist ein wichtiges Dokumentationsformat, das in der Welt der Freien Software und für
Veröffentlichungen genutzt wird. Das Modul Locale::Po4a::LaTeX(3pm) wurde mit der Python-Dokumentation,
einem Buch und ein paar Präsentationen ausprobiert.

Texinfo

Die gesamte GNU-Dokumentation ist in diesem Format geschrieben (das ist sogar eine der Voraussetzungen,
um ein offizielles GNU-Projekt zu werden). Die Unterstützung für Locale::Po4a::Texinfo(3pm) in Po4a ist
noch ganz am Anfang. Bitte berichten Sie Fehler und Funktionalitätswünsche.

xml

Das XML-Format liegt vielen Dokumentationsformaten zu Grunde.

Derzeit wird die DocBook-DTD von Po4a unterstützt. Lesen Sie Locale::Po4a::Docbook(3pm) für weitere
Details.

andere

Po4a kann auch mit einigen selteneren oder spezialisierten Formaten umgehen, wie dem Dokumentationsformat
der Kompilierungsoptionen des 2.4+-Linux-Kernels oder der vom Dia-Werkzeug erstellten Diagramme. Das
Hinzufügen eines neuen Formats ist oft sehr leicht und die Hauptaufgabe besteht darin, einen Parser für
Ihr Zielformat zu entwickeln. Lesen Sie Locale::Po4a::TransTractor(3pm) für mehr Informationen dazu.

Nicht unterstützte Formate
Unglücklicherweise fehlt Po4a noch Unterstützung für einige Dokumentationsformate.

Es gibt einen ganzen Satz an weiteren Formaten, die wir gerne mit Po4a unterstützen würden, nicht nur
Dokumentationsformate. Tatsächlich würden wir gerne alle Marktnischen besetzen, die von den klassichen
Gettext-Werkzeugen freigelassen werden. Darunter fallen Paketbeschreibungen (Deb und RPM),
Paketinstallationsskriptfragen, Paket-Änderungsprotokolle (»Changelogs«) und alle spezialisierten
Dateiformate, die von Programmen verwandt werden, wie Spieleszenarien oder WINE-Ressource-Dateien.

Wie wird Po4a verwandt?

Dieses Kapitel ist eine Art Referenzhandbuch. Es versucht, die Fragen der Benutzer zu beantworten und
ihnen ein besseres Verständnis des gesamten Prozesses zu vermitteln. Hier wird eingeführt, wie Po4a mit
den Dingen umgeht und es dient als Einleitung zur Dokumentation der speziellen Werkzeuge.

Graphischer Überblick
Das folgende Schema gibt einen Überblick über den Prozess der Dokumentationsübersetzung mittels Po4a.
Haben Sie keine Angst vor der scheinbaren Komplexität, dies kommt daher, das hier der gesamte Prozess
dargestellt ist. Sobald Sie Ihr Projekt auf Po4a umgestellt haben, ist nur der rechte Teil der Graphik
relevant.

Beachten Sie, dass Master.dok als Beispiel der zu übersetzenden Dokumentation dient und Übersetzung.dok
der entsprechende übersetzte Text ist. Die Endung könnte .pod, .xml oder .sgml lauten, abhängig vom
Format. Jeder Teil der Abbildung wird in den folgenden Abschnitten noch im Detail dargestellt.

Master.dok
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{Übersetzung} | { Aktualisierung von Master.dok } :
: | | :
XX.dok | V V
(optional) | Master.dok ->-------->------>+
: | (neu) |
V V | |
[po4a-gettextize] dok.XX.po--->+ | |
| (alt) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
Übersetzung.pot ^ V |
| | dok.XX.po |
| | (unscharf) |
{ Übersetzung } | | |
| ^ V V
| | {manuelle Bearbeitung} |
| | | |
V | V V
dok.XX.po --->---->+<---<---- doc.XX.po Addendum Master.dok
(anfänglich) (aktuell) (optional) (aktuell)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.dok
(aktuell)

Auf der linken Seite wird gezeigt, wie eine Umstellung von einer Übersetzung, die Po4a nicht verwendet,
in dieses System erfolgt. Oben im rechten Teil werden die Tätigkeiten des ursprünglichen Autors
dargestellt (Aktualisierung der Dokumentation). In der Mitte vom rechten Teil sind die automatischen
Tätigkeiten von Po4a dargestellt. Das neue Material wird herausgelöst und mit der existierenden
Übersetzung verglichen. Unveränderte Teile werden gefunden und vorherige Übersetzungen verwandt. Teile,
die teilweise geändert wurden, werden auch mit der vorherigen Übersetzung verbunden, allerdings mit einer
speziellen Markierung, die angibt, dass die Übersetzung aktualisiert werden muss. Der untere Teil der
Abbildung zeigt, wie formatierte Dokumente gebaut werden.

Tatsächlich ist der einzige manuelle Arbeitsschritt, den Sie als Übersetzer durchführen müssen, die
Bearbeitung des mit »{manuelle Bearbeitung}« markierten Bereiches. Jaja, es tut mir leid, Po4a hilft beim
Übersetzen. Es übersetzt nichts für Sie …

HOWTO: Wie wird eine neue Übersetzung begonnen?
Dieser Abschnitt stellt die benötigten Schritte dar, um eine neue Übersetzung mit Po4a zu beginnen. Die
Verfeinerungen, um ein existierendes Projekt in dieses System zu überführen, werden in den relevanten
Abschnitten dargestellt.

Um eine neue Übersetzung mit Po4a anzufangen, müssen Sie die folgenden Schritte ausführen:

- Herauslösen des zu übersetzenden Texts aus dem ursprünglichen Dokument <Master.dok> in eine neue
Übersetzungsvorlagendatei <Übersetzung.pot> (dem Gettext-Format). Verwenden Sie dafür das Programm
po4a-gettextize auf folgende Art und Weise:

$ po4a-gettextize -f <Format> -m <Master.dok> -p <Übersetzung.pot>

<Format> ist natürlich das im Dokument Master.dok verwandte Format. Wie erwartet, geht die Ausgabe in
translation.pot. Bitte lesen Sie po4a-gettextize(1) für weitere Details über die existierenden
Optionen.

- Übersetzen Sie tatsächlich, was übersetzt werden soll. Dafür müssen Sie die POT-Datei in z.B. dok.XX.po
umbenennen (wobei XX der ISO 639-1-Code für die Sprache ist, in die Sie übersetzen, z.B. fr) und
bearbeiten Sie die entstandene Datei. Oft ist es eine gute Idee, die Datei nicht XX.po zu nennen, um
Verwirrung mit der Übersetzung der Programmmeldungen zu vermeiden, allerdings ist das Ihre
Entscheidung. Vergessen Sie nicht, die Kopfzeilen der PO-Datei zu aktualisieren, sie sind wichtig.

Die eigentliche Übersetzung kann mit dem PO-Modus von Emacs oder Vi, Lokalize (KDE-basiert),
Gtranslator (GNOME-basiert) oder mit welchem Programm Sie am liebsten arbeiten (z.B. Virtaal),
erfolgen.

Wenn Sie mehr darüber wissen wollen, müssen Sie auf jeden Fall die Gettext-Dokumentation konsultieren.
Sie ist im Paket gettext-doc verfügbar.

HOWTO: Wie wird die Übersetzung zurück in eine Dokumentationsdatei zurücküberführt?
Sobald Sie mit der Übersetzung fertig sind, möchten Sie die übersetzte Dokumentation erhalten und diese
dann zusammen mit der ursprünglichen an die Benutzer verteilen. Verwenden Sie hierfür das Programm
po4a-translate(1) wie folgt (wobei XX für den Sprachcode steht):

$ po4a-translate -f <Format> -m <Master.dok> -p <dok.XX.po> -l <XX.dok>

Wie vorher ist <format> das im Dokument Master.dok verwandte Format. Diesmal ist aber die mit dem
Schalter -p übergebene PO-Datei Teil der Eingabe. Dies ist Ihre Übersetzung. Die Ausgabe landet in
XX.dok.

Bitte lesen Sie po4a-translate(1) für weitere Details.

HOWTO: Wie wird eine Po4a-Übersetzung aktualisiert?
Um Ihre Übersetzung zu aktualisieren, wenn sich die ursprüngliche Datei Master.dok geändert hat,
verwenden Sie das Programm po4a-updatepo(1) wie folgt:

$ po4a-updatepo -f <Format> -m <neue_Master.dok> -p <alte_dok.XX.po>

(Bitte lesen Sie po4a-updatepo(1) für weitere Details.)

Natürlich wird der neue Absatz in dem Dokument nicht magisch in der PO-Datei durch diesen Befehl
übersetzt werden und Sie müssen die PO-Datei manuell aktualisieren. Entsprechend müssen Sie die
Übersetzung für Absätze, die geändert wurden, anpassen. Um sicherzustellen, dass Sie keine verpassen
werden diese beim Erstellen mit »fuzzy« markiert und Sie müssen diese Markierung entfernen, bevor die
Übersetzung von po4a-translate verwandt werden kann. Wie bei der ursprünglichen Übersetzung verwenden Sie
am besten Ihren Lieblings-PO-Editor hierfür.

Sobald Ihre PO-Datei wieder aktuell ist, ohne verbliebene unübersetzte oder unscharfe Zeichenketten,
können Sie ein übersetztes Dokument erstellen, wie dies im vorherigen Abschnitt beschrieben wurde.

HOWTO: Wie wird eine existierende Übersetzung nach Po4a konvertiert?
Oft haben Sie ein Dokument manuell übersetzt, bis eine größere Reorganisation des ursprünglichen
Dokuments Master.dok stattfand. Nach ein paar unschönen Versuchen mit diff und ähnlichen Werkzeugen
möchten Sie auf Po4a umstellen. Allerdings möchten Sie natürlich nicht ihre bestehenden Übersetzungen
dabei verlieren. Keine Angst, dieser Fall wird auch von den Po4a-Werkzeugen abgedeckt und wird
»Gettextisierung« genannt.

Der Schlüssel ist dabei, dass die gleiche Struktur im übersetzten Dokument und in dem ursprünglichen
vorliegt, so dass die Werkzeuge die zugehörigen Inhalte entsprechend ermitteln können.

Falls Sie Glück haben (d.h. falls die Struktur beider Dokumente perfekt passt) wird dies reibungsfrei
verlaufen und Sie sind in wenigen Sekunden eingerichtet. Andernfalls werden Sie herausfinden, warum
dieser Prozess so einen scheußlichen Namen hat und Sie bereiten sich auf Routinearbeit vor. Denken Sie in
jedem Fall daran, dass dies der Preis ist, den Sie zahlen müssen, um den Komfort von Po4a danach zu
genießen. Das gute daran ist, dass Sie diesen Prozess nur einmal durchführen müssen.

Ich kann das nicht oft genug wiederholen. Um den Prozess zu erleichtern, ist es daher wichtig, dass Sie
die genau identische Version finden, die zur Übersetzung verwandt wurde. Am besten ist es, wenn Sie sich
die VCS-Revision, die für die Übersetzung verwandt wurde, notiert hatten und Sie sie nicht im
Übersetzungsprozess geändert haben, und Sie diese daher verwenden können.

Es wird nicht gut funktionieren, wenn Sie einen aktualisierten Originaltext mit der alten Übersetzung
verwenden. Es bleibt möglich, aber es ist schwieriger und sollte wirklich vermieden werden, wenn möglich.
Tatsächlich schlage ich vor, dass die beste Lösung, wenn Sie den ursprünglichen Text nicht wiederfinden
können, ist, jemanden zu finden, der die Gettextisierung für Sie vornimmt (aber nicht mich ;).

Vielleicht bin ich hier zu dramatisch. Selbst wenn Dinge schiefgehen, bleibt dies deutlich schneller als
eine komplette Neuübersetzung. Ich konnte die existierende französische Übersetzung der Perl-
Dokumentation an einem Tag gettextisieren, selbst obwohl Dinge schief gegangen sind. Das waren mehr als
zwei Megabyte an Text und eine neue Übersetzung hätte Monate oder mehr gedauert.

Lassen Sie mich zuerst die Grundlagen der Prozedur erläutern. Später werde ich dann Tipps für die Fälle
geben, bei denen was schief läuft. Um das Verständnis zu erleichtern, verwende ich das obige Beispiel
noch mal.

Sobald Sie Sie die alte Master.dok, auf welche die Übersetzung XX.dok passt, haben, kann die
Gettextisierung direkt mit der PO-Datei dok.XX.po erfolgen, ohne die manuelle Übersetzung der Datei
Übersetzung.pot:

$ po4a-gettextize -f <Format> -m <alte_Master.dok> -l <XX.dok> -p <dok.XX.po>

Wenn Sie Glück haben, war's das. Sie haben Ihre alte Übersetzung nach Po4a konvertiert und können mit der
Aktualisierung sofort beginnen. Folgen Sie einfach den Anweisungen, wie sie einige Abschnitte weiter oben
beschrieben wurden, um Ihre PO-Datei mit dem neusten Originaldokument zu synchronisieren, und
aktualisieren Sie die Übersetzung entsprechend.

Beachten Sie, dass selbst wenn alles korrekt abgelaufen zu sein scheint, es immer noch
Fehlermöglichkeiten gibt. Das liegt daran, dass Po4a nicht in der Lage ist, den Text zu verstehen, um
sicherzustellen, dass die Übersetzung auf das Original passt. Daher werden alle Zeichenketten bei diesem
Vorgang mit »fuzzy« (d.h. als unscharf) markiert. Sie sollten daher alle sorgfältig prüfen, bevor Sie
diese Markierung entfernen.

Oft passen die Dokumentstrukturen nicht genau, wodurch po4a-gettextize daran gehindert wird, seine
Aufgabe korrekt wahrzunehmen. Zu diesem Zeitpunkt besteht das Spiel darin, die Dateien zu bearbeiten, um
ihre verdammte Struktur passend zu bekommen.

Es kann helfen, den Abschnitt Gettextization: Wie funktioniert es? unten zu lesen. Ein Verständnis des
internen Vorgangs wird Ihnen bei der Durchführung helfen. Gut daran ist, dass po4a-gettextize recht
ausführlich berichtet, was schief gelaufen ist, wenn das passiert. Zuerst nagelt es den Punkt fest, bei
dem in den Dokumenten die Strukturdiskrepanzen vorliegen. Sie werden die Zeichenketten kennenlernen, die
nicht zueinander passen, ihre Position im Text und ihren Typ. Desweiteren wird die soweit generierte PO-
Datei in gettextization.failed.po ausgegeben.

- Entfernen Sie alle zusätzlichen Teile in der Übersetzung, wie den Abschnitt, in dem Sie den Namen des
Übersetzers angeben und allen danken, die zu der Übersetzung beigetragen haben. Addenda, die im
nächsten Abschnitt beschrieben werden, erlauben es Ihnen, diese Informationen wieder hinzuzufügen.

- Haben Sie keine Scheu, sowohl das Original als auch die Übersetzung zu bearbeiten. Das wichtigste
ist, die PO-Datei zu erhalten. Sie können diese dann im Anschluss aktualisieren. Andererseits sollte
die Bearbeitung der Übersetzung vorgezogen werden, wenn beide möglich wären, da dies die Dinge
erleichtert, wenn die Gettextisierung abgeschlossen ist.

- Falls notwendig, löschen Sie Teile des Originals, falls diese nicht übersetzt wurden. Beim
anschließenden Synchronisieren der PO-Datei mit dem Dokument kommen diese von alleine zurück.

- Falls Sie die Struktur etwas geändert haben (um zwei Absätze zusammenzufassen oder einen anderen
aufzuteilen) nehmen Sie diese Änderungen zurück. Falls es Probleme im Original gibt, sollten Sie den
Originalautor informieren. Wenn Sie diese nur in Ihrer Übersetzung korrigieren, werden diese nur für
einen Teil der Gemeinschaft korrigiert. Und desweiteren ist das unmöglich, wenn Sie Po4a verwenden ;)

- Manchmal passen die Inhalte des Absatzes, aber ihr Typ nicht. Dies zu korrigieren hängt stark vom
Format ab. In POD und Man kommt dies oft daher, dass bei einem der beiden eine Zeile enthalten ist,
die mit einem Leerzeichen beginnt. In diesen Formaten kann so ein Absatz nicht umgebrochen werden und
erhält daher einen anderen Typ. Entfernen Sie einfach das Leerzeichen und es klappt wieder. Es kann
sich auch um einen Tippfehler im Namen der Markierung (Tags) handeln.

Entsprechend könnten zwei Absätze in POD zusammengefasst worden sein, wenn die trennende Zeile
Leerzeichen enthält oder wenn es keine Leerzeile zwischen der =item-Zeile und dem Inhalt des »item«s
gibt.

- Manchmal sind die Dateien nicht mehr synchron und die Übersetzuzng hängt am falschen Absatz. Dies
zeigt an, dass das echte Problem schon früher in den Dateien vorlag. Überprüfen Sie
gettextization.failed.po, um herauszufinden, wo die Desynchronisation beginnt und korrigieren Sie
dies dort.

- Manchmal erhalten Sie das starke Gefühl, dass Po4a Teile des Texts aufgefuttert hat, entweder vom
Original oder von der Übersetzung. gettextization.failed.po können Sie entnehmen, dass beide gut
aufeinander gepasst haben und dann schlug die Gettextisierung fehl, da versucht wurde, einen Absatz
mit einem Absatz vor (oder hinter) dem Richtigen zu paaren, als ob der richtige Absatz verschwunden
wäre. Verfluchen Sie Po4a wie ich es getan habe, als es mir das erste Mal passierte. Gründlich.

Diese unglückliche Situation entsteht, wenn ein Absatz mehrfach im Dokument vorkommt. In diesem Fall
wird kein neuer Eintrag in der PO-Datei erstellt, sondern es wird stattdessen eine neue Referenz zu
dem bestehenden hinzugefügt.

Wenn daher der gleiche Absatz zwei Mal im Original auftaucht, aber nicht jedes Mal exakt identisch
übersetzt wurde, bekommen Sie den Eindruck, dass ein Absatz des Originals verschwunden ist. Entfernen
Sie einfach die neue Übersetzung. Falls Sie bevorzugen, stattdessen die erste Übersetzung zu
entfernen, da die zweite einfach besser war, ersetzen Sie die erste durch die zweite.

Wurden im Gegensatz dazu zwei ähnliche, aber verschiedene Absätze exakt identisch übersetzt, bekommen
Sie den Eindruck, dass ein Absatz der Übersetzung verschwunden ist. Eine Lösung ist, eine dumme
Zeichenkette zum ursprünglichen Absatz hinzuzufügen (wie »Ich bin anders«). Haben Sie keine Angst,
diese Dinge verschwinden während der Synchronisation, und wenn der hinzugefügte Text kurz genug ist,
wird Gettext ihre Übersetzung zum existierenden Text hinzufügen (und sie dabei als unscharf (»fuzzy«)
markieren, was hier allerdings irrelevant ist, da alle Zeichenketten nach der Gettextisierung
unscharf sind).

Hoffentlich werden diese Tipps Ihnen bei der Gettextisierungsarbeit und der Erlangung der wertvollen PO-
Datei helfen. Sie können jetzt Ihre Datei synchronisieren und mit der Übersetzung beginnen. Bitte
beachten Sie, dass bei langen Texten die erste Synchronisierung sehr lange dauert.

Beispielsweise dauerte der erste Lauf von po4a-updatepo der französischen Übersetzung der Perl-
Dokumentation (eine 5.5 MB PO-Datei) rund zwei Tage auf einem 1 GHz G5-Computer. Ja, 48 Stunden. Die
folgenden dauern aber nur ein paar Dutzend Sekunden auf meinem alten Laptop. Dies kommt daher, dass beim
ersten Lauf die meisten Msgids der PO-Datei auf keine der POT-Datei passen. Dies zwingt Gettext, die
ähnlichsten mit einem sehr aufwändigen Zeichenketten-Approximier-Algorithmus zu suchen.

HOWTO: Wie wird zusätzlicher Text zu Übersetzungen (wie der Name des Übersetzers) hinzugefügt?
Aufgrund der Gettext-Methode ist dies schwieriger mit Po4a als das vorherige reine Bearbeiten einer neuen
Datei neben der ursprünglichen. Allerdings bleibt es dank sogenannter addenda möglich.

Es mag beim Verständnis helfen, Addenda als eine Art von Patches, die auf das übersetzte Dokument nach
der Verarbeitung angewandt werden, zu betrachten. Sie unterscheiden sich recht stark von gewöhnlichen
Patches (es gibt nur eine Zeile Kontext, der reguläre Ausdrücke von Perl einbetten kann, uns sie können
nur neuen Text hinzufügen ohne alten zu löschen), aber die Funktionalität ist die gleiche.

Ihr Ziel ist es, dem Übersetzer zu erlauben, zusätzliche Inhalte zum Dokument hinzuzufügen, der keine
Übersetzung aus dem ursprünglichen Dokument ist. Am häufigsten wird dies dazu verwandt, einen Abschnitt
über die Übersetzung selbst hinzuzufügen, in der Beitragende aufgeführt sind und dargestellt wird, wie
ein Fehler in der Übersetzung gemeldet werden soll.

Ein Addendum muss als separate Datei bereitgestellt werden. Die erste Zeile stellt eine Kopfzeile dar,
die anzeigt, wo in dem erstellten Dokument das Addendum eingefügt werden soll. Der Rest der Addendumdatei
wird dann unverändert an der angegebenen Position des erstellten Dokuments hinzugefügt.

Die Kopfzeile. die den Kontext festlegt, hat eine recht starre Syntax: Sie muss mit der Zeichenkette
PO4A-HEADER: beginnen, gefolgt von einer durch Semikola (;) getrennten Liste von Schlüssel=Wert-Feldern.
Leerzeichen SIND wichtig. Beachten Sie, dass Sie das Semikolon-Zeichen (;) nicht im Wert benutzen können
(hierbei hilft auch nicht, das Zeichen zu schützen). Optional können zur Lesbarkeit Leeraumzeichen ( )
vor dem Schlüssel eingefügt werden.

Obwohl diese Kontextsuche so betrachtet werden könnte, als ob sie ungefähr auf jeder Zeile des
übersetzten Dokuments arbeiten würde, arbeitet sie tatsächlich auf der internen Datenzeichenkette des
übersetzten Dokuments. Diese interne Datenzeichenkette kann ein Text sein, der mehrere Absätze mit
mehreren Zeilen umfasst oder kann eine einzelne XML-Markierung selbst sein. Der genaue Einfügepunkt des
Addendums muss vor oder nach der internen Datenzeichenkette und kann nicht innerhalb der internen
Datenzeichenkette liegen.

Die tatsächliche interne Datenzeichenkette des übersetzten Dokuments kann durch Ausführung von Po4a im
Fehlersuchmodus visualisiert werden.

Das klingt wieder beängstigend, aber das Beispiel unten sollte Ihnen dabei helfen, herauszufinden, wie
die von Ihnen benötigte Kopfzeile geschrieben wird. Um die Diskussion zu beleuchten, nehmen wir an, dass
Sie einen Abschnitt »Über diese Übersetzung« nach dem Abschnitt »Über dieses Dokument« hinzufügen
möchten.

Dies sind die möglichen Schlüssel in der Kopfzeile:

mode (zwingend)
Er kann entweder die Zeichenkette before oder after sein.

Falls mode=before ist, wird der Einfügepunkt durch eine einstufige reguläre Übereinstimmung
ermittelt, die durch das reguläre Ausdrucksargument Position festgelegt wird. Der Einfügepunkt ist
direkt vor der eindeutig übereinstimmenden internen Datenzeichenkette des übersetzten Dokuments.

Falls mode=after ist, wird der Einfügepunkt durch eine zweistufige reguläre Übereinstimmung
ermittelt, die durch das reguläre Ausdrucksargument Position und durch das reguläre Ausdrucksargument
beginboundary oder endboundary festgelegt werden.

Da es mehrere Abschnitte für den angenommenen Fall geben kann, wird der Zweistufenansatz verwandt.

mode=after

position (zwingend)
Ein regulärer Perlausdruck zur Angabe des Kontextes.

Falls mehr als eine interne Datenzeichenkette (oder keine) auf diesen regulären Ausdruck passt, wird
diese Suche nach dem Einfügepunkt und das Hinzufügen fehlschlagen. Es ist in der Tat besser, einen
Fehler zu melden, als das Addendum an der falschen Stelle hinzuzufügen.

Falls mode=before ist, wird der Einfügepunkt vor die interne Datenzeichenkette, die eindeutig auf das
reguläre Argument Position passt, festgelegt.

Falls mode=after ist, wird die Suche nach dem Einfügepunkt auf die Daten nach der internen
Datenzeichenkette, die eindeutig auf das reguläre Argument Position passt, eingegrenzt. Der genaue
Einfügepunkt wird weiter durch beginboundary oder endboundary festgelegt.

In diesem Fall müssen mehrere vorhergehende Abschnitte übersprungen werden, um die Suche mittels der
Abschnittstitelzeichenkette einzugrenzen.

position=Über dieses Dokument

(In der Realität müssen Sie hier stattdessen die übersetzte Titelzeichenkette verwenden.)

beginboundary (nur bei mode=after verwandt, in diesem Fall zwingend)
endboundary (dasselbe)
Eine zweiter regulärer Perlausdruck, der nur bei mode=after benötigt wird. Das Addendum wird direkt
vor oder nach der ersten internen Datenzeichenkette, die auf den regulären Argumentenausdruck
beginboundary bzw. endboundary passt, gelegt.

In diesem Fall kann ausgewählt werden, das Ende des Abschnitts anzugeben, das beim Hinzufügen von
Folgendem passt:

endboundary=</Abschnitt>

oder den Anfang des nächsten Abschnitts anzugeben, indem Folgendes angegeben wird:

beginboundary=<Abschnitt>

In beiden Fällen wird das Addendum nach dem </Abschnitt> und vor dem <Abschnitt> platziert. Die erste
Variante ist besser, da sie auch funktioniert, wenn das Dokument neu organisiert wird.

Es gibt beide Formen, da sich die Formate der Dokumentationen unterscheiden. In einigen davon gibt es
eine Möglichkeit, das Ende eines Abschnitts zu markieren (genauso wie im gerade benutzten
</Abschnitt>), während einige andere das Ende des Abschnitts nicht explizit markieren (wie in
Handbuchseiten). Im erstgenannten Fall möchten Sie keine Abschnittsgrenzen, die ans Ende eines
Abschnitts passen, so dass der Einfügepunkt danach kommt. Im letztgenannten Fall möchten Sie
erreichen, dass Abschnittsgrenzen an den Anfang des nächsten Abschnitts passen, so dass der
Einfügepunkt direkt davor kommt.

Dies kann undurchsichtig erscheinen, aber die nächsten Beispiele werden Sie hoffentlich erleuchten.

Um das bisher benutzte Beispiel zusammenzufassen, können Sie, um einen Abschnitt namens »Über diese
Übersetzung« nach dem »Über dieses Dokument« einem SGML-Dokument hinzuzufügen, eine dieser beiden
Kopfzeilen verwenden:
PO4A-HEADER: mode=after; position=Über dieses Dokument; endboundary=</section>
PO4A-HEADER: mode=after; position=Über dieses Dokument; beginboundary=<section>

Falls Sie etwas hinter den folgenden Nroff-Abschnitt hinzufügen möchten:
.SH "AUTOREN"

Sie sollten den zweischrittigen Zugang durch Setzen von mode=after wählen. Dann sollten Sie mit dem
regulären Argumentenausdruck Position die Suche auf die Zeile nach AUTOREN eingrenzen. Dann sollten Sie
eine Übereinstimmung mit dem Anfang des nächsten Abschnittes (d.h. ^\.SH) mit dem regulären
Argumentenausdruck beginboundary erzielen. Mit anderen Worten:

PO4A-HEADER:mode=after;position=AUTOREN;beginboundary=\.SH

Falls Sie einem Abschnitt etwas hinzufügen möchten (etwa hinter »Copyright Großer Kerl«), statt einen
ganzen Abschnitt hinzuzufügen, geben Sie eine Position an, die zu dieser Zeile passt und geben Sie ein
beginboundary an, das zu irgendeiner Zeile passt.
PO4A-HEADER:mode=after;position=Copyright Großer Kerl, 2004;beginboundary=^

Falls Sie am Ende des Dokuments etwas hinzufügen möchten, geben Sie eine Position an, die zu einer Zeile
Ihres Dokuments passt (aber nur eine Zeile – Po4a wird nicht fortfahren, wenn sie nicht eindeutig ist)
und geben Sie ein endboundary an, das zu nichts passt. Verwenden Sie hier keine einfachen Zeichenketten
wie »EOF«, aber nehmen Sie bevorzugt solche, bei denen es unwahrscheinlich ist, dass sie sich in Ihrem
Dokument befinden.
PO4A-HEADER:mode=after;position=Über dieses Dokument;beginboundary=FakePo4aBoundary

Denken Sie auf alle Fälle daran, dass dies reguläre Ausdrücke sind. Falls der Ausdruck zum Beispiel auf
das Ende eines Nroff-Abschnitts passen soll, der mit der Zeile

.fi

endet, benutzen Sie .fi nicht als endboundary, weil es auf »e[rfi]nden« passt, was vermutlich nicht das
ist, was sie erwarten. Das korrekte endboundary ist in diesem Fall: ^\.fi$.

Falls das Addendum nicht dort landet, wo Sie es erwartet haben, versuchen Sie das Argument -vv an die
Werkzeuge zu übergeben, so dass sie erklären, was sie beim Platzieren des Addendums tun.

Ein ausführlicheres Beispiel

Originaldokument (POD-formatiert):

Dann wird das folgende Addendum sicherstellen, dass ein Abschnitt (auf Französisch) über den Übersetzer
an das Ende der Datei hinzugefügt wird (auf Französisch heißt »ÜBERSETZER« »TRADUCTEUR« und »moi« heißt
»ich«).

Um Ihr Addendum vor dem AUTOR einzufügen, verwenden Sie die folgende Kopfzeile:

PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

Dies funktioniert, da die nächste auf das beginboundary /^=head1/ passende Zeile nach dem Abschnitt
»BESCHREIBUNG« (übersetzt zu »NOM« auf Französisch) diejenige ist, die die Autoren deklariert. Daher wird
das Addendum zwischen beide Abschnitte gelegt. Beachten Sie: Falls später ein anderer Abschnitt zwischen
den Abschnitten NAME und AUTHOR hinzugefügt wird, wird Po4a das Addendum fehlerhafterweise vor den neuen
Abschnitt legen.

Um dies zu vermeiden, können Sie das gleiche mittels mode=before erreichen:

PO4A-HEADER:mode=before;position=^=head1 AUTEUR

HWOTO: Wie erfolgt alles dies in einem Programmaufruf?
Die Benutzung von Po4a erweist sich für Benutzer als ein wenig fehleranfällig, da Sie zwei
unterschiedliche Programme in der richtigen Reihenfolge aufrufen müssen (po4a-updatepo und dann
po4a-translate), von denen jedes mehr als drei Argumente benötigt. Zudem war es schwer, mit diesem System
nur eine PO-Datei für all Ihre Dokumente zu benutzen, wenn mehr als ein Format benutzt wurde.

Das Programm po4a(1) wurde entworfen, um diese Schwierigkeiten zu lösen. Sobald Ihr Projekt auf dieses
System umgestellt wurde, schreiben Sie eine einfache Konfigurationdatei, die erklärt, wo Ihre
Übersetzungsdateien (PO und POT) liegen, wo Ihre Originaldokumente liegen, deren Formate und wohin ihre
Übersetzungen platziert werden sollen.

Wird po4a(1) für diese Datei aufgerufen, wird sichergestellt, dass die PO-Dateien mit dem Original
synchronisiert werden und dass das übersetzte Dokument ordentlich erzeugt wird. Gewiss möchten Sie dieses
Programm zwei Mal aufrufen: Einmal vor der Bearbeitung der PO-Dateien, um sie zu aktualisieren, und
einmal danach, um ein vollständig aktualisiertes übersetztes Dokument zu erhalten. Sie müssen sich aber
nur eine Befehlszeile merken.

HOWTO: Wie wird Po4a angepasst?
Po4a-Module haben Optionen (mit der Option -o angegeben), die benutzt werden können, um das Verhalten des
Moduls zu ändern.

Sie können auch den Quellcode der bestehenden Module bearbeiten oder sogar Ihre eigenen Module schreiben.
Um sie für Po4a sichtbar zu machen, kopieren Sie sie in einen Pfad namens
"/bli/blah/blu/lib/Locale/Po4a/" und fügen Sie dann den Pfad "/bli/blah/blu" in der Umgebungsvariablen
"PERLIB" oder "PERL5LIB" hinzu. Beispiel:

PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

Hinweis: Der tatsächliche Name des Lib-Verzeichnisses ist nicht von Bedeutung.

Wie funktioniert es?

Dieses Kapitel gibt Ihnen einen kurzen Überblick über die Interna von Po4a, so dass Sie sich sicherer
fühlen, es zu warten und zu verbessern. Es könnte Ihnen auch dabei helfen, zu verstehen, warum es nicht
das tut, was Sie erwarten, und wie Sie Ihre Probleme beheben können.

Was steckt dahinter?
Die Po4a-Architektur ist objektorientiert (in Perl. Ist das nicht schön?). Der gemeinsame Vorfahr zu
allen Auswertungsklassen nennt sich TransTractor. Dieser merkwürdige Name ist der Tatsache zu verdanken,
dass er gleichzeitig für das Übersetzen des Dokuments und das Extrahieren von Zeichenketten zuständig
ist.

Förmlicher ausgedrückt nimmt es ein Dokument zum Übersetzen plus eine PO-Datei, die die Übersetzungen
enthält, als Eingabe, während es zwei getrennte Ausgaben erzeugt: Eine weitere PO-Datei (die das Ergebnis
des Extrahierens übersetzbarer Zeichenketten vom Eingabedokument ist) und einem übersetzen Dokument (mit
der gleichen Struktur, wie der aus der Eingabe, bei der aber alle übersetzbaren Zeichenketten durch den
Inhalt der Eingabe-PO-Datei ersetzt wurden). Hier eine grafische Darstellung davon:

Eingabedokument -- \ /---> Ausgabedokument
\ TransTractor:: / (übersetzt)
+-->-- parse() --------+
/ \
Eingabe-PO-Datei---/ \---> Ausgabe-PO-Datei
(extrahiert)

Dieser kleine Knochen ist der Kern der Po4a-Architektur. Falls Sie die Eingabe-PO-Datei und das
Ausgabedokument weglassen, erhalten Sie po4a-gettextize. Falls Sie beide Eingaben bereitstellen und die
Ausgabe-PO-Datei nicht beachten, erhalten Sie po4a-translate. po4a ruft TransTractor zweimal auf und ruft
msgmerge -U zwischen diesen TransTractor-Aufrufen auf, um Lösungen aus einer Hand mit einer einzelnen
Konfigurationsdatei bereitzustellen.

TransTractor::parse() ist eine virtuelle Funktion, die durch jedes Modul implementiert wird. Hier nun ein
kleines Beispiel, um zu zeigen, wie es funktioniert. Es wertet eine Liste von Absätzen aus, von denen
jeder mit <p> beginnt.

1 sub parse {
2 PARAGRAPH: while (1) {
3 $my ($paragraph,$pararef,$line,$lref)=("","","","");
4 $my $first=1;
5 while (($line,$lref)=$document->shiftline() && defined($line)) {
6 if ($line =~ m/<p>/ && !$first--; ) {
7 $document->unshiftline($line,$lref);
8
9 $paragraph =~ s/^<p>//s;
10 $document->pushline("<p>".$document->translate($paragraph,$pararef));
11
12 next PARAGRAPH;
13 } else {
14 $paragraph .= $line;
15 $pararef = $lref unless(length($pararef));
16 }
17 }
18 return; # Keine definierte Zeile erhalten? Ende der Eingabedatei.
19 }
20 }

In Zeile 6 und 7 tauchen "shiftline()" und "unshiftline()" auf. Diese helfen beim Ein- und Auslesen der
Kopfzeilen des internen Eingabedatenstroms des Masterdokuments in die Zeilenzeichenkette und seine
Referenz. Hier wird die Referenz durch eine Zeichenkette "$filename:$linenum" bereitgestellt. Bitte
denken Sie daran, dass Perl nur eindimensionale Felddatenstrukturen hat. Daher ist Code, der mit den
internen Eingabedatenstromzeilen umgeht, etwas kryptisch.

Zeile sechs wird erreicht, wenn <p> zum zweiten Mal gelesen wurde. Dies signalisiert den nächsten Absatz.
Daher sollte die gerade erhaltene Zeile zurück in das Originaldokument (Zeile sieben) ablegt und der
soweit gebaute Absatz ausgegeben werden. Nachdem das führende <p> in Zeile neun entfernt wurde, wird die
Verbindung dieser Markierung mit der Übersetzung des restlichen Absatzes ausgegeben.

Diese translate()-Funktion ist richtig toll. Sie schiebt ihre Argumente in die Ausgabe-PO-Datei
(Extrahierung) und gibt ihre Übersetzung so zurück, wie sie in der Eingabe-PO-Datei vorgefunden wurde
(Übersetzung). Da sie als Teil des Arguments von pushline() verwandt wird, landet diese Übersetzung im
Ausgabedokument.

Ist das nicht toll? Es ist möglich, ein vollständiges Po4a-Modul in weniger als 20 Zeilen zu bauen, wenn
das Format einfach genug ist …

Sie können unter Locale::Po4a::TransTractor(3pm) mehr darüber erfahren.

Gettextisierung: Wie funktioniert das?
Die Idee hierbei ist, das Originaldokument und seine Übersetzung zu nehmen und zu sagen, dass die Nte
übersetzte Zeichenkette der Übersetzung die Übersetzung der Nten extrahierten Zeichenkette des Originals
ist. Damit das funktioniert, müssen sich beide Dateien die exakt gleiche Struktur teilen. Falls die
Dateien zum Beispiel die folgende Struktur haben, ist es sehr unwahrscheinlich, dass die vierte
Zeichenkette der Übersetzung (vom Typ »Kapitel«) die Übersetzung der vierten Zeichenkette des Originals
(vom Typ »Absatz«) ist.

Original Übersetzung

Kapitel Kapitel
Absatz Absatz
Absatz Absatz
Absatz Kapitel
Kapitel Absatz
Absatz Absatz

Dafür werden Po4a-Parser sowohl für das Original als auch für die Übersetzungsdateien zum Extrahieren der
PO-Dateien benutzt. Dann wird eine dritte PO-Datei gebaut, deren Zeichenketten von der zweiten als
Übersetzung der Zeichenketten der ersten genommen werden. Um zu prüfen, ob die zusammengefügten
Zeichenketten tatsächlich die Übersetzung der jeweils anderen sind, sollten Dokumenten-Parser in Po4a
Informationen über den syntaktischen Typ der extrahierten Zeichenketten im Dokument setzen (alle
existierenden tun das, Ihres sollte das ebenfalls tun). Dann wird diese Information benutzt, um
sicherzustellen, dass beide Dokumente die gleiche Syntax haben. Im vorhergehenden Beispiel würde es
ermöglichen, festzustellen, dass Zeichenkette vier im einen Fall ein Absatz und im anderen Fall eine
Kapitelüberschrift ist und dieses Problem melden.

Theoretisch wäre es möglich, das Problem festzustellen und die Dateien nachher neu zu synchronisieren
(genauso wie es diff tut). Aber es ist nicht klar, was mit den wenigen Zeichenketten geschehen soll,
bevor sie asynchron werden und es würde manchmal zu schlechten Ergebnissen führen. Dies ist der Grund,
weshalb aktuelle Implementierungen nicht versuchen, etwas neu zu synchronisieren und lautstark
fehlschlagen, wenn etwas schiefgeht, was manuelle Änderungen an Dateien erfordert, um das Problem zu
lösen.

Sogar mit diesen Vorsichtsmaßnahmen können hier sehr einfach Dinge schiefgehen. Daher werden alle
Übersetzungen, die auf diese Weise entstehen, als »fuzzy« (unscharf) markiert, um sicherzustellen, dass
der Übersetzer sie aufarbeitet und prüft.

Addendum: Wie funktioniert es?
Gut, das hier ist ziemlich leicht. Das übersetzte Dokument wird nicht direkt auf die Platte geschrieben,
sondern im Speicher gehalten, bis alle Addenda angewandt wurden. Die hier beteiligten Algorithmen sind
eher unkompliziert. Es wird nach einer Zeile gesucht, die zum regulären Positionsausdruck passt und falls
mode=before ist, wird das Addendum davor eingefügt. Wenn nicht, wird die nächste zur Abschnittsgrenze
passende Zeile gesucht und das Addendum nach dieser Zeile eingefügt, falls es ein endboundary ist oder
vor dieser Zeile, falls es ein beginboundary ist.

Häufig gestellte Fragen

Dieses Kapitel gruppiert die häufig gestellten Fragen (»Frequently Asked Questions«). In der Tat könnten
derzeit die meisten dieser Fragen wie folgt formuliert werden: »Warum wurde es auf diese Weise entwickelt
und nicht auf eine andere?«. Falls Sie glauben, Po4a ist nicht die richtige Lösung zur Übersetzung von
Dokumentation, sollten Sie diesen Abschnitt lesen. Falls er Ihre Frage nicht beantwortet, nehmen Sie auf
unserer Mailingliste <devel@lists.po4a.org> mit uns (auf Englisch) Kontakt auf. Wir freuen uns über
Rückmeldungen.

Warum ist jeder Absatz getrennt zu übersetzen?
Ja, in Po4a wird jeder Absatz getrennt übersetzt (tatsächlich entscheidet dies jedes Modul, aber alle
existierenden Module tun dies und Ihres sollte das auch tun). Es gibt zwei Hauptvorteile für dieses
Herangehen:

• Wenn die technischen Teile des Dokuments nicht sichtbar sind, kann der Übersetzer nicht daran
herumbasteln. Je weniger Markierungen der Übersetzer vorgesetzt bekommt, um so weniger Fehler kann er
machen.

• Das Zerschneiden des Dokuments hilft beim Isolieren der Änderungen am Originaldokument. Wenn das
Original verändert wurde, wird es durch diesen Prozess vereinfacht, herauszufinden, welche Teile der
Übersetzung aktualisiert werden müssen.

Sogar mit diesen Vorteilen mögen einige Leute den Gedanken nicht, jeden Absatz einzeln zu übersetzen.
Hier einige Antworten auf deren Befürchtungen:

• Diese Herangehensweise erwies sich im KDE-Projekt als erfolgreich und ermöglichte dort Leuten die
größte bekannte Sammlung übersetzter und aktueller Dokumentation.

• Die Übersetzer können weiterhin den Kontext zum Übersetzen benutzen, da die Zeichenketten in der PO-
Datei in der gleichen Reihenfolge wie im Originaldokument stehen. Nacheinander zu übersetzen ist daher
eher vergleichbar, ob Sie Po4a verwenden oder nicht. Und auf jeden Fall bleibt die beste Möglichkeit,
den Kontext zu erhalten, das Dokument in ein druckbares Format umzuwandeln, da die Fassungen mit
Textformatierungen nach Auffassung des Verfassers nicht wirklich lesbar sind.

• Diese Herangehensweise ist diejenige, die von professionellen Übersetzern angewandt wird. Es stimmt,
dass die etwas andere Ziele als Open-Source-Übersetzer verfolgen. Die Wartung ist zum Beispiel meist
weniger kritisch für sie, da der Inhalt sich seltener ändert.

Warum wird nicht auf Satzebene (oder darunter) unterteilt?
Professionelle Übersetzerwerkzeuge unterteilen das Dokument machmal auf Satzebene, um die
Wiederverwendbarkeit vorhergehender Übersetzungen zu maximieren und ihre Verarbeitung zu beschleunigen.
Das Problem ist, dass der gleiche Satz mehrere Übersetzungen haben könnte, je nach Kontext.

Absätze sind definitionsgemäß länger als Sätze. Das wird hoffentlich sicherstellen, dass der gleiche
Absatz, wenn er in zwei Dokumenten vorkommt, die gleiche Bedeutung (und Übersetzung) hat, ohne in jedem
Fall den Kontext zu beachten.

Unterteilen in kleinere Teile als einen Satz wäre sehr schlecht. Es wäre etwas zu umfangreich, hier zu
erklären warum, aber interessierte Leser können beispielsweise die Handbuchseite
Locale::Maketext::TPJ13(3pm) lesen (die der Perl-Dokumentation beigefügt ist). Kurz gesagt, hat jede
Sprache ihre besonderen syntaktischen Regeln und es gibt keine Möglichkeit, Sätze durch angesammelte
Teile von Sätzen für alle existierenden Sprachen zu bilden (oder gar für fünf der zehn meistgesprochenen,
oder sogar weniger).

Warum wird das Original nicht der Übersetzung als Kommentar (oder andersherum) mitgegeben?
Auf den ersten Blick schien Gettext nicht für alle Arten von Übersetzungen geeignet zu sein. Es scheint
zum Beispiel nicht an Debconf angepasst zu sein, die Schnittstelle, die alle Debian-Pakete für ihr
Zusammenspiel mit dem Anwender während der Installation nutzen. In diesem Fall waren die Texte schön
klein (ein Dutzend Zeilen für jedes Paket) und es war schwierig, die Übersetzung in eine Spezialdatei
abzulegen, da sie vor der Paketinstallation verfügbar sein müssen.

Daher haben sich die Debconf-Entwickler entschieden, eine andere Lösung zu implementieren, bei der
Übersetzungen in die gleiche Datei wie das Original platziert werden. Dies ist recht ansprechend. Jemand
könnte dies zum Beispiel sogar für XML wollen, dies würde dann ungefähr so aussehen:

<section>
<title lang="de">Mein Titel</title>
<title lang="fr">Mon titre</title>

<para>
<text lang="de">Mein Text.</text>
<text lang="fr">Mon texte.</text>
</para>
</section>

Aber es war dadurch so problematisch, dass nun eine PO-basierte Herangehensweise benutzt wird. Nur das
Original kann in der Datei bearbeitet werden und die Übersetzung muss in PO-Dateien erfolgen, die von der
Master-Schablone extrahiert wurden (und zur Kompilierungzeit des Pakets zurück platziert werden). Das
alte System wurde wegen mehrerer Probleme missbilligt:

• Verwaltungsprobleme

Falls mehrere Übersetzer gleichzeitig einen Patch bereitstellen, ist es schwierig, sie
zusammenzufügen.

Wie möchten Sie Änderungen im Original ermitteln, wofür die Übersetzungen aktualisiert werden müssen?
Um Diff zu benutzen, müssen sie vermerken, welche Version des Originals Sie übersetzt haben. D.h. Sie
benötigen in Ihrer Datei eine PO-Datei. ;)

• Kodierungsprobleme

Diese Lösung ist umsetzbar, wenn nur europäische Sprachen beteiligt sind, aber die Einführung von
Koreanisch, Russisch und/oder Arabisch erschwert das Szenario. UTF könnte eine Lösung sein, aber es
gibt immer noch Probleme damit.

Außerdem sind solche Probleme schwer feststellbar (d.h. nur koreanische Leser werden bemerken, dass
die Kodierung von Koreanisch kaputt ist [aufgrund des russischen Übersetzers]).

Gettext löst all diese Probleme gleichzeitig.

Aber Gettext wurde nicht für diese Verwendung entworfen!
Das stimmt, allerdings kam bisher niemand mit einer besseren Lösung. Die einzige bekannte Alternative ist
die manuelle Übersetzung mit all den Verwaltungsproblemen.

Was ist mit den anderen Übersetzungswerkzeugen für Dokumentation, die Gettext benutzen?
Soweit mir bekannt, gibt es nur zwei davon:

poxml
Dies ist das durch KDE-Leute entwickelte Werkzeug, um DocBook-XML zu handhaben. Soweit bekannt, war
es das erste Programm zum Extrahieren von Zeichenketten aus der Dokumentation in PO-Dateien und um
sie nach dem Übersetzen wieder einzuspeisen.

Es kann nur XML und eine spezielle DTD handhaben. Der Verfasser ist ziemlich unglücklich mit der
Handhabung von Listen, die in einer großen Msgid enden. Wenn die Liste groß wird, wird es schwerer,
mit dem großen Stück umzugehen.

po-debiandoc
Dieses von Denis Barbier erstellte Programm ist so eine Art Vorläufer des Po4a-SGML-Moduls, wodurch
ersteres mehr oder weniger missbilligt ist. Wie der Name sagt, handhabt es nur die DebianDoc-DTD, die
mehr oder weniger eine missbilligte DTD ist.

Die Hauptvorteile von Po4a demgegenüber sind die Erleichterung beim Hinzufügen zusätzlichen Inhalts (was
dort sogar schlechter ist) und die Fähigkeit, Gettext zu verwenden.

Entwickler über Übersetzung schulen
Wenn Sie versuchen, Dokumentationen oder Programme zu übersetzen, sehen Sie sich drei Arten von Problemen
gegenüber; linguistische (nicht jeder spricht zwei Sprachen), technische (der Grund, weshalb Po4a
existiert) und beziehungsartige/menschliche. Nicht alle Entwickler verstehen die Notwendigkeit, Dinge zu
übersetzen. Sogar wenn sie entgegenkommend sind, könnten Sie ignorieren, wie Übersetzern die Arbeit
erleichtert wird. Um dabei zu helfen, bringt Po4a ein Menge Dokumentation mit, auf die Bezug genommen
werden kann.

Ein weiterer wichtiger Punkt ist, dass jede übersetzte Datei mit einem kurzen Kommentar beginnt, der
angibt, um was für eine Datei es sich handelt und wie sie benutzt wird. Dies sollte den armen Entwicklern
helfen, die mit tonneweisen Dateien in unterschiedlichen Sprachen überschüttet werden, die sie kaum
sprechen können und hilft ihnen, korrekt damit umzugehen.

In einem Projekt, das Po4a verwendet, sind übersetzte Dateien keine Quelldateien mehr. Das bedeutet, dass
diese Dateien nicht die bevorzugte Form für Veränderungen sind. Da dies eher untypisch ist, ist das eine
leichte Fehlerquelle. Daher haben alle vorhandenen Dateien diese Kopfzeilen:

| *****************************************************
| * GENERATED FILE, DO NOT EDIT *
| * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
| *****************************************************
|
| This file was generated by po4a-translate(1). Do not store it (in VCS,
| for example), but store the PO file used as source file by po4a-translate.
|
| In fact, consider this as a binary, and the PO file as a regular source file:
| If the PO gets lost, keeping this translation up-to-date will be harder ;)

Ebenso müssen die normalen PO-Dateien von Gettext nur in das Verzeichnis po/ kopiert werden. Aber dies
ist nicht der Fall bei denen, die durch Po4a manipuliert wurden. Das Hauptrisiko hier ist, dass ein
Entwickler die existierende Übersetzung seines Programms mit der Übersetzung seiner Dokumentation löscht.
(Beides kann nicht in der gleichen PO-Datei gespeichert werden, weil sein Programm seine Übersetzung als
mo-Datei installieren muss, während die Dokumentation ihre Übersetzung nur zur Zeit der Kompilierung
benötigt.) Daher enthalten die PO-Dateien, die vom Modul po-debiandoc erzeugt wurden folgende Kopfzeilen:

#
# ADVISES TO DEVELOPERS:
# - you do not need to manually edit POT or PO files.
# - this file contains the translation of your debconf templates.
# Do not replace the translation of your program with this !!
# (or your translators will get very upset)
#
# ADVISES TO TRANSLATORS:
# If you are not familiar with the PO format, gettext documentation
# is worth reading, especially sections dedicated to this format.
# For example, run:
# info -n '(gettext)PO Files'
# info -n '(gettext)Header Entry'
#
# Some information specific to po-debconf are available at
# /usr/share/doc/po-debconf/README-trans
# or http://www.debian.org/intl/l10n/po-debconf/README-trans
#

ZUSAMMENFASSUNG der Vorteile der Gettext-basierten Herangehensweise
• Die Übersetzungen werden nicht zusammen mit dem Original gespeichert, wodurch es möglich wird,
festzustellen, ob Übersetzungen nicht mehr aktuell sind.

• Die Übersetzungen werden jeweils in separaten Dateien gespeichert, was verhindert, dass sich Übersetzer
unterschiedlicher Sprachen, sowohl beim Senden des Patches als auch auf der Ebene des Dateikodierung,
stören.

• Es basiert intern auf Gettext (Po4a bietet aber eine sehr einfache Schnittstelle, so dass Sie die
Interna nicht verstehen müssen, um es zu benutzen). Auf diese Art muss das Rad nicht neu erfunden
werden und aufgrund ihrer weiten Verbreitung kann davon ausgegangen werden, dass diese Werkzeuge mehr
oder weniger fehlerfrei sind.

• Für den Endanwender hat sich nichts geändert (außer der Tatsache, dass Übersetzungen hoffentlich besser
gepflegt werden). Die resultierende Dokumentationsdatei, die verteilt wird, ist exakt dieselbe.

• Es ist nicht nötig, dass Übersetzer eine neue Dateisyntax lernen und ihr bevorzugter PO-Editor (wie der
PO-Modus von Emacs, Lokalize oder Gtranslator) wird gut funktionieren.

• Gettext bietet eine einfache Möglichkeit, Statistiken darüber zu erhalten, was erledigt ist, was
überprüft und aktualisiert werden sollte und was noch zu erledigen ist. Einige Beispiele können unter
den folgenden Adressen gefunden werden:

- https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/

Aber nicht alles ist rosig und diese Herangehensweise hat auch einige Nachteile, die bewältigt werden
müssen.

• Addenda sind … auf den ersten Blick merkwürdig.

• Sie können den übersetzten Text nicht nach Ihren Präferenzen anpassen, wie das Aufteilen eines Absatzes
hier und das Zusammensetzen zwei anderer dort. Aber, falls es in einem gewissen Sinn ein Problem mit
dem Original gibt, sollte es sowieso als Fehler gemeldet werden.

• Sogar mit der einfachen Oberfläche bleibt es ein neues Werkzeug, das Leute lernen müssen.

Es wäre traumhaft, wenn jemand Po4a in Gtranslator oder Lokalize einbinden würde. Wenn eine
Dokumentationsdatei geöffnet wird, werden die Zeichenketten automatisch extrahiert. Wenn sie
gespeichert wird, kann eine übersetzte Datei + PO-Datei auf die Platte geschrieben werden. Falls es
fertiggebracht wird, ein MS-Word-Modul™ (oder zumindest RTF) zu erstellen, können es sogar
professionelle Übersetzer nutzen.

AUTOREN

        Denis Barbier <barbier,linuxfr.org>
        Martin Quinson (mquinson#debian.org)

Po4a-Werkzeuge                                     2020-04-15                                            PO4A(7)