Provided by: po4a_0.73-2ubuntu1_all 
NAME
Po4a - Rahmenwerk zur Übersetzung von Dokumentation und anderen Materialien
Einleitung
Po4a (PO für alles) erleichtert die Pflege von Dokumentationsübersetzungen mittels der klassischen
Gettext-Werkzeuge. Die Hauptfunktionalität von Po4a ist, dass sie die Übersetzung des Inhaltes von der
Dokumentenstruktur trennt.
Dieses Dokument dient als Einführung in das Po4a-Projekt mit einem Fokus auf mögliche Benutzer, die
überlegen, ob sie dieses Werkzeug verwenden sollten und den Neugierigen, die verstehen möchten, warum die
Dinge so sind, wie sie sind.
Warum Po4a?
Die Philosophie Freier Software ist es, die Technik wirklich für jeden verfügbar zu machen. Aber
Lizenzierung ist nicht die einzige Betrachtung: nicht übersetzte Freie Software ist für nicht englisch
sprechende Personen nutzlos. Daher haben wir noch einiges zu tun, Software für jede Person verfügbar zu
machen.
Von den meisten Projekten wird diese Situation sehr gut verstanden und jeder ist jetzt von der
Notwendigkeit, alles zu übersetzen, überzeugt. Allerdings stellt die eigentliche Übersetzung einen
riesengroßen Aufwand durch viele Beteiligte dar, die zudem von kleinen technischen Schwierigkeiten
behindert werden.
Dankenswerterweise ist Open-Source-Software mittels der Gettext-Werkzeugsammlung sehr gut übersetzt.
Diese Werkzeuge werden zum Entnehmen der zu übersetzenden Zeichenketten aus einem Programm verwandt und
dann werden diese Zeichenketten in einem standardisierten Format dargestellt (genannt PO-Dateien oder
Übersetzungskataloge). Ein gesamtes Ökosystem an Werkzeugen ist entstanden, um Übersetzern beim
eigentlichen Übersetzen dieser PO-Dateien zu helfen. Das Ergebnis wird dann von Gettext zur Laufzeit
verwandt, um dem Endbenutzer die übersetzten Meldungen anzuzeigen.
Im Hinblick auf Dokumentation ist die Situation allerdings immer noch etwas entäuschend. Anfangs
erscheint die Übersetzung der Dokumentation leichter als die Übersetzung eines Programms, da es so
aussieht, als müssten Sie nur das Ursprungsdokument kopieren und anfangen, den Inhalt zu übersetzen. Wenn
allerdings das Ursprungsdokument verändert wird, wird die Nachverfolgung der Änderungen schnell zu einem
Albtraum für Übersetzer. Falls dies manuell erfolgt, ist die Aufgabe unschön und fehlerbehaftet.
Veraltete Übersetzungen sind oft schlimmer als gar keine. Endbenutzer können durch Dokumentation, die
veraltetes Verhalten des Programms beschreibt, verwirrt werden. Sie können zudem nicht direkt mit dem
Betreuer in Kontakt treten, da sie kein Englisch sprechen. Zusätzlich kann der Betreuer keine Probleme
beheben, da er nicht jede Sprache spricht, in die seine Dokumentation übersetzt ist. Diese
Schwierigkeiten, die oft durch schlechte Werkzeuge hervorgerufen werden, können die Motivation für
freiwillige Übersetzer unterminieren, wodurch das Problem weiter verschlimmert wird.
Das Ziel des Po4a-Projektes ist es, die Arbeit der Dokumentenübersetzer zu erleichtern. Insbesondere
macht es die Dokumentenübersetzungen pflegbar.
Die Idee besteht darin, den Gettext-Ansatz für dieses Feld wiederzuverwenden und anzupassen. Wie bei
Gettext werden Texte aus ihren ursprünglichen Orten herausgelöst und den Übersetzern als
PO-Übersetzungskataloge dargestellt. Die Übersetzer können die klassischen Gettext-Werkzeuge wirksam
einsetzen, um die zu erledigende Arbeit zu überwachen, zusammenzuarbeiten und sich als Teams zu
organisieren. Po4a fügt dann die Übersetzung direkt in die Dokumentationsstruktur ein, um übersetzte
Quelldateien zu erstellen, die dann genau wie die englischen Dateien verarbeitet und verteilt werden
können. Jeder Absatz, der nicht übersetzt ist, verbleibt im entstehenden Dokument auf englisch, wodurch
sichergestellt ist, dass die Endbenutzer niemals veraltete Übersetzungen in der Dokumentation sehen.
Dies automatisiert den größten Teil der Routinearbeit bei der Wartung von Übersetzungen. Es wird sehr
leicht, die zu aktualisierenden Absätze zu erkennen und der Prozess ist vollständig automatisiert, wenn
Elemente ohne weitere Änderungen neu sortiert werden. Es können auch spezielle Überprüfungen verwandt
werden, um die Möglichkeit von Formatierungsfehlern zu verringern, die zu einem defekten Dokument führen
würden.
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 (ausgereiftes Auswertprogramm)
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ützt das Format »mdoc«, das von den BSD-Handbuchseiten
verwandt wird (diese sind auch unter Linux recht häufig anzutreffen).
AsciiDoc (ausgereiftes Auswertprogramm)
Dieses Format ist ein leichtgewichtiges Textauszeichnungsformat, um das Schreiben von Dokumentation
zu erleichtern. Es wird beispielsweise von dem Git-System verwandt. Dessen Handbuchseiten werden
mittels Po4a übersetzt.
Siehe Locale::Po4a::AsciiDoc für Details.
pod (ausgereiftes Auswertprogramm)
Das ist das »Perl Online Documentation«-Format. Die Sprache und Erweiterungen selbiger sind in diesem
Format 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, bis
sie Po4a verwenden.
Siehe Locale::Po4a::Pod für Details.
sgml (ausgereiftes Auswertprogramm)
Obwohl dieses Format heutzutage von XML verdrängt wurde, wird es noch für Dokumente verwandt, die
mehr als ein paar Bildschirmseiten lang sind. Es kann sogar für komplette Bücher verwandt werden. Die
Übersetzung so langer Dokumente zu aktualisieren kann eine echte Herausforderung 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 nach 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 (ausgereiftes Auswertprogramm)
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.
text (ausgereiftes Auswertprogramm)
Das Text-Format ist das Grundlagenformat für viele Formate, die längere Textblöcke enthalten wie
Markdown, Glückssprüche, YAML-Deckblattabschnitte, debian/changelog und debian/control.
Dies unterstützt das häufige in »Static Site Generators«, READMEs und anderen Dokumentationssystemen
verwandte Format. Siehe Locale::Po4a::Text(3pm) für Details.
xml und XHMTL (wahrscheinlich ausgereiftes Auswertprogramm)
Das XML-Format liegt vielen Dokumentationsformaten zu Grunde.
Derzeit werden die DocBook-DTD (siehe Locale::Po4a::Docbook(3pm) für weitere Details) und XHTML von
Po4a unterstützt.
BibTex (wahrscheinlich ausgereiftes Auswertprogramm)
Das BibTex-Format wird zusammen mit LaTex zur Formatierung von Fundstellen (Bibliographien) verwandt.
Siehe Locale::Po4a::BibTex für Details.
Docbook (wahrscheinlich ausgereiftes Auswertprogramm)
Ein XML-basierte Auszeichnungssprache, die semantische Markierungen zur Beschreibung von Dokumenten
verwendet.
Siehe Locale::Po4a:Docbook für genauere Details.
Anleitungs-XML (wahrscheinlich ausgereiftes Auswertprogramm)
Ein XML-Dokumentationsformat. Dieses Modul wurde speziell entwickelt, um bei der Unterstützung und
Betreuung der Gentoo-Linux-Dokumentation bis mindestens einschließlich März 2016 (laut der Wayback
Machine) zu helfen. Gentoo ist seitdem auf das Format DevBook XML umgestiegen.
Siehe Locale::Po4a:Guide für genauere Details.
Wml (wahrscheinlich ausgereiftes Auswertprogramm)
Die Web-Auszeichnungssprache, verwechseln Sie WML nicht dem WAP-Zeug, das auf Handys verwendet wird.
Dieses Modul baut auf dem Xhtml-Modul auf, das wiederum auf dem XmL-Modul aufbaut.
Siehe Locale::Po4a::Wml für genauere Details.
Yaml (wahrscheinlich ausgereiftes Auswertprogramm)
Eine strikte Obermenge von JSON. YAML wird oft als System- oder Konfigurationsprojekt verwandt. YAML
ist der Kern von Red Hats Ansible.
Siehe Locale::Po4a::Yaml für genauere Details.
RubyDoc (wahrscheinlich ausgereiftes Auswertprogramm)
Das Ruby-Dokument (RD-)Format, ursprünglich das Standarddokumentationsformat von Ruby und Ruby-
Projekten, bevor die Umstellung auf RDoc in 2002 erfolgte. Obwohl anscheinend die japanische Version
des Ruby-Referenzhandbuches immer noch RD verwendet.
Siehe Locale::Po4a::RubyDoc für genauere Details.
Halibut (wahrscheinlich experimentelles Auswertprogramm)
Ein Dokumentenerstellungssystem, mit Elementen, die TeX, debiandoc-sgml, TeXinfo und anderen ähneln.
Entwickelt von Simon Tatham, dem Entwickler von PuTTY.
Siehe Locale::Po4a:Halibut für genauere Details.
Ini (wahrscheinlich experimentelles Auswertprogramm)
Konfigurationsdateiformat, durch MS-DOS beliebt geworden.
Siehe Locale::Po4a::Ini für genauere Details.
texinfo (sehr hoch experimentelles Auswertprogramm)
Die gesamte GNU-Dokumentation ist in diesem Format geschrieben (dies 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.
gemtext (sehr hoch experimentelles Auswertprogramm)
Das native schlichte Textformat des Gemini-Protokolls. Die Erweiterung ».gmi« wird häufig verwandt.
Unterstützung für dieses Modul ist in Po4a noch in frühen Anfängen. Falls Sie etwas finden, reichen
Sie bitte (auf Englisch) einen Fehler oder eine Funktionalitätsbitte ein.
Andere unterstützte Formate
Po4a kann auch mit einigen selteneren oder spezialisierten Formaten umgehen, wie dem
Dokumentationsformat der Kompilierungsoptionen des 2.4+-Linux-Kernels (Locale::Po4A::KernelHelp) oder
der vom Dia-Werkzeug erstellten Diagramme (Locale::Po4a:Dia). 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 fehlen Po4a immer noch Unterstützung für eine Reihe von Dokumentationsformaten.
Viele davon könnten leicht in Po4a unterstützt werden. Dazu gehören auch Formate, die nicht nur für
die Dokumentation verwandt werden, wie Paketbeschreibungen (Deb und RPM),
Paketinstallationsskriptfragen, Paket-Änderungsprotokolle (»Changelogs«) und alle spezialisierten
Dateiformate, die von Programmen verwandt werden, wie Spieleszenarien oder WINE-Ressource-Dateien.
Po4a verwenden
Am einfachsten verwenden Sie dieses Werkzeug in Ihrem Projekt, indem Sie eine Konfigurationsdatei für das
Programm po4a schreiben und nur mit diesem Programm interagieren. Bitte lesen Sie dessen Dokumentation in
po4a(1). Der Rest dieses Abschnitts stellt eine detailliertere Beschreibung für fortgeschrittenere
Benutzer von Po4a bereit, die ihr Verständnis vertiefen möchten.
Detailliertes Schema des Po4a-Arbeitsablaufs
Lesen Sie auf jeden Fall vor diesem sehr detaillierten Abschnitt erst po4a(1), um einen vereinfachten
Überblick über den Po4a-Arbeitsablauf zu bekommen. Kommen Sie hierher zurück, wenn Sie das vollständige,
gruselige Bild mit fast allen Datails bekommen möchten.
Im nachfolgende Schema steht master.dok als Beispielname für die zu übersetzende Dokumentation; XX.dok
das gleiche Dokument übersetzt in die Sprache XX während doc.XX.po der Übersetzungskatalog für das
Dokument in der Sprache XX ist. Dokumentationsautoren kümmern sich hauptsächlich um master.dok (dies kann
eine Handbuchseite, ein XML-Dokument, eine AsciiDoc-Datei usw. sein); die Übersetzer kümmern sich
hauptsächlich um die PO-Dateien, während die Endbenutzer nur die Datei XX.dok sehen werden.
Übergänge mit eckigen Klammern wie "[po4a updates po]" stellen die Ausführung eines Po4a-Werkzeugs dar,
während Übergänge mit geschweiften Klammern wie "{Aktualisierung von Master.dok}" eine händische
Veränderung der Projektdateien darstellt.
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 aktualisiert po] |
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 aktualisiert Übersetzungen]
|
V
XX.dok
(aktuell)
Wiederum ist dieses Schema übermäßig kompliziert. Lesen Sie po4a(1) für einen vereinfachten Überblick.
Der linke Teil stellt dar, wie po4a-gettextize(1) verwandt werden kann, um ein bestehendes
Übersetzungsprojekt in die Po4a-Infrastruktur zu überführen. Dieses Skript akzeptiert ein
Ursprungsdokument und sein übersetztes Gegenstück und versucht, eine entsprechende PO-Datei daraus zu
bauen. Eine solche manuelle Umwandlung ist recht beschwerlich (lesen Sie die Dokumentation von
po4a-gettextize(1) für weitere Details), sie wird aber nur einmalig notwendig, um Ihre bestehende
Übersetzungen zu überführen. Falls Sie keine Übersetzungen überführen müssen, können Sie diesen Schritt
ignorieren und sich auf den rechten Teil des Schemas konzentrieren.
Ganz oben rechts wird die Aktion der Ursprungsautors dargestellt, der die Dokumentation aktualisiert. Der
mittel-rechte Teil stellt die automatischen Aktualisierungen der Übersetzungsdateien dar: Das neue
Material wird herausgelöst und mit der bestehenden Übersetzung verglichen. Die vorherige Übersetzung wird
für unveränderte Teile verwandt, während teilweise geänderte Teile mit der vorherigen Übersetzung mit
einer »fuzzy«-Markierung verbunden sind, die anzeigt, dass die Übersetzung aktualisiert werden muss.
Neues oder stark verändertes Material verbleibt unübersetzt.
Dann stellt der Block manuelle Bearbeitung die Aktionen der Übersetzer dar, die die PO-Dateien verändern,
um Übersetzungen für jede Ursprungszeichenkette und jeden Absatz bereitzustellen. Dies kann entweder mit
einem speziellen Editor wie dem GNOME-Übersetzungseditor, KDEs Lokalize oder poedit erfolgen, oder
mittels einer Online-Lokalisierungsplattform wie Weblate oder Pootle. Das Übersetzungsergebnis ist eine
Gruppe von PO-Dateien, eine pro Sprache. Bitte lesen Sie die Gettext-Dokumentation für weitere Details.
Der untere Teil der Abbildung zeigt, wie po4a ein übersetztes Quelldokument aus dem ursprünglichen
Dokument master.doc und dem Übersetzungskatakog doc.XX.po, der durch die Übersetzer aktualisiert wurde,
erstellt. Die Struktur des Dokuments wird wiederverwandt, während der ursprüngliche Inhalt durch sein
übersetztes Gegenstück ersetzt wird. Optional kann ein Addendum verwandt werden, um einigen Extratext zu
der Übersetzung hinzuzufügen. Dies wird oft dazu verwandt, den Namen des Übersetzers zum finalen Dokument
hinzuzufügen. Sie finden Details hierzu weiter unten.
Beim Aufruf aktualisiert po4a die Übersetzungsdateien und die übersetzen Dokumentationsdateien
automatisch.
Ein neues Übersetzungsprojekt beginnen
Falls Sie auf der grünen Wiese anfangen, müssen Sie nur eine Konfigurationsdatei für Po4a schreiben und
das wars. Die wichtigen Vorlagen für die fehlenden Dateien werden automatisch erstellt und erlauben es
Ihren Beitragenden, Ihr Projekt in ihre Sprache zu übersetzen. Lesen Sie bitte po4a(1) für eine
Schnellstartanleitung und alle Details.
Falls Sie bereits eine bestehende Übersetzung haben, d.h. eine Dokumentationsdatei, die manuell übersetzt
wurde, können Sie den Inhalt in Ihren Po4a-Arbeitsablauf mittels po4a-gettextize integrieren. Diese
Aufgabe ist ein bisschen mühselig, aber sobald Ihr Projekt in den Po4a-Arbeitsablauf konvertiert ist,
wird alles automatisch aktualisiert.
Aktualisierungen der Übersetzungen und Dokumente
Sobald eingerichtet reicht der Aufruf von po4a, um sowohl die Übersetzungs-PO-Dateien als auch die
übersetzten Dokumente zu aktualisieren. Sie können "--no-translations" an po4a übergeben, um die PO-
Dateien nicht zu aktualisieren (und somit nur die Übersetzungen zu aktualisieren). Dies entspricht grob
den einzelnen Skripten po4a-updatepo und po4a-translate, die jetzt veraltet sind (siehe »Warum die
einzelnen Skripte veraltet sind« in der nachstehenden FAQ).
Verwendung von Addenda, um zusätzlichen Text zu Übersetzungen hinzuzufügen
Hinzufügen von neuem Text zu der Übersetzung ist wahrscheinlich das einzige, was langfristig bei der
manuellen Übersetzung einfacher ist :). Dies kommt vor, wenn Sie einen zusätzlichen Abschnitt zu dem
übersetzten Dokument hinzufügen möchten, der nicht zu Inhalten im Ursprungsdokument passt. Der klassische
Anwendungsfall ist die Danksagung an das Übersetzungs-Team und die Information, wie
übersetzungsspezifische Fehler berichtet werden sollen.
Mit Po4a müssen Sie addendum-Dateien angeben, die konzeptionell als Patches angesehen werden können, die
auf das lokalisierte Dokument nach der Verarbeitung angewandt werden. Jedes Addendum muss als separate
Datei bereitgestellt werden, wobei das Format sich allerdings deutlich von klassischen Patches
unterscheidet. Die erste Zeile ist eine Kopfzeile, die den Einschubpunkt des Addendums definiert (mit
einer unglücklicherweise kryptischen Syntax -- siehe unten), während der Rest der Datei unverändert an
der festgelegten Position eingefügt wird.
Die Kopfzeile muss mit der Zeichenkette PO4A-HEADER: beginnen, gefolgt von einer durch Semikola
getrennten Liste von Schlüssel=Wert-Paaren.
Beispielsweise erklärt die folgende Kopfzeile, dass ein Addendum ganz am Ende der Übersetzung abgelegt
werden muss.
PO4A-HEADER: mode=eof
Die Dinge werden komplexer, wenn Sie den zusätzlichen Inhalt in der Mitte des Dokuments hinzufügen
wollen. Die folgende Kopfzeile erklärt, dass nach dem XML-Abschnitt, der die Zeichenkette Über dieses
Dokument in der Übersetzung enthält, ein Addendum abgelegt werden muss.
PO4A-HEADER: position=Über dieses Dokument; mode=after; endboundary=</section>
In der Praxis wird Po4a beim Versuch, ein Addendum anzuwenden, nach der ersten Zeile, die auf das
Argument "Position" passt, suchen ("Position" kann ein regulärer Ausdruck sein). Vergessen Sie nicht,
dass Po4a hier das übersetzte Dokument betrachtet. Das Ursprungsdokument ist auf Englisch, aber Ihre
Zeile sollte wahrscheinlich wie folgt aussehen, falls Sie möchten, dass sie auf die französische
Übersetzung des Dokuments angewandt wird.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Sobald die "Position" im Zieldokument gefunden wurde, sucht Po4a für die nächste Zeile nach der
"Position", die auf das bereitgestellte "endboundary" passt. Das Addendum wird direkt nach dieser Zeile
eingefügt (da wir eine endboundary bereitstellten, d.h. eine Begrenzung, die den aktuellen Abschnitt
beendet).
Der genau gleiche Effekt könnte mit den nachfolgenden Kopfzeilen erreicht werden, die äquivalent sind:
PO4A-HEADER: position=Über dieses Dokument; mode=after; beginboundary=<section>
Hier sucht Po4a in der Übersetzung nach der ersten Zeile, die auf "<section>" passt und nach der auf
"Über dieses Dokument" passenden Zeile liegt, und fügt das Addendum vor dieser Zeile ein, da wir ein
beginboundary bereitgestellt haben, d.h. eine Begrenzungsmarkierung, die den Anfang des nächsten
Abschnitts markiert. Daher verlangt diese Kopfzeile, dass das Addendum nach dem Abschnitt, der "Über
dieses Dokument" enthält, gesetzt wird, und weist Po4a an, dass dieser Abschnitt mit einer Zeile, die die
Markierung "<section>" enthält, beginnt. Dies ist zum vorherigen Beispiel äquivalent, da Sie in
Wirklichkeit möchten, dass dieses Addendum entweder nach "</section>" oder vor "<section>" hinzugefügt
wird.
Sie können den Einfüge-Modus auch auf den Wert "before" setzen, mit einer ähnlichen Semantik:
Kombinierung von "mode=before" mit einem "endboundary" wird das Addendum genau nach der passenden
Begrenzung setzen. Dies ist die letzte mögliche Begrenzungszeile vor der "Position". Kombinierung von
"mode=before" mit einer "beginboundary" setzt das Addendum genau vor die passende Begrenzung. Dies ist
die letzte mögliche Begrenzungszeile vor der "Position".
Modus | Begrenzungsart | Verwandte Begrenzung | Einfügepunkt im Vergleich zur Begrenzung
========|================|=======================|=========================================
'before'| 'endboundary' | letzte vor 'Position' | direkt nach der ausgewählten Begrenzung
'before'|'beginboundary' | letzte vor 'Position' | direkt vor der ausgewählten Begrenzung
'after' | 'endboundary' | erste nach 'Position' | direkt nach der ausgewählten Begrenzung
'after' |'beginboundary' | erste nach 'Position' | direkt vor der ausgewählten Begrenzung
'eof' | (keine) | n.Z. | Dateiende
Tipps und Tricks rund um Addenda
• Denken Sie daran, dass dies reguläre Ausdrücke sind. Falls Sie beispielsweise das Ende eines Nroff-
Abschnittes, das auf die Zeile ".fi" endet, vergleichen wollen, verwenden Sie nicht ".fi" als
endboundary, da es auf "the[ fi]le" passen wird, was sie offensichtlich nicht erwarten würden. Das
korrekte endboundary ist in diesem Fall: ^\.fi$.
• Leerzeichen SIND im Inhalt von "position" und Begrenzungen wichtig. Daher unterscheiden sich die
beiden nachfolgenden Zeilen. Die zweite wird nur gefunden, falls im übersetzen Dokument ausreichend
angehängte Leerzeichen sind.
PO4A-HEADER: position=Über dieses Dokument; mode=after; beginboundary=<section>
PO4A-HEADER: position=Über dieses Dokument ; mode=after; beginboundary=<section>
• 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.
• Übergeben Sie das Argument "-vv" an po4a, um zu verstehen, wie Addenda zu der Übersetzung hinzugefügt
werden. Es kann auch helfen, po4a im Fehlersuchmodus zu betreiben, um die tatsächlichen internen
Datenzeichenketten zu sehen, wenn Ihr Addendum nicht angewandt wird.
Addenda-Beispiele
• 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 etwas direkt nach einer Zeile hinzufügen möchten (etwa hinter »Copyright Großer Kerl«),
verwenden Sie eine Position, die auf diese 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
Ein ausführlicheres Beispiel
Originaldokument (POD-formatiert):
|=head1 BESCHREIBUNG
|
|dummy - Ein Platzhalterprogramm
|
|=head1 AUTOR
|
|ich
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«).
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|moi
|
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
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.
TransTractoren und Projektarchitektur
Im Herzen des Po4a-Projekt ist die Klasse Locale::Po4a::TransTractor(3pm) der gemeinsame Vorfahr von
allen Auswertungsklassen. 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 sowohl die Eingabe bereitstellen und
die Ausgabe-PO ignorieren, erhalten Sie po4a-translate. Falls Sie stattdessen das Augabedokument
ignorieren, erhalten Sie po4a-updatepo. po4a verwendet einen ersten TransTractor, um eine aktuelle
Ausgabe-POT-Datei zu erhalten (und ignoriert die Ausgabedokumente), ruft msgmerge -U auf, um die
Übersetzungs-PO-Dateien auf Platte zu aktualisieren und baut einen zweiten TransTractor mit diesen
aktualisierten PO-Dateien, um die Ausgabedokumente zu aktualisieren. Kurz gesagt, po4a stellt eine
integrierte Lösung bereit, alles notwendige mittels einer einzigen Konfigurationsdatei zu aktualisieren.
po4a-gettextize verwendet auch zwei TransTractoren, aber auf eine andere Art: Es baut einen TransTractor
pro Sprache und baut dann eine neue PO-Datei mittels der Msgids des ursprünglichen Dokuments als Msgids
und den Msgids des übersetzten Dokuments als Msgstrs. Es bedarf großer Sorgfalt sicherzustellen, dass
alle Zeichenketten, die so zueiander kommen auch tatsächlich zueinander passen, wie in po4a-gettextize(1)
beschrieben.
Format-spezifische Auswerter
Alle Po4a-Formatauswerter sind auf dem TransTractor implementiert. Einige von ihnen sind sehr einfach,
wie die für Text, Markdown und AsciiDoc. Sie laden die Zeilen nacheinander mittels
TransTractor::shiftline() und sammeln den Inhalt des Absatzes oder was auch immer auf. Sobald eine
Zeichenkette komplett ausgewertet ist, verwendet der Auswerter TransTractor::translate() um (1) diese
Zeichenkette zu der Ausgabe-PO-Datei hinzuzufügen und (2) die Übersetzung aus der Eingabe-PO-Datei zu
erhalten. Der Auswerter schiebt das Ergebnis mittels TransTractor::pushline() in die Ausgabedatei.
Einige andere Auswerter sind komplexer, da sie auf externe Auswerter angewiesen sind, um das
Eingabedokument auszuwerten. Die Auswerter für XML, HTML, SGML und Pod bauen auf den SAX-Auswerter auf.
Sie erklären Rücksprünge zu Ereignissen wie »Ich habe einen neuen Titel mit folgendem Inhalt gefunden«,
um gemäß des Eingabeinhalts mittels TransTractor::translate() und TransTractor::pushline() das
Ausgabedokument und die Ausgabe-POT-Dateien zu aktualisieren. Der Yaml-Auswerter ist ähnlich aber anders:
er serialisiert eine durch den Auswerter YAML::Tiny erzeugte Datenstruktur. Daher schlägt das Yaml-Modul
von Po4a beim Erklären der Referenzzeilen fehl: der Ort jeder Zeichenkette in der Eingabedatei wird durch
den Auswerter nicht aufgehoben, so dass nur »$filename:1« als Zeichenkettenort bereitgestellt werden
kann. Die SAX-orientierten Auswerter verwenden »globals« und andere Tricks, um den Dateinamen und die
Zeilennummer von Referenzen zu speichern.
Ein besonderes Problem tritt durch Dateikodierungen und BOM-Markierungen auf. Einfache Auswerter können
das Problem ignorieren, um das sich TransTractor::read() kümmert (intern verwandt, um die Zeilen eines
Eingabedokuments zu erhalten), aber Module, die sich auf einen externen Auswerter Auswerter verlassen,
müssen sicherstellen, dass alle Dateien mit einen geeigneten PerlIO-Decoding-Layer gelesen werden. Am
einfachsten öffen sie die Datei selbst und stellen einen Filehandle oder direkt die gesamte Zeichenkette
an den externen Auswerter bereit. Schauen Sie in Pod::read() und Pod::parse() für ein Beispiel. Der vom
TransTractor gelesene Inhalt wird ignoriert, aber ein frischer Filehandle wird an das externe
Auswerteprogramm übergeben. Der wichtige Teil ist der Modus "<:encoding($charset)", der an die Perl-
Funktion open() übergeben wird.
Po-Objekte
Die Klasse Locale::Po4a::Po(3pm) kümmert sich um das Laden und verwenden von PO- und POT-Dateien. Im
wesentlichen kann eine Datei gelesen, Einträge hinzugefügt, Übersetzungen mit der Methode gettext()
erhalten und die PO in eine Datei geschrieben werden. Fortgeschrittenere Funktionalitäten wie das
Zusammenführen einer PO-Datei mittels einer POT-Datei oder das Überprüfen einer Datei werden an msgmerge
bzw. msgfmt delegiert.
Zu Po4a beitragen
Selbst wenn Sie in der Vergangenheit noch nie zu einem Open-Source-Projekt beigetragen haben, sind Sie
willkommen: Wir helfen Ihnen gerne und beraten Sie gerne. Da uns Mitarbeitende fehlen, versuchen wir eine
Willkommensinfrastruktur zu schaffen, indem wir die Dokumentation und die automatischen Tests verbessern,
um Ihnen Zuversicht beim Beitragen zum Projekt zu geben. Bitte lesen Sie die Datei CONTRIBUTING.md für
weitere Details.
Open-Source-Projekte, die Po4a verwenden
Es folgt eine unvollständige Liste von Projekten, die Po4a für ihre Dokumentation im Einsatz haben. Falls
Sie Ihre Projekt in diese Liste aufgenommen haben möchten, schicken Sie uns auf Englisch eine E-Mail
(oder einen »Merge Request«).
• adduser (man): Benutzer- und Gruppenverwaltungswerkzeug.
• apt (man, docbook): Debian-Paketverwalter.
• aptitude (docbook, svg): Terminal-baierter Paketverwalter für Debian
• F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installierbarer Katalog an
FOSS (Free and Open Source Software) Anwendungen für die Android-Plattform.
• git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): verteiltes Versionssteuersystem zur
Nachverfolgung von Quellcodeänderungen.
• Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)
Dieses Projekt stellt die Infrastruktur zur Übersetzung vieler Handbuchseiten in verschiedene
Sprachen bereit, mit Integration in viele große Distributionen (Arch Linux, Debian und abgeleitete,
Fedora).
• Stellarium <https://github.com/Stellarium/stellarium> (HTML): ein freies, Open-Source-Planetarium für
Ihren Rechner. Po4a wird zur Übersetzung der Himmelskulturbeschreibungen verwandt.
• Jamulus <https://jamulus.io/> (Markdown, YAML, HTML): eine FOSS-Anwendung zum Online-Jamming in
Echtzeit. Die Dokumentation des Webauftritts wird mittels Po4a in mehreren Sprachen verwaltet.
• Anderer zu sortierender Eintrag: <https://gitlab.com/fdroid/fdroid-website/>
<https://github.com/fsfe/reuse-docs/pull/61>
Häufig gestellte Fragen
Wie wird Po4a ausgesprochen?
Ich persönlich spreche es als pouah <https://en.wiktionary.org/wiki/pouah> aus, was auf Französich
lautmalerisch anstelle von »Bäh« verwandt wird :) Vielleicht habe ich einen merkwürdigen Humor :)
Warum sind die einzelnen Skripte veraltet?
Tatsächlich sind po4a-updatepo und po4a-translate zugunsten po4a veraltet. Dies liegt daran, dass po4a
als direkter Ersatz für diese Skripte verwandt werden kann und es hier eine Menge an doppelten Code gibt.
Die einzelnen Skripte sind rund 150 Code-Zeilen, während das Programm po4a 1200 Zeilen lang ist, daher
machen sie eine Menge zusätzliches neben den gemeinsamen Interna. Der doppelte Code führt dazu, dass
Fehler in beiden Versionen auftreten und zwei Korrekturen benötigen. Ein Beispiel für eine solche
Doppelung sind die Fehler #1022216 in Debian und das Problem #442 in GitHub, die beide die exakt gleiche
Korrektur hatten, aber die eine in po4a und die andere in po4a-updatepo.
Langfristig würde ich gerne die einzelnen Skripte entfernen und nur eine Version des Codes verwalten. Die
einzelnen Skripte werden auf jeden Fall nicht mehr verbessert, daher wird nur po4a neue Funktionalitäten
bekommen. Damit sei aber angemerkt, dass es keine Dringlichkeit für das Veralten gibt. Ich habe vor, die
einzelnen Skripte so lange wie möglich beizubehalten, mindestens bis 2030. Falls Ihr Projekt 2030 immer
noch po4a-updatepo und po4a-translate verwendet, könnten Sie ein Problem haben.
Es könnte auch sein, dass wir die Veraltung dieser Skripte irgendwann aufheben, falls eine
Restrukturierung die Code-Dopplung auf Null reduziert. Falls Sie dazu eine Idee (oder besser: einen
Patch) haben, würden wir uns über Ihre Hilfe freuen.
Was ist mit den anderen Übersetzungswerkzeugen für Dokumentation, die Gettext benutzen?
Es gibt eine Reihe davon. Hier ist eine unvollständige Liste und weitere Werkzeuge erscheinen am
Horizont.
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.
xml2po.py
Vom GIMP-Dokumentationsteam seit 2004 verwandt. Funktioniert recht gut, selbst wenn es, wie es der
Name andeutet, nur mit XML-Dateien funktioniert und besonders konfigurierte Makefiles benötigt.
Sphinx
Das Sphinx-Dokumentationsprojekt verwendet Gettext auch intensiv, um seine Übersetzungen zu
verwalten. Unglücklicherweise funktioniert es nur für einige wenige Textformate, Rest und Markdown,
obwohl es wahrscheinlich das einzige Werkzeug ist, das den gesamten Übersetzungsprozess verwaltet.
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.
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 etwas 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.
SIEHE AUCH
• Die Dokumentation des Komplettwerkzeuges, das Sie verwenden sollen: po4a(1).
• Die Dokumentation der individuellen Po4a-Skripte: po4a-gettextize(1), po4a-updatepo(1),
po4a-translate(1), po4a-normalize(1).
• Die zusätzlichen Helferskripte: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).
• Die Auswertprogramme für jedes Format, insbesondere, um die durch jedes akzeptierten Optionen zu
sehen: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm),
Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm),
Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm),
Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm),
Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm),
Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm),
Locale::Po4a::Xml(3pm).
• Die Implementierung der Kerninfrastruktur: Locale::Po4a::TransTractor(3pm) (insbesondere zum
Verständnis der Code-Organisation wichtig), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm),
Locale::Po4a::Common(3pm). Prüfen Sie bitte auch die Datei CONTRIBUTING.md im dem Quellbaum.
AUTOREN
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
perl v5.38.2 2024-08-28 PO4A.7(1)