Provided by: po4a_0.73-2ubuntu1_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 ;)
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
ignoriert; dieser Schlüssel wird für ältere Berechnung beibehalten.
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.
AUTOREN
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
perl v5.38.2 2024-08-28 LOCALE::PO4A::PO.3PM(1)