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 »tags« weiter unten.
- 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
- 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
oder ein Attribut einer Markierung ohne Wert). 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
- 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
einige 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
- 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>).
- 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>).
- 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
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. 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
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>).
- 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)¶
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.
- 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.