Provided by: po4a_0.73-2ubuntu1_all 
NAME
Locale::Po4a::Xml - konvertiert XML-Dokumente und -Derivate von/in PO-Dateien
BESCHREIBUNG
Das Projektziel von Po4a (PO für alles) ist es, die Übersetzung (und interessanter, die Wartung der
Übersetzung) zu vereinfachen, indem die Gettext-Werkzeuge auch für Gebiete verwendet werden, wo diese
nicht erwartet werden, wie Dokumentation.
Locale::Po4a::Xml ist ein Modul, um bei der Übersetzung von XML-Dokumenten in andere [natürliche]
Sprachen zu helfen. Es kann auch als Basis verwandt werden, um Module für XML-basierte Dokumente zu
erstellen.
ÜBERSETZEN MIT PO4A::XML
Dieses Modul kann direkt zum Umgang mit generischen XML-Dokumenten verwandt werden. Dabei werden die
Inhalte aller Markierungen (»Tags«) aber keiner Attribute ausgelesen, da sich dort in den meisten XML-
basierten Dokumenten der geschriebene Text befindet.
Es gibt einige Optionen (die im nächsten Abschnitt beschrieben werden), die dieses Verhalten anpassen
lassen. Falls dies nicht auf Ihr Dokumentenformat passt, ermutigen wir Sie, Ihr eigenes, von diesem Modul
abgeleitetes Modul zu schreiben, um die Details Ihres Formats zu beschreiben. Lesen Sie den Abschnitt
SCHREIBEN ABGELEITETER MODULE weiter unten für die Beschreibung des Prozesses.
VON DIESEM MODUL AKZEPTIERTE OPTIONEN
Die globale Option »debug« führt dazu, dass das Module ausgeschlossene Zeichenketten anzeigt, um zu
erkennen, ob etwas Wichtiges übersprungen wird.
Dies sind die Modul-spezifischen Optionen:
nostrip
verhindert, dass es Leerzeichen um herausgelöste Zeichenketten entfernt
wrap
Erstellt eine kanonische Form der zu übersetzenden Zeichenketten, berücksichtigt dabei, dass
Leerzeichen nicht wichtig sind, und bricht das übersetzte Dokument um. Diese Option kann mit
angepassten »tag«-Optionen überschrieben werden. Lesen Sie dazu über die Option translated weiter
unten.
unwrap_attributes
Attribute werden standardmäßig zeilenumgebrochen. Diese Option unterbindet Zeilenumbrüche.
caseinsensitive
Damit funktioniert die Suche nach Markierungen und Attributen unabhängig von der
Groß-/Kleinschreibung. Falls es definiert ist, wird es <BooK>laNG und <BOOK>Lang als <book>lang
behandeln.
escapequotes
Maskiert Anführungszeichen in Ausgabezeichenketten. Dies ist zum Beispiel für die Erstellung von
Zeichenkettenressourcen zur Verwendung mit den Android-Bauwerkzeugen notwendig.
Siehe auche: https://developer.android.com/guide/topics/resources/string-resource.html
includeexternal
Wenn definiert, werden externe Entitäten in das erstellte (übersetzte) Dokument und für die
Herauslösung der Zeichenketten aufgenommen. Falls es nicht definiert ist, müssen Sie externe
Entitäten separat als unabhängige Dokumente übersetzen.
ontagerror
Diese Option defniert das Verhalten des Moduls, wenn es auf eine ungültige XML-Syntax trifft (eine
schließende Markierung (»Tag«), die nicht zur letzten öffnenden Markierung passt). Sie kann die
folgenden Werte annehmen:
fail
Dies ist der Standardwert. Das Modul wird sich mit einem Fehler beenden.
warn
Das Modul wird fortfahren und eine Warnung ausgeben.
silent
Das Modul wird ohne Warnungen fortfahren.
Seien Sie vorsichtig, wenn Sie diese Option verwenden. Im Allgemeinen wird empfohlen, die
Eingabedatei zu reparieren.
tagsonly
Hinweis: Diese Option wurde missbilligt.
extrahiert nur die angegebenen Markierungen in der Option tags. Andernfalls wird es nur die
Markierungen extrahieren mit Ausnahme derjenigen, die angegeben wurden.
doctype
Zeichenkette, bei der ausprobiert wird, ob sie zu der ersten Zeile des Dokumenttyps passt (falls
definiert). Falls nicht, wird eine Warnung angezeigt, dass das Dokument vom falschen Typ ist.
addlang
Zeichenkette, die den Pfad einer Markierung (z.B. <bbb><aaa>) angibt, zu dem ein Attribut lang="…"
hinzugefügt werden soll. Die Sprache wird als Basisname der PO-Datei ohne irgendeine .po-Erweiterung
definiert sein.
optionalclosingtag
Logischer Wert, der angibt, ob schließende Markierungen optional sind (wie in HTML). Standardmäßig
lösen fehlende schließende Markierungen einen Fehler aus, der entsprechend ontagerror behandelt wird.
tags
Hinweis: Diese Option wurde missbilligt. Sie sollten stattdessen die Optionen translated und
untranslated verwenden.
leerzeichengetrennte Liste der Markierungen, die Sie übersetzen oder überspringen möchten.
Standardmäßig werden die angegebenen Markierungen ausgenommen, falls Sie aber die Option »tagsonly«
verwenden, werden nur die angegebenen Markierungen einbezogen. Die Markierungen müssen die Form <aaa>
haben, Sie können aber einige verbinden (<bbb><aaa>), um anzugeben, dass der Inhalt der Markierung
<aaa> nur übersetzt wird, wenn er in einer <bbb>-Markierung liegt.
Sie können außerdem einige Markierungsoptionen angeben, indem Sie ein paar Zeichen an den Anfang der
Markierungshierarchie stellen. Sie können zum Beispiel w (Zeilenumbruch) oder W (kein Zeilenumbruch)
setzen, um das Standardverhalten, das durch die globale Option wrap angegeben wurde, außer Kraft zu
setzen.
Beispiel: W<Kapitel><Titel>
attributes
leerzeichengetrennte Liste der Markierungsattribute, die Sie übersetzen wollen. Sie können die
Attribute mittels ihres Namens angeben (zum Beispiel »lang«), aber Sie können ihnen eine Markierung
voranstellen, um anzugeben, dass das Attribut nur übersetzt wird, wenn es sich in der angegebenen
Markierung befindet. Zum Beispiel: <bbb><aaa>lang gibt an, dass das Attribut lang nur übersetzt wird,
falls es in einer <aaa> und einer <aaa>-Markierung steht.
foldattributes
Attribute in innenliegenden Markierungen nicht übersetzen; stattdessen alle Attribute einer
Markierung durch po4a-id=<Kennzahl> ersetzen
Dies ist nützlich, wenn Attribute nicht übersetzt werden sollen, da dies die Zeichenketten für
Übersetzer vereinfacht und Tippfehler vermeidet.
customtag
leerzeichengetrennte Liste der Markierungen, die nicht als Markierungen betrachtet werden. Diese
Markierungen werden als innenliegend angesehen und müssen nicht geschlossen werden.
break
leerzeichengetrennte Liste der Markierungen, die die Abfolge unterbrechen sollen. Standardmäßig
unterbrechen alle Markierungen die Abfolge.
Die Markierungen müssen in der Form <aaa> vorliegen, Sie können aber einige verbinden (<bbb><aaa>),
falls eine Markierung nur berücksichtigt werden soll, wenn sie innerhalb einer anderen Markierung
liegt (<bbb>).
Bitte beachten Sie, dass eine Markierung nur in einer der Einstellungszeichenketten break, inline
placeholder oder customtag aufgeführt sein soll.
inline
leerzeichengetrennte Liste der Markierungen, die als innenliegend betrachtet werden sollen.
Standardmäßig unterbrechen alle Markierungen die Abfolge.
Die Markierungen müssen in der Form <aaa> vorliegen, Sie können aber einige verbinden (<bbb><aaa>),
falls eine Markierung nur berücksichtigt werden soll, wenn sie innerhalb einer anderen Markierung
liegt (<bbb>).
placeholder
leerzeichengetrennte Liste der Markierungen, die als Platzhalter betrachtet werden sollen.
Platzhalter unterbrechen die Abfolge nicht, der Inhalt der Platzhalter wird aber separat übersetzt.
Die Lage des Platzhalters in seinem Block wird mit einer Zeichenkette ähnlich der Folgenden markiert:
<placeholder type=\"footnote\" id=\"0\"/>
Die Markierungen müssen in der Form <aaa> vorliegen, Sie können aber einige verbinden (<bbb><aaa>),
falls eine Markierung nur berücksichtigt werden soll, wenn sie innerhalb einer anderen Markierung
liegt (<bbb>).
break-pi
Standardmäßig werden Verarbeitungsanweisungen (d.h. "<? … ?>"-Markierungen) als innenliegende
Markierungen behandelt. Übergeben Sie diese Option, wenn Sie möchten, dass die Verarbeitungshinweise
als unterbrechende Markierungen behandelt werden sollen. Beachten Sie, dass unkomprimierte PHP-
Markierungen durch das Auswertprogramm als Verarbeitungsanweisungen gehandhabt werden.
nodefault
leerzeichengetrennte Liste der Markierungen, die das Modul nicht standardmäßig in jeder Kategorie zu
setzen versuchen sollte.
Falls Sie eine Markierung einsetzen, deren Vorgabeeinstellung in einer Unterklasse dieses Moduls ist,
Sie aber eine alternative Einstellung wählen möchten, müssen Sie diese Markierung als Teil der
Einstellungszeichenkette nodefault aufführen.
cpp C-Präprozessordirektiven unterstützen. Wenn diese Option gesetzt ist, wird Po4a
Präprozessordirektiven als Absatztrenner betrachten. Dies ist wichtig, falls die XML-Datei vorher
bearbeitet werden muss, weil die Direktiven andernfalls in die Mitte der Zeilen eingefügt werden
könnten, falls Po4a sie zum aktuellen Absatz gehörig ansieht und sie nicht durch den Präprozessor
erkannt würden. Hinweis: Die Präprozessordirektiven dürfen nur zwischen Markierungen erscheinen (sie
dürfen keine Markierung unterbrechen).
translated
leerzeichengetrennte Liste der Markierungen, die Sie übersetzen möchten
Die Markierungen müssen in der Form <aaa> vorliegen, Sie können aber einige verbinden (<bbb><aaa>),
falls eine Markierung nur berücksichtigt werden soll, wenn sie innerhalb einer anderen Markierung
liegt (<bbb>).
Sie können außerdem einige Markierungsoptionen angeben, indem Sie ein paar Zeichen an den Anfang der
Markierungshierarchie stellen. Dies setzt das durch die globalen Optionen wrap und
defaulttranslateoption festgelegte Vorgabeverhalten außer Kraft.
w Markierungen sollten übersetzt werden und Inhalt kann neu umgebrochen werden
W Markierungen sollten übersetzt werden und Inhalt sollte nicht neu umgebrochen werden
i Markierungen sollten innenliegend übersetzt werden
p Markierungen sollten als Platzhalter übersetzt werden
Intern kümmert sich der XML-Parser nur um diese vier Optionen: w W i p.
* In break aufgeführte Markierungen werden abhängig von der Option wrap auf w oder W gesetzt.
* In inline aufgeführte Markierungen werden auf i gesetzt.
* In placeholder aufgeführte Markierungen werden auf p gesetzt.
* In untranslated aufgeführte Markierungen sind ohne eine dieser gesetzten Optionen.
Das tatsächliche interne Parameterverhalten können Sie durch Aufruf von po4a mit der Option --debug
überprüfen.
Beispiel: W<Kapitel><Titel>
Bitte beachten Sie, dass eine Markeirung entweder in der Einstellungszeichenkette translated oder
untranslated aufgeführt sein sollte.
untranslated
leerzeichengetrennte Liste der Markierungen, die Sie nicht übersetzen möchten
Die Markierungen müssen in der Form <aaa> vorliegen, Sie können aber einige verbinden (<bbb><aaa>),
falls eine Markierung nur berücksichtigt werden soll, wenn sie innerhalb einer anderen Markierung
liegt (<bbb>).
Bitte beachten Sie, dass eine übersetzbare innenliegende Markierung in einer unübersetzbaren
Markierung als eine übersetzbare unterbrechende Markierung behandelt wird, die Einstellung i entfällt
und w oder W werden abhängig von der Option wrap gesetzt.
defaulttranslateoption
die Standardkategorie für Markierungen, die sich nicht in »translated«, »untranslated«, »break«,
»inline« oder »placeholder« befinden
Dies ist eine Gruppe von in translated definierten Buchstaben und diese Einstellung ist nur für
übersetzbare Markierungen gültig.
SCHREIBEN ABGELEITETER MODULE
DEFINIERT, WELCHE MARKIERUNGEN UND ATTRIBUTE ZU ÜBERSETZEN SIND
Die einfachste Anpassung ist, zu definieren, welche Markierungen und Attribute der Parser übersetzen
soll. Dies sollte in der Funktion »initialize« erledigt werden. Zuerst sollten Sie die
Haupt-»initialize«-Funktion aufrufen, um die Befehlszeilenoptionen zu erhalten und dann Ihre angepassten
Definitionen an den Options-Hash anhängen. Falls Sie einige neue Optionen von der Befehlszeile bearbeiten
möchten, sollten Sie sie vor dem Aufruf der Haupt-»initialize«-Funktion definieren:
$self->{options}{'new_option'}='';
$self->SUPER::initialize(%options);
$self->{options}{'_default_translated'}.=' <p> <head><title>';
$self->{options}{'attributes'}.=' <p>lang id';
$self->{options}{'_default_inline'}.=' <br>';
$self->treat_options;
Sie sollten in abgeleiteten Modulen die Optionen _default_inline, _default_break, _default_placeholder,
_default_translated, _default_untranslated und _default_attributes benutzen. Dies ermöglicht Anwendern,
das in Ihrem Modul definierte Verhalten mit Befehlszeilenoptionen außer Kraft zu setzen.
AUSSERKRAFTSETZEN DES VORGABEVERHALTENS MIT BEFEHLSZEILENOPTIONEN
Falls Sie das Vorgabeverhalten dieses XML-Moduls und seiner abgeleiteten Module nicht mögen, können Sie
Befehlszeilenoptionen zur Änderung ihres Verhaltens bereitstellen.
Siehe Locale::Po4a::Docbook(3pm),
DIE FUNKTION found_string AUßER KRAFT SETZEN
Ein weiterer einfacher Schritt ist es, die Funktion »found_string« außer Kraft zu setzen, die die
extrahierten Zeichenketten vom Parser erhält, um sie zu übersetzen. Dort können Sie steuern, welche
Zeichenketten Sie übersetzen möchten und Umwandlungen in diese vor oder nach der Übersetzung selbst
durchführen.
Sie erhält den extrahierten Text, die Referenz, von wo sie stammt und einen Hash, der zusätzliche
Informationen enthält, um zu steuern, welche Zeichenketten zu übersetzen sind, wie sie zu übersetzen sind
und um den Kommentar zu erzeugen.
Der Inhalt dieser Optionen hängt von der Art der Zeichenkette ab (angegeben in einem Eintrag dieses
Hashs):
type="Markierung"
Die gefundene Zeichenkette ist der Inhalt einer übersetzbaren Markierung. Der Eintrag »tag_options«
enthält die Optionszeichen am Anfang der Markierungshierarchie in der Moduloption »tags«.
type="Attribut"
bedeutet, dass die gefundene Zeichenkette der Wert eines übersetzbaren Attributs ist. Der Eintrag
»Attribut« erhält den Namen des Attributs.
Sie muss den Text zurückgeben, der das Original im übersetzten Dokument ersetzt. Hier ein grundlegendes
Beispiel dieser Funktion:
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Im neuen Modul Dia ist ein weiteres einfaches Beispiel, das nur einige Zeichenketten filtert.
ÄNDERN VON KENNZEICHENTYPEN (ZU ERLEDIGEN)
Dies ist ein komplexeres Modul, das aber eine (fast) vollständige Anpassung ermöglicht. Es basiert auf
einer Liste von Hashes, von denen jeder das Verhalten eines Markierungstyps definiert. Die Liste sollte
sortiert sein, so dass die allgemeinsten Markierungen hinter den konkretesten stehen (zuerst nach den
beginnenden und dann nach den endenden Schlüsseln sortiert). Um eine Markierung zu definieren, müssen Sie
einen Hash mit den folgenden Schlüsseln erstellen:
beginning
gibt den Anfang der Markierung an, nach dem »<«
end gibt das Ende der Markierung an, vor dem »>«
breaking
teilt mit, ob dies eine unterbrechende Markierungsklasse ist. Eine nicht unterbrechende
(innenliegende) Markierung ist eine, die nicht als Teil des Inhalts einer anderen Markierung genommen
werden kann. Sie kann die Werte false (0), true (1) oder undefiniert annehmen. Falls Sie dies
undefiniert lassen, müssen Sie die Funktion f_breaking definieren, die aussagt, ob eine bestimmte
Markierung dieser Klasse eine unterbrechende Markierung ist oder nicht.
f_breaking
Es ist eine Funktion, die mitteilen wird, ob die nächste Markierung unterbrechend ist oder nicht. Sie
sollte definiert sein, wenn die Option breaking nicht definiert ist.
f_extract
Falls Sie diesen Schlüssel undefiniert lassen, muss die generische Extrahierfunktion die Markierung
selbst extrahieren. Das ist nützlich für Markierungen, die andere Markierungen oder besondere
Strukturen beinhalten können, so dass der Haupt-Parser nicht durchdreht. Diese Funktion bekommt einen
logischen Wert, der aussagt, ob die Markierung aus dem Eingabedatenstrom entfernt werden soll oder
nicht.
f_translate
Diese Funktion erhält die Markierung (im Format get_string_until()) und gibt die übersetzte
Markierung (übersetzte Attribute oder alle nötigen Umbildungen) als eine einzelne Zeichenkette
zurück.
INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden
ARBEITEN MIT KENNZEICHEN
get_path()
Diese Funktion gibt den Pfad zur aktuellen Markierung von der Wurzel des Dokuments in der Form
<html><body><p> zurück.
Ein zusätzliches Feld von Markierungen (ohne Klammern) kann als Argument übergeben werden. Diese
Pfadelemente werden am Ende des aktuellen Pfades hinzugefügt.
tag_type()
Diese Funktion gibt den Index der Liste tag_types zurück, die zur nächsten Markierung des
Eingabedatenstroms passt oder -1, falls es am Ende der Eingabedatei liegt.
Hier hat die Markierung eine Struktur, die mit < beginnt und > endet und mehrere Zeilen enthalten
kann.
Dies funktioniert auf dem Feld "@{$self->{TT}{doc_in}}", das Eingabedokumentdaten und indirekt
mittels "$self->shiftline()" und "$self->unshiftline($$)" Referenzen enthält.
extract_tag($$)
Diese Funktion gibt die nächste Markierung des Eingabedatenstroms ohne Anfang und Ende in Form eines
Feldes zurück, um die Referenzen der Eingabedatei zu verwalten. Sie hat zwei Parameter: den Typ der
Markierung (wie er von tag_type zurückgegeben wird) und einen logischen Wert, der angibt, ob die
Markierung aus dem Eingabedatenstrom entfernt werden soll.
Dies funktioniert auf dem Feld "@{$self->{TT}{doc_in}}", das Eingabedokumentdaten und indirekt
mittels "$self->shiftline()" und "$self->unshiftline($$)" Referenzen enthält.
get_tag_name(@)
Diese Funktion gibt den Namen der als Argument übergebenen Markierung in der Form eines durch
extract_tag zurückgegebenen Feldes zurück.
breaking_tag()
Diese Funktion gibt einen logischen Wert zurück, der angibt, ob die nächste Markierung im
Eingabedatenstrom eine unterbrechende Markierung ist oder nicht (innenliegende Markierung). Sie läßt
den Eingabedatenstrom intakt.
treat_tag()
Diese Funktion übersetzt die nächste Markierung des Eingabedatenstroms. Dabei benutzt sie die
angepassten Übersetzungsfunktionen jedes Markierungstyps.
Dies funktioniert auf dem Feld "@{$self->{TT}{doc_in}}", das Eingabedokumentdaten und indirekt
mittels "$self->shiftline()" und "$self->unshiftline($$)" Referenzen enthält.
tag_in_list($@)
Diese Funktion gibt eine Zeichenkette zurück, die angibt, ob das erste Argument (eine
Markierungshierarchie) zu einem der Markierungen des zweiten Arguments passt (eine Liste von
Markierungen oder Markierungshierarchien). Falls es nicht passt, gibt sie 0 zurück. Ansonsten gibt
sie die Optionen der passenden Markierung zurück (die Zeichen an Anfang der Markierung) oder 1 (falls
die Markierung keine Optionen hat).
MIT ATTRIBUTEN ARBEITEN
treat_attributes(@)
Diese Funktion handhabt die Übersetzung der Attribute von Markierungen. Sie erhält die Markierung
ohne die Anfangs-/Endmarkierungen, sucht dann die Attribute und übersetzt die, die übersetzbar sind
(angegeben durch die Moduloption attributes). Dies gibt eine einfache Zeichenkette mit der
übersetzten Markierung zurück.
ARBEITEN MIT MARKIERTEN INHALTEN
treat_content()
Diese Funktion erhält Text aus dem Eingabedatenstrom bis zur nächsten unterbrechenden Markierung
(nicht innenliegende). Übersetzen Sie ihn mittels der angepassten Übersetzungsfunktionen jedes
Markierungstyps.
Dies funktioniert auf dem Feld "@{$self->{TT}{doc_in}}", das Eingabedokumentdaten und indirekt
mittels "$self->shiftline()" und "$self->unshiftline($$)" Referenzen enthält.
MIT DEN MODULOPTIONEN ARBEITEN
treat_options()
Diese Funktion füllt die internen Strukturen, die die Markierung, Attribute und innenliegenden Daten
enthalten, mit den Optionen des Moduls (angegeben auf der Befehlszeile oder in der
Initialisierungsfunktion).
TEXT AUS DEM EINGABEDOKUMENT ERHALTEN
get_string_until($%)
Diese Funktion gibt ein Feld mit den Zeilen (und Referenzen) vom Eingabedokument zurück, bis es das
erste Argument findet. Das zweite Argument ist ein Options-Hash. Der Wert 0 bedeutet »deaktiviert«
(die Vorgabe) und 1 »aktiviert«.
Die gültigen Optionen sind:
include
Dies sorgt dafür, dass das zurückgegebene Feld den gesuchten Text erhält.
remove
Dies entfernt den zurückgegebenen Datenstrom aus der Eingabe.
unquoted
Dies stellt sicher, dass der gesuchte Text außerhalb irgendwelcher Anführungszeichen steht.
RegAus
Dies zeigt an, dass das erste Argument ein regulärer Ausdruck statt einer einfachen Zeichenkette
ist.
skip_spaces(\@)
Diese Funktion erhält als Argument die Referenz eines Absatzes (im Format, das von get_string_until
zurückgegeben wird), überspringt dessen führende Leerzeichen und gibt sie als einfache Zeichenkette
zurück.
join_lines(@)
Diese Funktion liefert eine einfache Zeichenkette mit dem Text aus dem Argument-Feld (die Referenzen
werden weggelassen).
STATUS DIESES MODULS
Dieses Modul kann Markierungen und Attribute übersetzen.
TODO-LISTE
DOKUMENTENART (ENTITÄTEN)
Es gibt dort eine minimale Unterstützung für die Übersetzung vom Instanzen. Sie werden als Ganzes
übersetzt und Markierungen werden nicht berücksichtigt. Mehrzeilige Entitäten werden nicht unterstützt
und Entitäten werden während der Übersetzung immer neu umgebrochen.
KENNZEICHENTYPEN VON GEERBTEN MODULEN (die Struktur tag_types innerhalb des Hashs $self verschieben?)
SIEHE AUCH
Locale::Po4a::TransTractor(3pm), po4a(7)
AUTOREN
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
URHEBERRECHT UND LIZENZ
Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL v2.0 oder neuer (siehe
die Datei COPYING) vertreiben und/oder verändern.
perl v5.38.2 2024-08-28 LOCALE::PO4A::XML.3PM(1)