Das po4a-Programm ist nützlich, wenn Sie den Aufruf von po4a-gettextize(1), po4a-updatepo(1) und po4a-translate(1) in komplexen Makefiles bei der Verwendung mehrerer Dateien zur Übersetzung, verschiedenen Formaten oder der Notwendigkeit, verschiedene Optionen für verschiedene Dokumente anzugeben, vermeiden wollen.
Angabe der Pfade zu den Eingaben der Übersetzer
Automatische Erkennung der Pfade und Sprachen
Angabe der zu übersetzenden Dokumente
Angabe der Optionen für die Module
Angabe der Aliase
Es erlaubt es Ihnen auch, Dokumente mit verschiedenen Formaten in die gleiche POT-Datei zu mischen, so dass Sie nur eine solche Datei pro Projekt haben müssen.
Das Verhalten kann durch andere Werkzeuge aus der Po4a-Suite nachgebildet werden (z.B. mit Makefiles). Allerdings ist es recht schwierig und ermüdend, die gleichen komplizierten Makefiles für jedes Po4a-verwendende Projekt immer wieder zu erstellen.
Der Datenfluss kann wie folgt zusammengefasst werden. Jede Änderung am Master-Dokument wird sich in den PO-Dateien wiederspiegeln und alle Änderungen in den PO-Dateien (sowohl manuell als auch verursacht durch den vorherigen Schritt) spiegeln sich in den übersetzten Dokumenten wieder.
Master-Dokument --> PO-Dateien --> Übersetzungen
Der Datenfluss kann von dem Werkzeug nicht invertiert werden und Änderungen an der Übersetzung werden vom Inhalt der PO-Dateien überschrieben. Tatsächlich kann dieses Werkzeug nicht dazu verwandt werden, existierende Übersetzungen in das Po4a-System umzuwandeln. Für diese Aufgabe verwenden Sie bitte po4a-gettextize(1).
Kommentare in dieser Datei werden durch das Zeichen »#« markiert. Es kommentiert alles bis zum Zeilenende aus. Zeilen können fortgesetzt werden, indem das Zeilenende markiert wird. Alle nicht leeren Zeilen müssen mit einem []-Befehl beginnen, gefolgt von seinen Argumenten. (so klingt das schwierig, aber es ist recht einfach, hoffe ich zumindest ;)
Dieser optionale Befehl kann die gesamte Konfigurationsdatei vereinfachen und damit skaliert sie auch besser. Sie müssen eine Liste von Sprachen angeben, in die Sie die Dokumente übersetzen möchten. Dies ist so einfach wie das folgende Beispiel:
[po4a_langs] fr de
Dies ermöglicht es Ihnen, $lang auf alle angegebenen Sprachen in dem Rest der Konfigurationsdatei zu expandieren.
Zuerst müssen Sie angeben, wo die Eingabedateien der Übersetzer (d.h. die Dateien, die von den Übersetzern für ihre Aufgabe verwandt werden) liegen. Dies kann durch ein Zeile der folgenden Form geschehen:
[po4a_paths] doc/l10n/projekt.dok.pot \
fr:doc/l10n/fr.po de:doc/l10n/de.po
Der Befehl ist somit [po4a_paths]. Das erste Argument ist der Pfad zu der zu verwendenden POT-Datei. Alle folgenden Argumente sind von der folgenden selbsterklärenden Form:
<Sprache>:<Pfad zu der PO-Datei für diese Sprache>
Falls Sie die Vorlagensprachen definiert haben, können Sie die obige Zeile wie folgt umschreiben:
[po4a_paths] doc/l10n/projekt.dok.pot $lang:doc/l10n/$lang.po
Sie können auch $master verwenden, um sich auf den Dateinamen des Dokuments zu beziehen. In diesem Fall wird po4a einen Aufspaltungsmodus verwenden: eine POT und eine PO (für jede Sprache) für jedes in der Konfigurationsdatei von po4a angegebene Dokument wird erstellt. Lesen Sie den Abschnitt Aufspaltungsmodus.
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Dieser Befehl sollte nicht zusammen mit den Befehlen [po4a_langs] oder [po4a_paths] verwandt werden.
Wenn Sie diesen Befehl verwenden, müssen Sie beim ersten Aufruf von po4a eine leere POT-Datei erstellen, um ihm dem Namen der POT-Datei mitzuteilen.
[po_directory] po4a/po/
[type: sgml] dok/mein_zeug.sgml fr:dok/fr/mon_truc.sgml \
de:dok/de/mein_kram.sgml
[type: pod] skript fr:dok/fr/script.1 de:doc/de/script.1 \
add_fr:doc/l10n/script.fr.add
Dies sollte auch recht selbsterklärend sein. Beachten Sie, dass im zweiten Fall dok/l10n/script.fr.add ein Addendum ist, dass zu der französischen Version dieses Dokumentes hinzugefügt wird. Bitte lesen Sie po4a(7) für weitere Informationen über Addenda.
Formaler beschrieben lautet das Format:
[type: <Format>] <Master_dok> (<Sprache>:<lokalisiertes_Dok>)* \
(add_<Sprache>:<Modifikator>*<Addendum_Pfad>)*
Falls es keinen Modifikator gibt, ist Addendum_Pfad der Pfad zum Addendum. Modifikatoren sind
Falls Sie die Vorlagensprachen definiert haben, können Sie die obige Zeile wie folgt umschreiben:
[type: pod] Skript $lang:dok/$lang/script.1 \
add_fr:dok/l10n/script.fr.add
Falls alle Sprachen Addenda mit ähnlichen Pfaden haben, können Sie auch Folgendes schreiben:
[type: pod] Skript $lang:dok/$lang/script.1 \
add_$lang:dok/l10n/script.$lang.add
Falls Sie eine bestimmte Option für eines der zu übersetzenden Dokumente benötigen, können Sie diese auch in der Konfigurationsdatei angeben. Optionen werden durch das Schlüsselwort opt eingeleitet. Das Argument des Schlüsselworts opt muss mit doppelten Anführungszeichen geschützt werden, falls es ein Leerzeichen enthält (z.B. wenn Sie mehrere Optionen oder Optionen mit Argument angeben wollen). Sie können Optionen, die nur für eine bestimmte Sprache angewandt werden sollen, auch mittels des Schlüsselworts opt_Sprache angeben.
Hier ist ein Beispiel:
[type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt:``-k 75'' opt_it:``-L UTF-8'' opt_fr:-v
Argumente dürfen Leerzeichen enthalten, falls Sie einfache Anführungszeichen
oder geschützte doppelte Anführungszeichen verwenden:
[po4a_alias:man] man opt:``-o \''mdoc=NAME,SEE ALSO\`` -k 20''
Falls Sie die gleichen Optionen für viele Dokumente angeben möchten, bietet sich die Verwendung eines Alias an (lesen Sie den Abschnit Angabe der Aliase unten).
Sie können auch Optionen für alle in der Konfigurationsdatei angegebenen
Dokumente festlegen:
[options] opt:``…'' opt_fr:``…''
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
Dies definiert einen Modul-Alias namens test, basierend auf dem Modul man, wobei -k 21 auf alle Sprachen und -o debug=splitargs für die spanische Übersetzung angewandt werden soll.
Dieser Modul-Alias kann wie ein reguläres Modul verwandt werden:
[type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
Beachten Sie, dass Sie pro Datei zusätzliche Optionen angeben können.
Bei der Verwendung des Aufspaltungsmodus wird eine temporäre große POT- und temporäre große PO-Dateien eingesetzt. Dies erlaubt es, die Übersetzungen in allen POs gemeinsam zu nutzen.
Wenn die gleiche Zeichenkette in zwei POs verschieden übersetzt ist, wird po4a diese Zeichenkette als unscharf markieren und beide Übersetzungen in alle PO-Dateien, die diese Zeichenketten enthalten, einfügen. Wenn dann ein Übersetzer die Übersetzung aktualisiert und die Fuzzy-Markierung in einer PO-Datei entfernt, wird diese Übersetzung der Zeichenkette in allen PO-Dateien automatisch aktualisiert.
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
Das Standardverhalten (wenn --force nicht angegeben ist) ist wie folgt:
Eine Übersetzung wird auch nur neu erstellt, falls das Master-Dokument, die PO-Datei, einer ihrer Addenda oder die Konfigurationsdatei neuer ist. Um zu vermeiden, dass die Erstellung von Übersetzungen, die die Schwellwertbarriere nicht erreichen, versucht wird (siehe --keep), kann eine Datei mit der Erweiterung .po4a-stamp erstellt werden (siehe --stamp).
Falls ein Master-Dokument Dateien einbindet, soillten Sie den Schalter --force verwenden, da der Änderungszeitpunkt dieser eingebundenen Dateien nicht mit betrachtet wird.
Die PO-Dateien werden basierend auf der POT-Datei mittels msgmerge -U neu erstellt.
Hinweis: Dies aktiviert nur die Erstellung der .po4a-stamp-Dateien. Die Stempeldateien werden immer benutzt, falls sie existieren, und sie werden mit --rm-translations oder wenn die Datei schließlich übersetzt ist entfernt.
Das Argument kann von einem Komma und entweder dem Schlüsselwort wrap oder nowrap gefolgt werden. Referenzen werden standardmäßig auf eine einzelne Zeile geschrieben. Die Option wrap bricht Referenzen über mehre Zeilen um, um die gettext (xgettext und msgmerge) nachzuahmen. Diese Option wird in zukünftigen Veröffentlichungen die Vorgabe werden, da sie vernünftiger ist. Die Option nowrap ist für Benutzer, die das alte Verhalten beibehalten möchten, verfügbar.
Hinweis: $lang wird zur aktuellen Sprache erweitert.
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
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL (siehe die Datei COPYING) vertreiben und/oder verändern.