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:

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.

  * In B<break> aufgeführte Markierungen werden abhängig von der Option <wrap> auf I<w> oder I<W> gesetzt.
  * In B<inline> aufgeführte Markierungen werden auf I<i> gesetzt.
  * In B<placeholder> aufgeführte Markierungen werden auf I<p> gesetzt.
  * In B<untranslated> aufgeführte Markierungen haben keine dieser Optionen gesetzt.

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¶

  $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;

  sub found_string {
    my ($self,$text,$ref,$options)=@_;
    $text = $self->translate($text,$ref,"type ".$options->{'type'},
      'wrap'=>$self->{options}{'wrap'});
    return $text;
  }

INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden¶

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 (siehe die Datei COPYING) vertreiben und/oder verändern.