NAME¶
Locale::Po4a::TransTractor - generischer Übersetzungs-Ausleser
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.
Diese Klasse ist Vorfahr jedes Po4a-Parsers. Sie wird zum Auswerten eines
Dokuments, zur Suche nach übersetzbaren Zeichenketten, zum Auslesen in
eine PO-Datei und zur Ersetzung durch ihre Übersetzung im
Ausgabedokument, verwandt.
Oder formaler, sie erwartet die folgenden Argumente als Eingabe:
- -
- ein zu übersetzendes Dokument
- -
- eine PO-Datei, die die zu verwendende Übersetzung
enthält.
Als Ausgabe produziert sie:
- -
- eine weitere PO-Datei, die aus der Auslösung der
übersetzbaren Zeichenketten aus dem Eingabedokument entsteht
- -
- ein übersetztes Dokument mit der gleichen Struktur wie
das der Eingabe, bei der aber alle übersetzbaren Zeichenketten mit
den in der als Eingabe bereitgestellten PO-Datei gefundenen
Übersetzungen ersetzt wurden.
Dies ist eine graphische Darstellung davon:
Eingabedokument --\ /---> Ausgabedokument
\ / (übersetzt)
+-> parse()-Funktion -----+
/ \
Eingabe-PO -------/ \---> Ausgabe-PO
(herausgelöst)
FUNCTIONEN, DIE IHR PARSER ÜBERSCHREIBEN SOLLTE¶
- parse()
- Hier findet die gesamte Arbeit statt: das Auswerten der
Eingabedokumente, die Erstellung der Ausgabe und das Herauslösen der
übersetzbaren Zeichenketten. Das ist mit den in Abschnitt INTERNE
FUNKTIONEN weiter unten vorgestellten angebotenen Funktionen recht
einfach. Lesen Sie auch die ÜBERSICHT, in der ein Beispiel
vorgestellt wird.
Diese Funktion wird von der unten beschriebenen process()-Funktion
aufgerufen. Falls Sie sich aber entscheiden, die new()-Funktion zu
verwenden und den Inhalt manuell zu Ihrem Dokument hinzuzufügen,
müssen Sie diese Funktion selbst aufrufen.
- docheader()
- Diese Funktion gibt den Header zurück und sollte dem
erzeugten Dokument hinzugefügt werden, ordentlich zitiert, so dass
sie in der Zielsprache ein Kommentar wird. Lesen Sie den Abschnitt
Entwickler über Übersetzungen schulen, von
po4a(7), um zu erfahren, wozu dies benutzt wird.
ÜBERSICHT¶
Das folgende Beispiel wertet eine Liste von Absätzen aus, die mit
»<p>» beginnen. Der Einfachheit halber wird angenommen, dass
das Dokument gut formatiert ist, d.h. dass »<p>«-Markierungen
die einzigen vorhandene Markierungen sind und dass diese Markierung ganz am
Anfang jedes Absatzes steht.
sub parse {
my $self = shift;
PARAGRAPH: while (1) {
my ($paragraph,$pararef)=("","");
my $first=1;
my ($line,$lref)=$self->shiftline();
while (defined($line)) {
if ($line =~ m/<p>/ && !$first--; ) {
# <p>taucht nicht zum ersten Mal auf.
# Fügen Sie die aktuelle Zeile erneut in die Eingabe,
# und fügen Sie den erstellten Absatz in die Ausgabe.
$self->unshiftline($line,$lref);
# Nun ist das Dokument ausgestaltet, es wird übersetzt:
# - Die führende Markierung entfernen
$paragraph =~ s/^<p>//s;
# - die Ausgabe der führenden Markierung (unübersetzt) und des
# Rests des Absatzes (unübersetzt) anstoßen
$self->pushline( "<p>"
. $document->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# an den Absatz anhängen
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Die Schleife neu initialisieren
($line,$lref)=$self->shiftline();
}
# Keine definierte Zeile erhalten? Ende der Eingabedatei
return;
}
}
Sobald Sie die Funktion zum Auswerten implementiert haben, können Sie Ihre
Dokumentenklasse verwenden, die die öffentliche Schnittstelle benutzt,
die im nächsten Abschnitt vorgestellt wird.
ÖFFENTLICHE SCHNITTSTELLE für Skripte, die Ihren Parser
benutzen¶
Konstruktor¶
- process(%)
- Diese Funktion kann alles tun, was Sie mit einem
Po4a-Dokument in einem Aufruf tun müssen. Ihre Argumente müssen
als ein Hash gepackt sein. AKTIONEN:
- a.
- liest alle PO-Dateien, die in po_in_name angegeben
sind
- b.
- liest alle Originaldokumente, die in file_in_name angegeben
sind
- c.
- wertet das Dokument aus
- d.
- liest alle angegebenen Addenda und wendet sie an
- e.
- schreibt das übersetzte Dokument in file_out_name
(falls angegeben)
- f.
- schreibt die extrahierte PO-Datei nach po_out_name (falls
angegeben)
ARGUMENTE jenseits der durch
new() akzeptierten (mit erwartetem Typ):
- file_in_name (@)
- Liste der Dateinamen, bei denen das Eingabedokument gelesen
werden sollte
- file_in_charset ($)
- im Eingabedokument benutzter Zeichensatz (falls er nicht
angegeben wurde, wird versucht, ihn aus dem Eingabedokument zu
bestimmen).
- file_out_name ($)
- Name der Datei, in den das Ausgabedokument geschrieben
werden soll
- file_out_charset ($)
- im Ausgabedokument benutzter Zeichensatz (falls er nicht
angegeben wurde, wird der der PO-Datei benutzt).
- po_in_name (@)
- Liste der Dateinamen, von denen die Eingabe-PO-Dateien
gelesen werden sollen; enthält die Übersetzung, die benutzt
wird, um das Dokument zu übersetzen
- po_out_name ($)
- Name der Datei, in den die Ausgabe-PO-Datei geschrieben
werden soll; enthält die aus dem Eingabedokument extrahierten
Zeichenketten.
- addendum (@)
- Liste der Dateinamen, aus denen die Addenda gelesen
werden
- addendum_charset ($)
- Zeichensatz für die Addenda
- new(%)
- erstellt ein neues Po4a-Dokument; akzeptiert Optionen (aber
nur in Form eines Hashs):
- verbose ($)
- setzt die Detailstufe
- debug ($)
- setzt die Debugging-Stufe
Manipulieren von Dokumentdateien¶
- read($)
- fügt am Ende des existierenden Eingabedokuments ein
weiteres ein. Das Argument ist der zu lesende Dateiname.
Bitte beachten Sie, dass es nichts auswertet. Sie sollten die Funktion
parse() benutzen, wenn Sie damit fertig sind, Eingabedateien in das
Dokument zu packen.
- write($)
- schreibt das übersetzte Dokument in den angegebene
Dateinamen
PO-Dateien manipulieren¶
- readpo($)
- fügt den Inhalt einer Datei (deren Name als Argument
übergeben wird) der existierenden Eingabe-PO-Datei hinzu. Der alte
Inhalt wird nicht verworfen.
- writepo($)
- schreibt die extrahierte PO-Datei in den angegebene
Dateinamen
- stats()
- gibt einige Statistiken über bisher erledigte
Übersetzungen zurück. Bitte beachten Sie, dass es sich nicht um
die gleichen Statistiken handelt, die »msgfmt --statistics«
ausgibt. Hier geht es um den aktuellen Gebrauch der PO-Datei, während
Msgfmt den Status der Datei ausgibt. Es ist ein Wrapper für die
Funktion Locale::Po4a::Po::stats_get, die auf die Eingabe-PO-Datei
angewandt wird. Beispiel für die Benutzung:
[normale Benutzung des Po4a-Dokuments …]
($percent,$hit,$queries) = $document->stats();
print "Es wurden Übersetzungen für $percent\% ($hit von $queries) der Zeichenketten gefunden.\n";
Addenda manipulieren¶
- addendum($)
- Weitere Informationen, was Addenda sind und wie
Übersetzer sie schreiben sollten, finden Sie unter po4a(7). Um
ein Addendum auf ein übersetztes Dokument anzuwenden, übergeben
Sie einfach dieser Funktion seinen Dateinamen und Sie sind fertig. ;)
Diese Funktion gibt bei einem Fehler eine Ganzzahl ungleich Null
zurück.
INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser
verwendet werden¶
Eingaben erhalten, Ausgaben bereitstellen¶
Um Eingaben zu erhalten und Ausgaben bereitzustellen, stehen vier Funktionen zur
Verfügung. Sie sind Shift/Unshift und Push/Pop sehr ähnlich. Das
erste Paar handelt von der Eingabe, während das Zweite von der Ausgabe
handelt. Merkhilfe: In der Eingabe sind Sie an der ersten Zeile interessiert,
was Shift ausgibt und in der Ausgabe möchten Sie Ihr Ergebnis an das Ende
hinzufügen, wie dies Push tut.
- shiftline()
- Diese Funktion gibt die nächste Zeile von doc_in zur
Auswertung und ihre Referenz zurück (als ein Feld gepackt).
- unshiftline($$)
- stellt eine Zeile des Eingabedokuments und seiner Referenz
wieder her
- pushline($)
- schiebt eine neue Zeile in doc_out ein.
- popline()
- holt die zuletzt verschobene Zeile aus doc_out hervor.
Zeichenketten als übersetzbar markieren¶
Eine Funktion wird bereitgestellt, um den Text zu handhaben, der übersetzt
werden soll.
- translate($$$)
- vorgeschriebene Argumente:
- -
- eine zu übersetzende Zeichenkette
- -
- die Referenz dieser Zeichenkette (d.h. Position in der
Eingabedatei)
- -
- der Typ der Zeichenkette (d.h. die inhaltliche Beschreibung
ihrer strukturellen Rolle; benutzt in
Locale::Po4a::Po::gettextization(); siehe auch po4a(7),
Abschnitt Gettextisierung: Wie funktioniert das?)
Diese Funktion kann außerdem einige zusätzliche Argumente
entgegennehmen. Sie müssen als Hash organisiert sein. Zum Beispiel:
$self->translate("string","ref","type",
'wrap' => 1);
- wrap
- logische Variable, ob die Leerzeichen in der Zeichenkette
als unwichtig betrachtet werden können. Falls ja, wird die Funktion
die Zeichenkette in eine kanonische Form bringen, bevor nach einer
Übersetzungen gesucht oder diese extrahiert wird und ein
Zeilenumbruch wird durchgeführt.
- wrapcol
- die Spalte, an der umgebrochen werden soll
(standardmäßig 76)
- comment
- ein zusätzlicher Kommentar, der zum Eintrag
hinzugefügt wird
Aktionen:
- -
- schiebt die Zeichenkette, die Referenz und den Typ nach
po_out
- -
- gibt die Übersetzung der Zeichenkette (wie sie in
po_in gefunden wurde) zurück, so dass der Parser das doc_out bauen
kann
- -
- handhabt die Zeichensätze, um den Zeichensatz der
Zeichenkette umzuwandeln, bevor sie an po_out gesandt werden und bevor die
Übersetzungen zurückgegeben werden
Verschiedene Funktionen¶
- verbose()
- kehrt zurück, falls die Option »verbose«
während der Erstellung von TransTractor übergeben wurde
- debug()
- kehrt zurück, falls die Option »debug«
während der Erstellung von TransTractor übergeben wurde
- detected_charset($)
- Dies teilt TransTractor mit, dass ein neuer Zeichensatz
(das erste Argument) vom Eingabedokument festgestellt wurde. Er kann
üblicherweise aus den Kopfzeilen des Dokuments gelesen werden. Nur
der erste Zeichensatz, der entweder von dem process()-Argumenten
kommt oder aus dem Dokumente ermittelt wird, wird übrigbleiben.
- get_out_charset()
- Diese Funktion wird den Zeichensatz zurückgeben, der
im ausgegebenen Dokument benutzt werden sollte (üblicherweise
nützlich, um den ermittelten Zeichensatz des Eingabedokuments zu
ersetzen, wo er gefunden wurde).
Sie wird den auf der Befehlszeile angegebenen Zeichensatz verwenden. Falls
er nicht angegeben wurde, wird sie den Zeichensatz der Eingabe-PO-Datei
benutzen und falls die Eingabe-PO-Datei die Vorgabe »CHARSET«
hat, wird sie den Zeichensatz des Eingabedokuments zurückgeben, so
dass die Kodierung durchgeführt wird.
- recode_skipped_text($)
- Diese Funktion gibt den vom Zeichensatz des
Eingabedokuments in den Zeichensatz des Ausgabedokuments neu kodierten
Text zurück, der als Argument übergeben wurde. Dies ist nicht
nötig, wenn eine Zeichenkette übersetzt wird (
translate() kodiert selbst alles neu), aber es ist nötig, wenn
Sie eine Zeichenkette des Eingabedokuments überspringen und wenn Sie
wollen, dass das Ausgabedokument über eine einheitliche globale
Kodierung verfügt.
ZUKÜNFTIGE ENTWICKLUNGEN¶
Ein Mangel des aktuellen Transtractors ist, dass er keine übersetzten
Dokumente handhaben kann, die alle Sprachen enthalten, wie Debconf-Schablonen
oder Desktop-Dateien.
Um dieses Problem anzugehen, sind nur bestimmte Schnittstellenänderungen
notwendig:
- -
- einen Hash in po_in_name nehmen (eine Liste pro
Sprache)
- -
- ein zu übersetzendes Argument hinzufügen, um die
Zielsprache anzugeben
- -
- ein Funktion pushline_all erstellen, die pushline ihres
Inhalts für alle Sprachen unter Benutzung einer kartenähnlichen
Syntax ausführen würde:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Es wird sich zeigen, ob das ausreicht. ;)
AUTOREN¶
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>