| Locale::Po4a::TransTractor(3pm) | Po4a-Werkzeuge | Locale::Po4a::TransTractor(3pm) |
Locale::Po4a::TransTractor - generischer Übersetzungs-Ausleser
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:
Als Ausgabe produziert sie:
Dies ist eine graphische Darstellung davon:
Eingabedokument --\ /---> Ausgabedokument
\ / (übersetzt)
+-> parse()-Funktion -----+
/ \
Eingabe-PO -------/ \---> Ausgabe-PO
(herausgelöst)
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.
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>"
. $self->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.
ARGUMENTE jenseits der durch new() akzeptierten (mit erwartetem Typ):
Das Feld
"@{$self->{TT}{doc_in}}"
hält die Eingabedokumentdaten als ein Feld von Zeichenketten mit
abwechselnden Bedeutungen.
* Die Zeichenkette $textline hält jede
Zeile der Eingabetextdaten.
* Die Zeichenkette "$filename:$linenum"
hält ihren Ort und wird
»reference« genannt
("linenum" beginnt mit 1).
Bitte beachten Sie, dass es nichts auswertet. Sie sollten die Funktion parse() benutzen, wenn Sie damit fertig sind, Eingabedateien in das Dokument zu packen.
Diese übersetzten Dokumentdaten werden bereitgestellt
durch:
* "$self->docheader()" hält
den Kopftext für die Erweiterung und
* "@{$self->{TT}{doc_out}}"
hält jede Zeile des übersetzten Haupttextes in dem
Feld.
[normale Benutzung des Po4a-Dokuments …]
($percent,$hit,$queries) = $document->stats();
print "Es wurden Übersetzungen für $percent\% ($hit von $queries) der Zeichenketten gefunden.\n";
Diese Funktion gibt bei einem Fehler eine Ganzzahl ungleich Null zurück.
Es werden vier Funktionen bereitgestellt, um Eingaben zu erhalten und Ausgaben zurückzuliefern. Sie sind den Funktionen shift/unshift und push/pop von Perl sehr ähnlich.
* Perl shift liefert den ersten Feldeintrag zurück und entfernt ihn aus dem Feld. * Perl unshift hängt einen Eintrag als ersten Feldeintrag vor das Feld. * Perl pop liefert den letzten Feldeintrag zurück und entfernt ihn aus dem Feld. * Perl push hängt einen Eintrag als letzten Feldeintrag an das Feld an.
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.
Eine Funktion wird bereitgestellt, um den Text zu handhaben, der übersetzt werden soll.
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);
Aktionen:
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.
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:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Es wird sich zeigen, ob das ausreicht. ;)
Denis Barbier <barbier@linuxfr.org> Martin Quinson (mquinson#debian.org) Jordi Vilalta <jvprat@gmail.com>
| 2023-01-03 | Po4a-Werkzeuge |