Graphischer Überblick¶

    Masterdokumente  ---+---->-------->------>------>----+
 (Dokumentenerstellung) |                                |
                        V        (Po4a-Ausführung)       >-----+--> Übersetzungen
                        |                                |     |
 bestehende PO-Dateien ->---> aktualisierte PO-Dateien >-+     |
         ^                               |               |
         |                               V               |
         +----------<----------<---------+               ^
          (manueller Übersetzungsprozess)                |
                                                         |
 Addendum -->--------------------------------------------+

Die Master-Dokumente werden von den Dokumentenautoren geschrieben. Alle Änderungen werden durch Po4a automatisch in den PO-Dateien wiedergegeben, die dann durch die Übersetzer aktualisiert werden. Alle Änderungen an den PO-Dateien (entwender manuell oder durch Po4a) werden in den übersetzten Dokumenten wiedergespiegelt. Sie können dieses Verhalten mittels der Skripte po4a-updatepo(1) und po4a-translate(1) in Make-Steuerdateien nachahmen, aber dies wird schnell nervend und wiederholend (siehe po4a(7)). Wir legen Ihnen die Verwendung des Programms po4a zum Einsatz in Ihrem Bauprogramm ans Herz.

Optionen, die die POT-Kopfzeilen verändern¶

--porefs Typ

Gibt das Referenzformat an. Das Argument Typ kann entweder never (keine Referenz erzeugen), file (nur die Datei ohne Zeilenzahlen festlegen), counter (alle Zeilennummern durch einen ansteigenden Zähler ersetzen) oder full (komplette Referenzen einbinden) sein. Die Vorgabe ist »full«.

--wrap-po no|newlines|Zahl (Vorgabe: 76)

Legt fest, wie die PO-Datei umgebrochen werden soll. Dies ermöglicht die Auswahl zwischen Dateien, die schön umgebrochen sind aber zu GIT-Konflikten führen können oder Dateien, die leichter automatisch zu handhaben, aber schwerer für Menschen zu lesen sind.

Aus kosmetischen Gründen hat die Gettext-Programmsammlung PO-Dateien in der 77.Spalte umgebrochen. Diese Option legt das Verhalten von Po4a fest. Falls auf einen numerischen Wert gesetzt, wird Po4a die PO-Datei nach dieser Spalte und nach Zeilenumbrüchen im Inhalt umbrechen. Falls auf newlines gesetzt, wird Po4a die msgid und msgstr nur nach Zeilenumbrüchen im Inhalt auftrennen. Falls auf no gesetzt, wird Po4a die PO-Datei überhaupt nicht umbrechen. Die Referenzkommentare werden durch die von Po4a intern verwandten Gettext-Werkzeuge immer umgebrochen.

Beachten Sie, dass diese Option keine Auswirkung darauf hat, wie msgid und msgstr umgebrochen werden, d.h. wie Zeilenumbrüche zu dem Inhalt dieser Zeilen hinzugefügt werden.

--master-language

Sprache der Quelldateien, die die zu übersetzenden Dokumente enthalten. Beachten Sie, dass alle Master-Dokumente in der gleichen Sprache vorliegen müssen.

--msgid-bugs-address e-mail@adresse

Setzt die E-Mail-Adresse, an die Fehler in den Meldungen (msgid) berichtet werden sollen. Standardmäßig haben die erstellten POT-Dateien keine »Report-Msgid-Bugs-To«-Felder.

--copyright-holder Zeichenkette

Setzt den Namen des Urhebers in den Kopfzeilen der POT-Datei. Standardmäßig ist dies »Free Software Foundation, Inc.«.

--package-name Zeichenkette

Setzt den Paketnamen für die POT-Kopfzeilen. Standardmäßig »PACKAGE«.

--package-version Zeichenkette

Setzt die Paketversion für die POT-Kopfzeilen. Standardmäßig »VERSION«.

Optionen, um PO-Dateien zu verändern¶

--msgmerge-opt Optionen

Extraoptionen für msgmerge(1).

