>> beginnen. Der Einfachheit halber wird angenommen, dass das Dokument gut formatiert ist, d.h. dass >>
<<-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/
/ && !$first--; ) { #
taucht nicht zum ersten Mal auf. # Fugen Sie die aktuelle Zeile erneut in die Eingabe, # und fugen Sie den erstellten Absatz in die Ausgabe. $self->unshiftline($line,$lref); # Nun ist das Dokument ausgestaltet, es wird ubersetzt: # - Die fuhrende Markierung entfernen $paragraph =~ s/^
//s; # - die Ausgabe der fuhrenden Markierung (unubersetzt) und des # Rests des Absatzes (unubersetzt) anstossen $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# an den Absatz anhangen
$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, konnen Sie
Ihre Dokumentenklasse verwenden, die die offentliche Schnittstelle
benutzt, die im nachsten Abschnitt vorgestellt wird.
OFFENTLICHE SCHNITTSTELLE fur Skripte, die Ihren Parser benutzen
Konstruktor
process(%)
Diese Funktion kann alles tun, was Sie mit einem Po4a-Dokument in
einem Aufruf tun mussen. Ihre Argumente mussen 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 ubersetzte 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 UTF-8 benutzt).
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 UTF-8 benutzt).
po_in_name (@)
Liste der Dateinamen, von denen die Eingabe-PO-Dateien gelesen
werden sollen; enthalt die Ubersetzung, die benutzt wird, um
das Dokument zu ubersetzen
po_out_name ($)
Name der Datei, in den die Ausgabe-PO-Datei geschrieben werden
soll; enthalt die aus dem Eingabedokument extrahierten
Zeichenketten.
addendum (@)
Liste der Dateinamen, aus denen die Addenda gelesen werden
addendum_charset ($)
Zeichensatz fur die Addenda
new(%)
erstellt ein neues Po4a-Dokument; akzeptiert Optionen (in dem als
Parameter ubergebenen Hash):
verbose ($)
setzt die Detailstufe
debug ($)
setzt die Debugging-Stufe
wrapcol ($)
die Spalte, an der der Text im Ausgabedokument umgebrochen
werden soll (standardmassig 76)
Ein negativer Wert bedeutet, dass uberhaupt kein Umbruch
stattfindet.
Es akzeptiert auch die nachsten Optionen fur zugrundeliegende PO-
Dateien: porefs, copyright-holder, msgid-bugs-address, package-
name, package-version, wrap-po.
Manipulieren von Dokumentdateien
read($$$)
Fugt weitere Eingabedokumentendaten am Ende des bestehenden Felds
"@{$self->{TT}{doc_in}}" hinzu.
Diese Funktion akzeptiert zwei verpflichtende Argumente und ein
optionales.
* Der von Platte zu lesende Dateiname;
* Der Name, der fur den Bau von Referenzen in der PO-Datei
verwandt werden soll;
* Der Zeichensatz, der zum Lesen dieser Datei (standardmassig
UTF-8) verwendet werden soll
Das Feld "@{$self->{TT}{doc_in}}" halt die Eingabedokumentdaten als
ein Feld von Zeichenketten mit abwechselnden Bedeutungen.
* Die Zeichenkette $textline halt jede Zeile der Eingabetextdaten.
* Die Zeichenkette "$filename:$linenum" halt 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.
write($)
schreibt das ubersetzte Dokument in den angegebene Dateinamen
Diese ubersetzten Dokumentdaten werden bereitgestellt durch:
* "$self->docheader()" halt den Kopftext fur die Erweiterung und
* "@{$self->{TT}{doc_out}}" halt jede Zeile des ubersetzten
Haupttextes in dem Feld.
PO-Dateien bearbeiten
readpo($)
fugt den Inhalt einer Datei (deren Name als Argument ubergeben
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 uber bisher erledigte Ubersetzungen zuruck.
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, wahrend Msgfmt den Status der
Datei ausgibt. Es ist ein Wrapper fur die Funktion
Locale::Po4a::Po::stats_get, die auf die Eingabe-PO-Datei angewandt
wird. Beispiel fur die Benutzung:
[normale Benutzung des Po4a-Dokuments ]
($percent,$hit,$queries) = $document->stats();
print "Es wurden Ubersetzungen fur $percent\% ($hit von $queries) der Zeichenketten gefunden.\n";
Addenda manipulieren
addendum($)
Weitere Informationen, was Addenda sind und wie Ubersetzer sie
schreiben sollten, finden Sie unter po4a(7). Um ein Addendum auf
ein ubersetztes Dokument anzuwenden, ubergeben Sie einfach dieser
Funktion seinen Dateinamen und Sie sind fertig. ;)
Diese Funktion gibt bei einem Fehler eine Ganzzahl ungleich Null
zuruck.
INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden
Eingaben erhalten, Ausgaben bereitstellen
Es werden vier Funktionen bereitgestellt, um Eingaben zu erhalten und
Ausgaben zuruckzuliefern. Sie sind den Funktionen shift/unshift und
push/pop von Perl sehr ahnlich.
* Perl shift liefert den ersten Feldeintrag zuruck und entfernt ihn aus dem Feld.
* Perl unshift hangt einen Eintrag als ersten Feldeintrag vor das Feld.
* Perl pop liefert den letzten Feldeintrag zuruck und entfernt ihn aus dem Feld.
* Perl push hangt einen Eintrag als letzten Feldeintrag an das Feld an.
Das erste Paar handelt von der Eingabe, wahrend das Zweite von der
Ausgabe handelt. Merkhilfe: In der Eingabe sind Sie an der ersten Zeile
interessiert, was Shift ausgibt und in der Ausgabe mochten Sie Ihr
Ergebnis an das Ende hinzufugen, wie dies Push tut.
shiftline()
Diese Funktion liefert die erste auszuwertende Zeile und ihre
entsprechende Referenz (als Feld gepackt) aus dem Feld
"@{$self->{TT}{doc_in}}" zuruck und entfernt diese ersten zwei
Feldeintrage. Hier wird die Referenz durch eine Zeichenkette
"$filename:$linenum" bereitgestellt.
unshiftline($$)
Schiebt die letzte geschobene Zeile des Eingabedokuments und seiner
entsprechenden Referenz an den Kopf von "{$self->{TT}{doc_in}}"
zuruck.
pushline($)
Schiebt eine neue Zeile an das Ende von "{$self->{TT}{doc_out}}".
popline()
Holt die zuletzt geschobene Zeile vom Ende von
"{$self->{TT}{doc_out}}".
Zeichenketten als ubersetzbar markieren
Eine Funktion wird bereitgestellt, um den Text zu handhaben, der
ubersetzt werden soll.
translate($$$)
vorgeschriebene Argumente:
- eine zu ubersetzende 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 ausserdem einige zusatzliche Argumente
entgegennehmen. Sie mussen 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 konnen. Falls ja, wird die Funktion
die Zeichenkette in eine kanonische Form bringen, bevor nach
einer Ubersetzungen gesucht oder diese extrahiert wird und ein
Zeilenumbruch wird durchgefuhrt.
wrapcol
die Spalte an der umgebrochen werden soll (standardmassig der
Wert von wrapcol, der wahrend der Erstellung des TransTractor
festgelegt wurde oder 76).
Der negative Wert wird von der Vorgabe abgezogen.
comment
ein zusatzlicher Kommentar, der zum Eintrag hinzugefugt wird
Aktionen:
- schiebt die Zeichenkette, die Referenz und den Typ nach po_out
- gibt die Ubersetzung der Zeichenkette (wie sie in po_in gefunden
wurde) zuruck, so dass der Parser das doc_out bauen kann
- handhabt die Zeichensatze, um den Zeichensatz der Zeichenkette
umzuwandeln, bevor sie an po_out gesandt werden und bevor die
Ubersetzungen zuruckgegeben werden
Verschiedene Funktionen
verbose()
kehrt zuruck, falls die Option >>verbose<< wahrend der Erstellung
von TransTractor ubergeben wurde
debug()
kehrt zuruck, falls die Option >>debug<< wahrend der Erstellung von
TransTractor ubergeben wurde
get_in_charset()
Diese Funktion liefert den Zeichensatz zuruck, der als
Hauptzeichensatz bereitgestellt wurde
get_out_charset()
Diese Funktion wird den Zeichensatz zuruckgeben, der im
ausgegebenen Dokument benutzt werden sollte (ublicherweise
nutzlich, 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 zuruckgeben, so dass die Kodierung durchgefuhrt
wird.
ZUKUNFTIGE ENTWICKLUNGEN
Ein Mangel des aktuellen Transtractors ist, dass er keine ubersetzten
Dokumente handhaben kann, die alle Sprachen enthalten, wie Debconf-
Schablonen oder Desktop-Dateien.
Um dieses Problem anzugehen, sind nur bestimmte
Schnittstellenanderungen notwendig:
- einen Hash in po_in_name nehmen (eine Liste pro Sprache)
- ein zu ubersetzendes Argument hinzufugen, um die Zielsprache
anzugeben
- ein Funktion pushline_all erstellen, die pushline ihres Inhalts fur
alle Sprachen unter Benutzung einer kartenahnlichen Syntax ausfuhren
wurde:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Es wird sich zeigen, ob das ausreicht. ;)
AUTOREN
Denis Barbier