Provided by: po4a_0.47-2_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
Canonicalizes the string to translate, considering that whitespaces are not important,
and wraps the translated document. This option can be overridden by custom tag
options. See the "tags" option below.
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.
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
This option defines the behavior of the module when it encounters invalid XML syntax
(a closing tag which does not match the last opening tag, or a tag's attribute without
value). It can take the following values:
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
extrahiert nur die angegebenen Markierungen in der Option »tags«. Andernfalls wird es
nur die Markierungen extrahieren mit Ausnahme derjenigen, die angegeben wurden.
Hinweis: Diese Option wurde missbilligt.
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.
tags
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>
Hinweis: Diese Option wurde missbilligt. Sie sollten stattdessen die Optionen
translated und untranslated verwenden.
attributes
Space-separated list of tag's attributes you want to translate. You can specify the
attributes by their name (for example, "lang"), but you can prefix it with a tag
hierarchy, to specify that this attribute will only be translated when it's in the
specified tag. For example: <bbb><aaa>lang specifies that the lang attribute will only
be translated if it's in an <aaa> tag, and it's in a <bbb> tag.
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
inline
leerzeichengetrennte Liste der Markierungen, die als innenliegend betrachtet werden
sollen. Standardmäßig unterbrechen alle Markierungen die Abfolge.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<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\"/>
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
nodefault
leerzeichengetrennte Liste der Markierungen, die das Modul nicht standardmäßig in
jeder Kategorie zu setzen versuchen sollte.
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
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
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>
untranslated
leerzeichengetrennte Liste der Markierungen, die Sie nicht übersetzen möchten
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag
(<aaa>) should only be considered when it's within another tag (<bbb>).
defaulttranslateoption
die Standardkategorie für Markierungen, die sich nicht in »translated«,
»untranslated«, »break«, »inline« oder »placeholder« befinden
Dies ist eine Zusammenstellung von Buchstaben:
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
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.
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)
This is a more complex one, but it enables a (almost) total customization. It's based on a
list of hashes, each one defining a tag type's behavior. The list should be sorted so that
the most general tags are after the most concrete ones (sorted first by the beginning and
then by the end keys). To define a tag type you'll have to make a hash with the following
keys:
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.
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.
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.
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.
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.
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 (c) 2004 by Jordi Vilalta <jvprat@gmail.com>
Copyright (c) 2008-2009 by Nicolas François <nicolas.francois@centraliens.net>
Dieses Programm ist freie Software; Sie können es unter den Bedingungen der GPL (siehe die
Datei COPYING) vertreiben und/oder verändern.