Hinweis: $lang wird zur aktuellen Sprache erweitert.

--no-previous

Diese Option entfernt --previous aus den an msgmerge übergebenen Optionen. Dies erlaubt die Unterstützung von gettext-Versionen vor 0.16.

--previous

Diese Option fügt --previous zu den an msgmerge übergebenen Optionen hinzu. Dies benötigt gettext 0.16 oder neuer und ist standardmäßig aktiviert.

Finden der PO- und POT-Dateien¶

Die einfachste Lösung ist die explizite Angabe der Pfade zu den POT- und PO-Dateien, wie folgt:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Die speziellen Pfade zu der POT-Datei zuerst, und dann die Pfade zu den deutschen und französischen PO-Dateien.

Die gleiche Information kann wie folgt geschrieben werden, um das Risko von Kopier-/Einfügefehlern zu vermeiden:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

Die Komponente $lang wird automatisch mittels der bereitgestellten Sprachliste ausgegeben, wodurch das Risiko von Kopieren-/Einfüge-Fehlern reduziert wird, wenn eine neue Sprache hinzugefügt wird.

Die gleiche Information kann noch kompakter geschrieben werden, indem Sie nur die Pfade zu dem Verzeichnis angeben, das Ihr Übersetzungsprojekt enthält, wie folgt:

 [po_directory] man/po/

Das bereitgestellte Verzeichnis muss eine Gruppe von PO-Dateien enthalten, jede mit Namen XX.po, wobei "XX" der ISO 631-Code der in dieser Datei verwandten Sprache ist. Das Verzeichnis muss auch eine einzelne POT-Datei enthalten, die die Endung ".pot" trägt. Beim ersten Lauf kann diese Datei leer sein, sie muss aber existieren (Po4a kann den Namen, der vor der Erweiterung zu verwenden ist, nicht erraten).

Beachten Sie, dass Sie nur einen aus "po_directory" und "po4a_paths" auswählen dürfen. Ersterer ("po_directory") ist kompakter, reduziert das Risiko von Kopieren-/Einfügenfehlern weiter, erzwingt aber die Verwendung von einer erwarteten Projektstruktur und Dateinamen. Die zweite Möglichkeit ("po4a_paths") ist expliziter, wahrscheinlich lesbarer und wird empfohlen, wenn Sie Ihr erstes Projekt mit Po4a einrichten.

Zentralisierte oder getrennte PO-Dateien?

Standardmäßig erstellt Po4a eine einzelne PO-Datei pro Zielsprache, die den gesamten Inhalt Ihres Übersetzungsprojektes enthält. Mit dem Wachstum Ihres Projektes könnte die Größe der Dateien problematisch werden. Bei der Verwendung von Weblate ist es möglich, für jedes Übersetzungssegment (d.h., msgid) Prioritäten festzulegen, so dass wichtige zuerst übersetzt werden. Einige Übersetzungsteams bevorzugen es aber weiterhin, den Inhalt in mehrere Teile zu trennen.

Um eine PO-Datei pro Master-Datei zu erhalten, müssen Sie einfach die Zeichenkette $master im Namen Ihrer PO-Dateien auf der "[po4a_paths]"-Zeile wie folgt verwenden:

 [po4a_paths] dok/$master/$master.pot $lang:dok/$master/$lang.po

Falls es Namenskonflikte gibt, da mehrere Dateien den gleichen Dateinamen haben, kann der Name der Masterdatei über das Hinzufügen der Option "master:file="Name festgelegt werden:

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

Im getrennten Modus baut po4a während der PO-Aktualisierung ein temporäres Kompendium auf, um die Übersetzungen zwischen allen PO-Dateien gemeinsam zu benutzen. Falls zwei PO-Dateien eine verschiedene Übersetzung der gleichen Zeichenkette haben, wird po4a diese Zeichenkette mit »fuzzy« markieren und beide Übersetzungen in alle PO-Dateien einstellen, die diese Zeichenkette enthalten. Wenn der Übersetzer die Zeichenkette bereinigt, dann wird die Übersetzung automatisch in jede PO-Datei übernommen.

