Provided by: po4a_0.69-1_all 
NAME
Locale::Po4a::Po - PO-Dateien-Manipulationsmodul
ÜBERSICHT
use Locale::Po4a::Po;
my $pofile=Locale::Po4a::Po->new();
# PO-Datei einlesen
$pofile->read('Datei.po');
# Einen Eintrag hinzufügen
$pofile->push('msgid' => 'Hallo', 'msgstr' => 'bonjour',
'flags' => "wrap", 'reference'=>'file.c:46');
# Eine Übersetzung extrahieren
$pofile->gettext("Hello"); # liefert »bonjour«
# In eine Datei zurückschreiben
$pofile->write('andereDatei.po');
BESCHREIBUNG
Locale::Po4a::Po ist ein Modul, das Ihnen die Bearbeitung von Nachrichtenkatalogen
ermöglicht. Sie können eine Datei laden und in sie schreiben (deren Erweiterung oft po
lautet), Sie können dynamisch neue Einträge hinzufügen oder um die Übersetzung einer
Zeichenkette bitten.
Für eine umfangreichere Beschreibung der Nachrichtenkataloge im PO-Format und ihren
Einsatz lesen Sie bitte die Info-Dokumentation des Gettext-Programms (Knoten »PO Files«).
Dieses Modul ist Teil des Po4a-Projekts, dessen Ziel es ist, PO-Dateien (ursprünglich dazu
erstellt, um die Übersetzung von Programmmeldungen zu erleichtern) zur Übersetzung von
allem einzusetzen, darunter Dokumentation (Handbuchseiten, Info-Handbücher),
Paketbeschreibungen, Debconf-Vorlagen und allem, das daraus Nutzen ziehen kann.
VON DIESEM MODUL AKZEPTIERTE OPTIONEN
--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 handzuhaben, 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.
--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«.
Funktionen, die gesamte Nachrichtenkataloge betreffen
new()
Erstellt einen neuen Nachrichtenkatalog. Falls ein Argument angegeben ist, ist es der
Name der PO-Datei, die geladen werden soll.
read($)
Liest eine PO-Datei ein (deren Namen als Argument übergeben wird). Vorherige Einträge
in »self« werden nicht entfernt, die neuen werden am Ende des Katalogs hinzugefügt.
write($)
schreibt den aktuellen Katalog in die übergebene Datei
write_if_needed($$)
Wie write, aber falls die PO- oder POT-Datei bereits existiert, wird das Objekt in
eine temporäre Datei geschrieben, die mit der bestehenden Datei verglichen wird, um zu
überprüfen, ob eine Aktualisierung benötigt wird (dies vermeidet eine Änderung an der
POT-Datei, um lediglich eine Zeilenreferenz oder das Feld »POT-Creation-Date« zu
aktualisieren).
filter($)
Diese Funktion löst einen Katalog aus einem bestehenden heraus. Nur die Einträge, die
eine Referenz in der angegebenen Datei haben, werden in dem resultierenden Katalog
eingefügt.
Diese Funktion wertet ihr Argument aus, konvertiert es in eine Perl-
Funktionsdefinition, wertet diese Definition aus und filtert die Felder heraus, für
die diese Funktion wahr zurückliefert.
Manchmal liebe ich Perl ;)
to_utf8()
Wandelt die Kodierung der Msgstrs in der PO-Datei in UTF-8. Führt nichts aus, falls
der Zeichensatz (Wert von »CHARSET«) in der PO-Datei nicht angegeben ist oder falls es
bereits UTF-8 oder ASCII ist.
Funktionen, die einen Nachrichtenkatalog für Übersetzungen verwenden
gettext($%)
Erbittet die Übersetzung der als Argument übergebenen Zeichenkette im aktuellen
Katalog. Die Funktion liefert die ursprüngliche (unübersetzte) Zeichenkette zurück,
falls die Zeichenkette nicht gefunden wurde.
Nach der zu übersetzenden Zeichenkette können Sie einen Hash mit zusätzlichen
Argumenten übergeben. Dabei gibt es die folgenden gültigen Einträge:
wrap
Logische Variable, die angibt, ob davon ausgegangen werden kann, dass Leerzeichen
in Zeichenketten nicht wichtig sind. Falls ja, überführt die Funktion die
Zeichenkette in eine kanonische Form, bevor sie nach einer Übersetzung sucht, und
bricht das Ergebnis um.
wrapcol
die Spalte, an der umgebrochen werden soll (standardmäßig 76)
stats_get()
Liefert Statistiken über das Trefferverhältnis von Gettext seit dem letzten Aufruf von
stats_clear() zurück. Beachten Sie, dass dies nicht die gleiche Statistik ist, die von
»msgfmt --statistic« ausgegeben wird. Hier berichtet die Statistik über die kürzliche
Verwendung der PO-Datei, während Msgfmt über den Status der Datei berichtet. Beispiel:
[einige Arbeiten mit der PO-Datei, um Zeugs zu übersetzen]
($percent,$hit,$queries) = $pofile->stats_get();
print "Bisher wurden Übersetzungen für $percent\% ($hit von $queries) der Zeichenketten gefunden.\n";
stats_clear()
bereinigt die Statistiken über Gettext-Treffer
Funktionen, um einen Katalog mit Meldungen aufzubauen
push(%)
Schiebt einen neuen Eintrag an das Ende des aktuellen Katalogs. Die Argumente sollten
eine Hash-Tabelle darstellen. Die gültigen Schlüssel sind:
msgid
die Zeichenkette in der Ursprungssprache
msgstr
die Übersetzung
reference
eine Angabe, wo die Zeichenkette gefunden wurde. Beispiel: Datei.c:46 (d.h. in
Datei.c, Zeile 46). Es kann eine durch Leerzeichen getrennte Liste sein, falls die
Zeichenkette mehrfach vorkommt.
comment
ein manuell (vom Übersetzer) hinzugefügter Kommentar. Das Format ist hier frei.
automatic
ein automatisch hinzugefügter Kommentar, der vom Zeichenkettenausleseprogramm
hinzugefügt wurde. Lesen Sie zu der Option »--add-comments« des Programms xgettext
für weitere Informationen hierzu.
flags
durch Leerzeichen getrennte Liste aller definierten Schalter für diesen Eintrag.
Gültige Schalter sind: c-text, python-text, lisp-text, elisp-text, librep-text,
smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap,
no-wrap und fuzzy.
Lesen Sie die Getttext-Dokumentation bezüglich ihrer Bedeutung.
type
Dies ist hauptsächlich ein internes Argument: Es wird beim Einbau von Gettext in
Dokumente verwandt. Die Idee hierbei ist, sowohl das Original als auch die
Übersetzung in ein PO-Objekt auszuwerten und sie dann zusammenzuführen, wobei die
Mgsids des einen die Msgids werden und die Mgsgids des anderen die Msgstr. Um
sicherzustellen, dass alles stimmig wird, wird jeder Msgid in PO-Objekten ein Typ
vergeben, basierend auf ihrer Struktur (wie »chapt«, »sect1«, »p« und so weiter in
Docbook). Falls die Typen der Zeichenketten nicht übereinstimmen, bedeutet dies,
dass die beiden Dateien nicht über die gleiche Struktur verfügen. Der Prozess
liefert dann eine Fehlermeldung.
Diese Information wird als automatischer Kommentar in die PO-Datei geschrieben, da
dies den Übersetzern Kontext zu den zu übersetzenden Zeichenketten liefert.
wrap
Logische Variable, die angibt, ob Leerzeichen bei kosmetischen Neuformatierungen
gequetscht werden dürfen. Falls wahr, wird die Zeichenkette vor der Verwendung in
eine kanonische Form gebracht.
Diese Information wird mit dem Schalter wrap oder no-wrap in die PO-Datei
geschrieben.
wrapcol
die Spalte, an der umgebrochen werden soll (standardmäßig 76)
Diese Information wird nicht in die PO-Datei geschrieben.
Verschiedene Funktionen
count_entries()
liefert die Anzahl an Einträgen im Katalog (ohne die Kopfzeilen)
count_entries_doc()
Liefert die Anzahl der Einträge im Dokument. Falls eine Zeichenkette mehrfach im
Dokument auftaucht, wird sie auch mehrfach gezählt.
msgid($)
liefert die Msgid der angegebenen Nummer
msgid_doc($)
liefert die Msgid mit der angegebenen Position im Dokument
type_doc($)
Liefert den Typ der Msgid mit der angegebenen Position im Dokument zurück. Dies ist
wahrscheinlich nur für die Gettextisierung nützlich, und es wird separat von
{$msgid}{'type'} gespeichert, da letzterer Ort durch einen anderen Typ überschrieben
werden könnte, falls die $msgid im Master-Dokument mehrfach vorkommt.
get_charset()
gibt den in den PO-Kopfzeilen definierten Zeichensatz zurück. Falls er nicht gesetzt
wurde, wird »UTF-8« zurückgegeben.
set_charset($)
Dies setzt den Zeichensatz der PO-Kopfzeilen auf den Wert, der im ersten Argument
angegeben wurde. Falls Sie diese Funktion nie aufrufen (und keine Datei mit einem
angegebenen Zeichensatz gelesen wird), wird der Standardwert auf »UTF-8« belassen.
Dieser Wert ändert nicht das Verhalten dieses Moduls, er wird nur benutzt, um das Feld
in den Kopfzeilen zu füllen und es in get_charset() zurückzuliefern.
AUTOREN
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)