Provided by: po4a_0.69-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
           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)