Angabe der zu übersetzenden Dokumente¶

Sie müssen auch die zu übersetzenden Dokumente aufführen. Für jede Master-Datei müssen Sie den zu verwendenden Format-Auswerter, den Ort der zu erstellenden Dokumente und optional weitere Konfiguration festlegen. Beispiel:

 [type: sgml] dok/mein_zeug.sgml fr:dok/fr/mon_truc.sgml \
              de:dok/de/mein_kram.sgml
 [type: man] script fr:dok/fr/script.1 de:dok/de/script.1
 [type: docbook] dok/script.xml fr:dok/fr/script.xml \
             de:dok/de/script.xml

Aber diese drei komplexen Zeilen sind wieder schwer zu lesen und zu verändern, z.B. wenn neue Sprachen hinzugefügt werden. Es ist viel einfacher, die Dinge neu mittels der Vorlage $lang wie folgt zu organisieren:

 [type: sgml]    dok/mein_zeug.sgml $lang:dok/$lang/mein_zeug.sgml
 [type: man]     script.1           $lang:po/$lang/script.1
 [type: docbook] dok/script.xml     $lang:dok/$lang/script.xml

Angabe der Optionen¶

Es gibt zwei Arten von Optionen: Po4a-Optionen sind Vorgabewerte für die Po4a-Befehlszeilenoptionen, während Formatoptionen zur Änderung des Verhaltens der Formatauswertprogramme verwandt werden. Als Po4a-Option könnten Sie beispielsweise in Ihrer Konfigurationsdatei festlegen, dass der Vorgabewert für den Befehlszeilenparameter von --keep 50% statt 80% beträgt. Formatoptionen sind in ihren speziellen Handbuchseiten für jedes Auswertmodul dokumentiert, z.B. Locale::Po4a::Xml(3pm). Sie könnten beispielsweise nostrip an das XML-Auswertprogramm übergeben, um die Leerzeichen rund um herausgelöste Zeichenketten nicht zu entfernen.

Sie können diese Optionen für eine bestimmte Masterdatei oder sogar für eine bestimmte Übersetzung dieser Datei mittels "opt:" und "opt_XX:" für die Sprache "XX" übergeben. Im nachfolgenden Beispiel wird die Option nostrip für den XML-Auswerter (für alle Sprachen) übergeben, während der Schwellwert für die französische Übersetzung auf 0% reduziert wird (diese wird daher immer beibehalten).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

Auf jeden Fall müssen diese Konfigurationsteile sich am Ende der Zeile befinden. Die Erklärung der Dateien muss zuerst kommen, dann das Addendum, falls vorhanden, (siehe unten) und dann nur die Optionen. Die Gruppierung der Konfigurationsteile ist nicht sehr wichtig, da die Elemente intern als Zeichenketten aneinandergehängt werden. Die folgenden Beispiele sind alle äquivalent:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Beachten Sie, dass beim Bau von POT-Dateien die sprachspezifischen Optionen nicht verwandt werden. Es ist beispielsweise unmöglich, nostrip nur an das Auswertprogramm zu übergeben, wenn die französische Übersetzung gebaut wird, da die gleiche POT-Datei zur Aktualisierung aller Sprachen verwandt wird. Daher sind die einzigen sprachspezifischen Optionen diejenigen, die bei der Erstellung der Übersetzung verwandt werden können, wie die Option "--keep".

Konfigurationsaliase

Um die gleiche Option an mehrere Dateien zu übergeben, ist es am besten, wie folgt einen Typ-Alias zu definieren. Im nächsten Beispiel wird "--keep 0" an jede italienische Übersetzung mittels dieses Typs "test" übergeben, der eine Erweiterung des Typs "man" ist.

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Sie können auch einen bestehenden Typ wie folgt erweitern, um den gleichen Aliasnamen erneut zu benutzen. Dies wird nicht als fehlerhafte rekursive Definition interpretiert.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Globale Vorgabeoptionen

