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 Dokumentation des Gettext-Programms.
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
- Dies gibt das Referenzformat an. Es kann entweder
none (keine Referenz erzeugen), noline (keine Zeilennummern
angeben) oder full (komplette Referenzen einbinden) sein.
Funktionen für gesamte Nachrichtenkataloge¶
- 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).
- gettextize($$)
- Diese Funktion erstellt einen übersetzten
Nachrichtenkatalog aus zwei Katalogen, ein Original und eine
Übersetzung. Dieser Prozess wird im Abschnitt Gettextization: Wie
funktioniert es? in po4a(7) beschrieben.
- 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
- get_charset()
- gibt den in den PO-Kopfzeilen definierten Zeichensatz
zurück. Falls er nicht gesetzt wurde, wird »CHARSET«
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 »CHARSET« 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)