Provided by: po4a_0.55-1_all bug

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[,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:

           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.

       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)