Sie können auch "[options]"-Zeilen verwenden, um Optionen zu definieren, die für alle Dateien, unabhängig von deren Typ, verwandt werden müssen.

  [options] --keep 20 --option nostrip

Wie bei Befehlszeilenoptionen können Sie die in der Konfigurationsdatei übergebenen Parameter abkürzen:

  [options] -k 20 -o nostrip

Optionsprioritäten

Die Optionen jeder Quelle werden aneinandergehängt, wodurch sichergestellt wird, dass die Vorgabewerte leicht durch speziellere Optionen außer Kraft gesetzt werden können. Die Reihenfolge ist wie folgt:

• "[options]"-Zeilen stellen Vorgabewerte bereit, die durch jede andere Quelle außer Kraft gesetzt werden können.
• Dann werden Typ-Aliase verwandt. Sprachspezifische Einstellungen setzen die für alle Sprachen angewandten Einstellungen außer Kraft.
• Einstellungen, die für eine gegebene Master-Datei spezifisch sind, setzen sowohl die Vorgabe- als auch die von Typ-Alias kommenden Einstellungen außer Kraft. In diesem Fall setzen auch sprachspezifische Einstellungen die globalen außer Kraft.
• Schließlich setzen auf der po4a-Befehlszeile bereitgestellte Parameter alle Einstellungen aus Konfigurationsdateien außer Kraft.

Beispiel

Hier ist ein Beispiel, das zeigt, wie Leer- und Anführungszeichen maskiert werden:

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

Addendum: Zusätzliche Inhalte in der Übersetzung hinzufügen¶

Falls Sie einen zusätzlichen Abschnitt zu der Übersetzung hinzufügen möchten, beispielsweise für Danksagungen an den Übersetzer, müssen Sie ein Addendum für die Zeile, die ihre Master-Datei definiert, hinzufügen. In der Handbuchseite po4a(7) finden Sie weitere Details zu der Syntax von Addendum-Dateien.

 [type: pod] script fr:dok/fr/script.1 \
             add_fr:dok/l10n/script.fr.add

Sie können wie folgt auch Sprachvorlagen verwenden:

 [type: pod] Skript $lang:dok/$lang/script.1 \
             add_$lang:dok/l10n/script.$lang.add

Falls ein Addendum nicht angewandt werden kann, wird die Übersetzung verworfen.

Attribute für die Addendum-Angabe

Addendum-Attribute können die Konfigurationsdatei in Fällen, in denen nicht alle Sprachen ein Addendum bereitstellen oder wenn sich Addenda von Sprache zu Sprache verändern, vereinfachen. Das Attribut ist ein einzelnes Zeichen, das sich vor dem Dateinamen befindet.

?

Berücksichtige Addendum_Pfad falls die Datei existiert, andernfalls passiert nichts.

@

Addendum_Pfad ist kein reguläres Addendum, sondern eine Datei, die eine Liste von Addenda enthält, eines pro Zeile. Jedem Addendum kann ein Modifikator vorangestellt sein.

!

Addendum_Pfad wird verworfen, es wird nicht geladen und wird auch nicht von weiteren Addendumspezifikationen geladen.

Folgendes Beispiel enthält ein Addendum für jede Sprache, aber nur, falls es existiert. Falls es nicht existiert, wird kein Fehler gemeldet.

 [type: pod] script $lang:dok/$lang/script.1  add_$lang:?dok/l10n/script.$lang.add

Folgendes Beispiel enthält eine Liste von Addenda für jede Sprache:

 [type: pod] script $lang:dok/$lang/script.1  add_$lang:@dok/l10n/script.$lang.add

Übersetzte Zeichenketten filtern¶

