po4a(1) PO-Dateien und übersetzte Dokumente auf einen Rutsch aktualisieren

ÜBERSICHT

po4a [Optionen] Konfig_Datei

BESCHREIBUNG

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

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.

Inhaltsverzeichnis

Das Dokument ist wie folgt organisiert:

BESCHREIBUNG

EINLEITUNG

SYNTAX DER KONFIGURATIONSDATEI

Angabe der Vorlagensprache

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

Aufspaltungsmodus

OPTIONEN

BEISPIEL

SCHWÄCHEN

AUTOREN

URHEBERRECHT UND LIZENZ

EINLEITUNG

Das Programm po4a ist sowohl für das Aktualisieren der PO-Dateien (zum Synchronisieren mit den ursprünglichen Dokumenten) als auch der übersetzten Dokumente (zum Synchronisieren mit den PO-Dateien) zuständig. Der Hauptpunkt besteht darin, die Verwendung von Po4a zu erleichtern, ohne die Befehlszeilenoptionen auswendig zu können.

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

SYNTAX DER KONFIGURATIONSDATEI

Das (verpflichtende) Argument ist der Pfad zu der zu verwendenden Konfigurationsdatei. Die Syntax zielt darauf ab, so einfach und ähnlich zu sein wie die Konfigurationsdateien, die von den intl-tools-Projekten verwandt werden.

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

Angabe der Vorlagensprache

Hinweis: Es wird empfohlen, [po_directory] statt [po4a_langs] und [po4a_paths] zu verwenden. Lesen Sie den Abschnitt Automatische Erkennung der Pfade und Sprachen weiter unten.

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.

Angabe der Pfade zu den Eingaben der Übersetzer

Hinweis: Es wird empfohlen, [po_directory] statt [po4a_langs] und [po4a_paths] zu verwenden. Lesen Sie den Abschnitt Automatische Erkennung der Pfade und Sprachen weiter unten.

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

Automatische Erkennung der Pfade und Sprachen

Ein weiterer Befehl kann zur Angabe des Verzeichnisses, in dem sich die PO- und POT-Dateien befinden, verwandt werden. Wenn er verwandt wird, wird po4a die POT-Datei als die einzige *.pot-Datei aus dem angegebenen Verzeichnis erkennen. po4a wird auch die Liste der *.po-Dateien aus der Liste der definierten Sprachen (unter Entfernen der Erweiterung) verwenden. Diese Sprachen werden für die Ersetzung der Variablen $lang in der restlichen Konfigurationsdatei verwandt.

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/

Angabe der zu übersetzenden Dokumente

