Provided by: po4a_0.69-1_all bug

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.

       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

       Historisch war Po4a um vier Skripte herum aufgebaut, wobei jedes eine bestimmte Aufgabe
       erfüllte. po4a-gettextize(1) hilft beim erstmaligen Erzeugen von Übersetzungen und
       optional der Umwandlung bestehender Übersetzungsprojekte in Po4a. po4a-updatepo(1)
       spiegelt die Änderungen an der Ursprungsdokumentation in die entsprechenden PO-Dateien.
       po4a-translate(1) baut übersetzte Quelldateien aus der ursprünglichen Datei und der
       entsprechenden PO-Datei. Zusätzlich ist po4a-normalize(1) hauptsächlich zur Fehlersuche
       der Po4a-Auswerteprogramme nützlich, da es ein nicht übersetztes Dokument aus dem
       ursprünglichen baut. Dies erleichtert es, Störungen zu finden, die aus dem Auswerteprozess
       stammen.

       Most projects only require the features of po4a-updatepo(1) and po4a-translate(1), but
       these scripts proved to be cumbersome and error prone to use. If the documentation to
       translate is split over several source files, it is difficult to keep the PO files up to
       date and build the documentation files correctly. As an answer, a all-in-one tool was
       provided: po4a(1). This tool takes a configuration file describing the structure of the
       translation project: the location of the PO files, the list of files to translate, and the
       options to use, and it fully automates the process. When you invoke po4a(1), it both
       updates the PO files and regenerate the translation files that need to. If everything is
       already up to date, po4a(1) does not change any file.

       Der Rest dieses Abschnitts gibt einen Überblick über die Skriptschnittstelle von Po4a. Die
       meisten Benutzer werden wahrscheinlich das Komplettwerkzeug bevorzugen, das in der
       Dokumentation von po4a(1) beschrieben ist.

   Graphischer Überblick über die Po4a-Skripte
       Das nachfolgende Schema gibt einen Überblick darüber, wie jedes Po4a-Skript verwandt
       werden kann. Hier 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 oder ähnliches sein); die Übersetzer kümmern sich hauptsächlich um die PO-
       Dateien, während die Endbenutzer nur die Datei XX.dok sehen werden.

                                          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)

       Dieses Schema ist kompliziert, aber in der Praxis wird nur der rechte Teil (der
       po4a-updatepo(1) und po4a-translate(1) betrifft) verwandt, sobald das Projekt eingerichtet
       und konfiguriert ist.

       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 Aktionen von
       po4a-updatepo(1) 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 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-translate(1) 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.

       Wie zuvor angemerkt, kombiniert das Programm po4a(1) die Wirkung der getrennten Skripte,
       Aktualisierungen der PO-Dateien und des übersetzten Dokumentes in einem Aufruf. Die
       zugrundeliegende Logik bleibt identisch.

   Eine neue Übersetzung beginnen
       Falls Sie po4a(1) verwenden, gibt es keinen bestimmten Schritt zum Start einer
       Übersetzung. Sie müssen nur die Sprachen in der Konfigurationsdatei aufführen und die
       fehlenden PO-Dateien werden automatisch erstellt. Natürlich müssen die Übersetzer dann die
       Übersetzungen für sämtliche Inhalte in Ihren Dokumenten bereitstellen. po4a(1) erstellt
       auch eine POT-Datei, das ist eine PO-Vorlagendatei. Mögliche Übersetzer können Ihr Projekt
       in eine neue Sprache übersetzen, indem sie diese Datei umbenennen und die Übersetzungen in
       ihrer Sprache bereitstellen.

       Falls Sie es bevorzugen, die individuellen Skripte separat zu verwenden, sollten Sie
       po4a-gettextize(1) wie folgt verwenden, um die POT-Datei zu erstellen. Diese Datei kann
       dann nach XX.po kopiert werden, um eine neue Übersetzung zu starten.

         $ po4a-gettextize --format <Format> --master <Master.dok> --po <Übersetzung.pot>

       Das Masterdokument wird als Eingabe, während die POT-Datei als die Ausgabe des Prozesses
       verwandt wird.

   Integration von Änderungen am ursprünglichen Dokument
       Das hierzu zu verwendende Programm ist po4a-updatepo(1) (bitte lesen Sie dessen
       Dokumentation für Details):

         $ po4a-updatepo --format <Format> --master <neue_Master.dok> --po <alte_dok.XX.po>

       Das Master-Dokument wird in der Eingabe verwandt, während die PO-Datei aktualisiert wird:
       sie wird sowohl in der Ein- als auch der Ausgabe verwandt.

   Erstellen eines übersetzten Dokumentes
       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:

         $ po4a-translate --format <Format> --master <Master.dok> --po <dok.XX.po> --localized <XX.dok>

       Sowohl die Master- als auch die PO-Dateien werden als Eingabe verwandt, während die
       lokalisierte Datei die Ausgabe dieses Prozesses ist.

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

       Die Po4a-Architektur ist objektorientiert. Die Klasse Locale::Po4a::TransTractor(3pm) ist
       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 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.
       Bitte lesen Sie Locale::Po4a::TransTractor(3pm) 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.

       •   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 :)

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