Manchmal möchten Sie einige Zeichenketten vor dem Übersetzungsprozess verstecken. Um dies zu erreichen, können Sie einen "pot_in"-Parameter an Ihre Masterdatei übegeben, um den Namen der Datei festzulegen, die statt des echten Masters für den Bau der POT-Datei verwandt werden soll. Hier ist ein Beispiel:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Mit dieser Einstellung werden die zu übersetzenden Zeichenketten aus book-filtered.xml herausgelöst (diese Datei muss vor dem Aufruf von po4a erstellt worden sein), während die übersetzten Dateien aus book.xml heraus gebaut werden. Damit wird jede Zeichenkette, die Teil von book.xml ist, aber nicht in book-filtered.xml vorkommt, nicht Teil der PO-Dateien sein und damit verhindert, dass die Übersetzer eine Übersetzung davon bereitstellen. Daher verbleiben diese Zeichenketten bei der Erstellung übersetzter Dokumente unverändert. Damit wird logischerweise der Anteil der Übersetzung reduziert und Sie könnten die Option "--keep" verwenden müssen, um sicherzustellen, dass das Dokument trotzdem erstellt wird.

KONFIGURATIONSBEISPIEL¶

TODO: Ist dieser Abschnitt wirklich nützlich?

Nehmen wir an, Sie betreuen ein Paket namens foo mit der Handbuchseite man/foo.1, die naturgemäß nur auf Englisch gewartet wird. Als (Distributions-)Betreuer wollen Sie jetzt Übersetzungen erstellen und betreuen. Zuerst müssen Sie die POT-Datei mittels po4a-gettextize(1) erstellen, die zum Senden an die Übersetzer notwendig ist.

In diesem Fall würde folgender Aufruf erfolgen:

 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Diese Datei schicken Sie dann an die entsprechenden Sprachlisten oder bieten sie auf Ihrer Website zum Herunterladen an.

Nehmen wir jetzt an, dass Sie drei Übersetzungen vor Ihrer nächsten Veröffentlichung erhalten haben: de.po (mit einem Addendum de.add), sv.po und pt.po. Da Sie Ihre Makefile(s) nicht ändern möchten, wenn eine neue Übersetzung eintrifft, können Sie po4a mit einer geeigneten Konfigurationsdatei (in diesem Beispiel po4a.cfg) in Ihrer Makefile aufrufen. In unserem Beispiel würde diese Konfigurationdatei dann wie folgt aussehen:

 [po_directory] man/po4a/po/
 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
            add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
In diesem Beispiel wird angenommen, dass die erstellte Handbuchseite (und
alle PO- und Addenda-Dateien) in F<man/translated/$lang/> (respektive
F<man/po4a/po/> und F<man/po4a/add_$lang/>) unterhalb des aktuellen
Verzeichnisses gespeichert werden. In diesem Beispiel würde dann das
Verzeichnis F<man/po4a/po/> die Dateien F<de.po>, F<pt.po> und F<sv.po>
enthalten und das Verzeichnis F<man/po4a/add_de/> die Datei F<de.add>.

Beachten Sie die Verwendung des Modifikators ?, da nur die deutsche Übersetzung (de.po) von einem Addendum begleitet wird.

Um dann die übersetzten Handbuchseiten tatsächlich zu bauen, würde (einmalig!) die folgende Zeile in das build-Ziel der entsprechenden Makefile eingebaut werden:

        po4a po4a.cfg

Sobald dies eingerichtet ist, müssen Sie die Makefile nicht mehr anfassen, wenn eine neue Übersetzung eintrifft, d.h. falls das französische Team Ihnen fr.po und fr.add schickt, dann packen Sie diese einfach in man/po4a/po/ respektive man/po4a/add_fr/ und beim nächsten Mal, wenn das Programm gebaut wird, wird auch die französische Übersetzung automatisch in man/translated/fr/ gebaut.

Beachten Sie, dass Sie weiterhin ein geeignetes Ziel in der Makefile benötigen, um die übersetzten Handbuchseiten zusammen mit den englischen zu installieren.

Falls Sie die automatisch erstellten Dateien nicht in Ihrem Versionskontrollsystem speichern wollen, benötigen Sie schließlich noch eine Zeile zum Ziel clean:
-rm -rf man/translated