Logischerweise müssen Sie jetzt angeben, welche Dokumente übersetzt sind, ihr Format und wohin die Übersetzung abgelegt werden soll. Dies kann durch folgende Zeilen erfolgen:

 [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

?
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.

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

Angabe der Optionen für die Module

po4a akzeptiert Optionen, die an die Module weitergegeben werden. Diese Optionen hängen von den Modulen ab und werden mit dem Schalter -o angegeben.

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:``…''

Angabe der Aliase

Falls Sie die gleichen Optionen für mehrere Dateien angeben müssen, könnten Sie an der Definition eines Modul-Alias interessiert sein. Dies kann folgendermaßen geschehen:

[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.

Aufspaltungsmodus

Der Aufspaltungsmodus wird verwandt, wenn $master in der Zeile [po4a_paths] eingesetzt wird.

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.

OPTIONEN

-k, --keep
Minimaler Schwellwert in Prozent, ab der die übersetzte Datei erhalten (d.h. geschrieben) wird, standardmäßig 80. D.h., standardmäßig müssen Dateien zu 80% übersetzt sein, um geschrieben zu werden.
-h, --help
zeigt eine kurze Hilfemeldung an
-M, --master-charset
Zeichensatz der Dateien, die die zu übersetzenden Dokumente enthalten. Beachten Sie, das derzeit alle Master-Dokumente den gleichen Zeichensatz benutzen müssen. Dies ist eine bekannte Einschränkung und wir arbeiten an einer Lösung.
-L, --localized-charset
Zeichensatz der Dateien, die die lokalisierten Dokumente enthalten. Beachten Sie, dass derzeit alle übersetzten Dokumente den gleichen Zeichensatz benutzen. Dies ist eine bekannte Einschränkung und wir arbeiten daran, dies zu beheben.
-A, --addendum-charset
Zeichensatz der Addenda. Beachten Sie, dass alle Addenda im gleichen Zeichensatz vorliegen sollten.
-V, --version
zeigt die Version des Skripts und beendet sich
-v, --verbose
Erhöhen der Ausführlichkeit des Programms
-q, --quiet
Verringern der Ausführlichkeit des Programms
-d, --debug
Fehlersuch- (Debug-)Informationen ausgeben
-o, --option
Extraoption(en), die an die Formaterweiterung übergeben werden soll. Geben Sie jede Option im Format »Name=Wert« an. Lesen Sie die Dokumentation jeder Erweiterung für weitere Informationen über die gültigen Optionen und ihre Bedeutungen.
-f, --force
immer die POT- und PO-Dateien erstellen, selbst wenn po4a dies nicht für notwendig betrachtet

Das Standardverhalten (wenn --force nicht angegeben ist) ist wie folgt:

Falls die POT-Datei bereits existiert, wird sie neu erstellt, falls ein Master-Dokument oder die Konfigurationsdatei neuer ist. Die POT-Datei wird auch in ein temporäres Dokument geschrieben und po4a überprüft, dass die Änderungen wirklich benötigt werden.

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.

--stamp
Sorgt dafür, dass po4a Stempeldateien erstellt, wenn eine Übersetzung nicht erstellt wurde, da sie den Schwellwert nicht erreichte. Diese Stempeldateien werden entsprechend des erwarteten übersetzten Dokuments, mit der Erweiterung .po4a-stamp, benannt.

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.

--no-translations
die übersetzten Dokumente nicht erstellen, nur die POT- und PO-Dateien aktualisieren
--rm-translations
entfernt die übersetzten Dateien (impliziert --no-translations)
--no-backups
Seit Version 0.41 macht dieser Schalter nichts und könnte daher in zukünftigen Veröffentlichungen entfernt werden.
--rm-backups
Seit Version 0.41 macht dieser Schalter nichts und könnte daher in zukünftigen Veröffentlichungen entfernt werden.
--translate-only übersetzte-Datei
Nur die angegebene Datei übersetzen. Das kann nützlich sein, um die Verarbeitung zu beschleunigen, falls die Konfigurationsdatei eine Reihe Dateien enthält. Beachten Sie, dass diese Optione die PO- und POT-Dateien nicht aktualisiert. Diese Option kann mehrfach angewandt werden.
--variable Var=Wert
Definiert eine Variable, die in der po4a-Konfigurationsdatei expandiert wird. Jedes Vorkommen von $(Var) wird durch Wert ersetzt. Diese Option kann mehrfach verwandt werden.
--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«.
--msgmerge-opt Optionen
Extraoptionen für msgmerge.

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.
--srcdir QUELLVERZ
setzt das Basisverzeichnis für alle Eingabedokumente, die in der Konfigurationsdatei po4a angegeben sind
--destdir ZIELVERZ
setzt das Basisverzeichnis für alle in der po4a-Konfigurationsdatei angegebenen Dokumente

BEISPIEL

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

SCHWÄCHEN

  • Dupliziert Teil des Codes von den po4a-*-Programmen.

Patches willkommen ;)

AUTOREN

 Denis Barbier <[email protected]>
 Nicolas François <[email protected]>
 Martin Quinson (mquinson#debian.org)

URHEBERRECHT UND LIZENZ

Copyright 2002-2012 SPI, Inc.

Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL (siehe die Datei COPYING) vertreiben und/oder verändern.