NAME¶

Ü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¶

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[,wrap|nowrap]

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

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.

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

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:

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:

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.

equals_msgid(po)

Liefert ($uptodate, $diagnostic) zurück, wobei $uptodate angibt, ob alle Msgid der aktuellen Po-Datei auch in der als Parameter übergebenen vorhanden sind (alle anderen Felder werden im Dateivergleich ignoriert). Informell bedeutet dies, falls $uptodate »false« zurückliefert, dass die Po-Datei durch po4a-updatepo geändert würde.

Falls $uptodate »false« ist, dann enthält $diagnostic eine Diagnose, warum dies der Fall ist.

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)