.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "LOCALE::PO4A::TRANSTRACTOR.3PM 1" .TH LOCALE::PO4A::TRANSTRACTOR.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Locale::Po4a::TransTractor \- generischer Übersetzungs\-Ausleser .SH BESCHREIBUNG .IX Header "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. .PP 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. .PP Oder formaler, sie erwartet die folgenden Argumente als Eingabe: .IP \- 2 ein zu übersetzendes Dokument .IP \- 2 eine PO-Datei, die die zu verwendende Übersetzung enthält. .PP Als Ausgabe produziert sie: .IP \- 2 eine weitere PO-Datei, die aus der Auslösung der übersetzbaren Zeichenketten aus dem Eingabedokument entsteht .IP \- 2 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. .PP Dies ist eine graphische Darstellung davon: .PP .Vb 6 \& Eingabedokument \-\-\e /\-\-\-> Ausgabedokument \& \e / (übersetzt) \& +\-> parse()\-Funktion \-\-\-\-\-+ \& / \e \& Eingabe\-PO \-\-\-\-\-\-\-/ \e\-\-\-> Ausgabe\-PO \& (herausgelöst) .Ve .SH "FUNCTIONEN, DIE IHR PARSER ÜBERSCHREIBEN SOLLTE" .IX Header "FUNCTIONEN, DIE IHR PARSER ÜBERSCHREIBEN SOLLTE" .IP \fBparse()\fR 4 .IX Item "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 \fBINTERNE FUNKTIONEN\fR weiter unten vorgestellten angebotenen Funktionen recht einfach. Lesen Sie auch die \fBÜBERSICHT\fR, in der ein Beispiel vorgestellt wird. .Sp Diese Funktion wird von der unten beschriebenen \fBprocess()\fR\-Funktion aufgerufen. Falls Sie sich aber entscheiden, die \fBnew()\fR\-Funktion zu verwenden und den Inhalt manuell zu Ihrem Dokument hinzuzufügen, müssen Sie diese Funktion selbst aufrufen. .IP \fBdocheader()\fR 4 .IX Item "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 \fBEntwickler über Übersetzungen schulen\fR, von \fBpo4a\fR\|(7), um zu erfahren, wozu dies benutzt wird. .SH ÜBERSICHT .IX Header "ÜBERSICHT" Das folgende Beispiel wertet eine Liste von Absätzen aus, die mit »
» 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. .PP .Vb 2 \& 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. \& # 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/^
//s; \& \& # \- die Ausgabe der führenden Markierung (unübersetzt) und des \& # Rests des Absatzes (unübersetzt) anstoßen \& $self\->pushline( "
"
\& . $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;
\& }
\& }
.Ve
.PP
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.
.SH "ÖFFENTLICHE SCHNITTSTELLE für Skripte, die Ihren Parser benutzen"
.IX Header "ÖFFENTLICHE SCHNITTSTELLE für Skripte, die Ihren Parser benutzen"
.SS Konstruktor
.IX Subsection "Konstruktor"
.IP process(%) 4
.IX Item "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:
.RS 4
.IP a. 3
.IX Item "a."
liest alle PO-Dateien, die in po_in_name angegeben sind
.IP b. 3
.IX Item "b."
liest alle Originaldokumente, die in file_in_name angegeben sind
.IP c. 3
.IX Item "c."
wertet das Dokument aus
.IP d. 3
.IX Item "d."
liest alle angegebenen Addenda und wendet sie an
.IP e. 3
.IX Item "e."
schreibt das übersetzte Dokument in file_out_name (falls angegeben)
.IP f. 3
.IX Item "f."
schreibt die extrahierte PO-Datei nach po_out_name (falls angegeben)
.RE
.RS 4
.Sp
ARGUMENTE jenseits der durch \fBnew()\fR akzeptierten (mit erwartetem Typ):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Liste der Dateinamen, bei denen das Eingabedokument gelesen werden sollte
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
im Eingabedokument benutzter Zeichensatz (falls er nicht angegeben wurde, wird UTF\-8 benutzt).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Name der Datei, in den das Ausgabedokument geschrieben werden soll
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
im Ausgabedokument benutzter Zeichensatz (falls er nicht angegeben wurde, wird UTF\-8 benutzt).
.IP "po_in_name (@)" 4
.IX Item "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
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Name der Datei, in den die Ausgabe-PO-Datei geschrieben werden soll; enthält die aus dem Eingabedokument extrahierten Zeichenketten.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Liste der Dateinamen, aus denen die Addenda gelesen werden
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Zeichensatz für die Addenda
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
erstellt ein neues Po4a\-Dokument; akzeptiert Optionen (in dem als Parameter übergebenen Hash):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
setzt die Detailstufe
.IP "debug ($)" 4
.IX Item "debug ($)"
setzt die Debugging-Stufe
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
die Spalte, an der der Text im Ausgabedokument umgebrochen werden soll (standardmäßig 76)
.Sp
Ein negativer Wert bedeutet, dass überhaupt kein Umbruch stattfindet.
.RE
.RS 4
.Sp
Es akzeptiert auch die nächsten Optionen für zugrundeliegende PO-Dateien: \fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fR.
.RE
.SS "Manipulieren von Dokumentdateien"
.IX Subsection "Manipulieren von Dokumentdateien"
.IP read($$$) 4
.IX Item "read($$$)"
Fügt weitere Eingabedokumentendaten am Ende des bestehenden Felds \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR hinzu.
.Sp
Diese Funktion akzeptiert zwei verpflichtende Argumente und ein optionales.
* Der von Platte zu lesende Dateiname;
* Der Name, der für den Bau von Referenzen in der PO-Datei verwandt werden soll;
* Der Zeichensatz, der zum Lesen dieser Datei (standardmäßig UTF\-8) verwendet werden soll
.Sp
Das Feld \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR hält die Eingabedokumentdaten als ein
Feld von Zeichenketten mit abwechselnden Bedeutungen.
* Die Zeichenkette \f(CW$textline\fR hält jede Zeile der Eingabetextdaten.
* Die Zeichenkette \f(CW\*(C`$filename:$linenum\*(C'\fR hält ihren Ort und wird
»reference« genannt (\f(CW\*(C`linenum\*(C'\fR beginnt mit 1).
.Sp
Bitte beachten Sie, dass es nichts auswertet. Sie sollten die Funktion \fBparse()\fR benutzen, wenn Sie damit fertig sind, Eingabedateien in das Dokument zu packen.
.IP write($) 4
.IX Item "write($)"
schreibt das übersetzte Dokument in den angegebene Dateinamen
.Sp
Diese übersetzten Dokumentdaten werden bereitgestellt durch:
* \f(CW\*(C`$self\->docheader()\*(C'\fR hält den Kopftext für die Erweiterung und
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR hält jede Zeile des übersetzten Haupttextes in dem Feld.
.SS "PO-Dateien bearbeiten"
.IX Subsection "PO-Dateien bearbeiten"
.IP readpo($) 4
.IX Item "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.
.IP writepo($) 4
.IX Item "writepo($)"
schreibt die extrahierte PO-Datei in den angegebene Dateinamen
.IP \fBstats()\fR 4
.IX Item "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:
.Sp
.Vb 1
\& [normale Benutzung des Po4a\-Dokuments …]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Es wurden Übersetzungen für $percent\e% ($hit von $queries) der Zeichenketten gefunden.\en";
.Ve
.SS "Addenda manipulieren"
.IX Subsection "Addenda manipulieren"
.IP addendum($) 4
.IX Item "addendum($)"
Weitere Informationen, was Addenda sind und wie Übersetzer sie schreiben sollten, finden Sie unter \fBpo4a\fR\|(7). Um ein Addendum auf ein übersetztes Dokument anzuwenden, übergeben Sie einfach dieser Funktion seinen Dateinamen und Sie sind fertig. ;)
.Sp
Diese Funktion gibt bei einem Fehler eine Ganzzahl ungleich Null zurück.
.SH "INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden"
.IX Header "INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden"
.SS "Eingaben erhalten, Ausgaben bereitstellen"
.IX Subsection "Eingaben erhalten, Ausgaben bereitstellen"
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.
.PP
.Vb 4
\& * 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.
.Ve
.PP
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.
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
Diese Funktion liefert die erste auszuwertende Zeile und ihre entsprechende Referenz (als Feld gepackt) aus dem Feld \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR zurück und entfernt diese ersten zwei Feldeinträge. Hier wird die Referenz durch eine Zeichenkette \f(CW\*(C`$filename:$linenum\*(C'\fR bereitgestellt.
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
Schiebt die letzte geschobene Zeile des Eingabedokuments und seiner entsprechenden Referenz an den Kopf von \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR zurück.
.IP pushline($) 4
.IX Item "pushline($)"
Schiebt eine neue Zeile an das Ende von \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP \fBpopline()\fR 4
.IX Item "popline()"
Holt die zuletzt geschobene Zeile vom Ende von \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Zeichenketten als übersetzbar markieren"
.IX Subsection "Zeichenketten als übersetzbar markieren"
Eine Funktion wird bereitgestellt, um den Text zu handhaben, der übersetzt werden soll.
.IP translate($$$) 4
.IX Item "translate($$$)"
vorgeschriebene Argumente:
.RS 4
.IP \- 2
eine zu übersetzende Zeichenkette
.IP \- 2
die Referenz dieser Zeichenkette (d.h. Position in der Eingabedatei)
.IP \- 2
der Typ der Zeichenkette (d.h. die inhaltliche Beschreibung ihrer strukturellen Rolle; benutzt in \fBLocale::Po4a::Po::gettextization()\fR; siehe auch \fBpo4a\fR\|(7), Abschnitt \fBGettextisierung: Wie funktioniert das?\fR)
.RE
.RS 4
.Sp
Diese Funktion kann außerdem einige zusätzliche Argumente entgegennehmen. Sie müssen als Hash organisiert sein. Zum Beispiel:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "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.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
die Spalte an der umgebrochen werden soll (standardmäßig der Wert von \fBwrapcol\fR, der während der Erstellung des TransTractor festgelegt wurde oder 76).
.Sp
Der negative Wert wird von der Vorgabe abgezogen.
.IP \fBcomment\fR 4
.IX Item "comment"
ein zusätzlicher Kommentar, der zum Eintrag hinzugefügt wird
.RE
.RS 4
.Sp
Aktionen:
.IP \- 2
schiebt die Zeichenkette, die Referenz und den Typ nach po_out
.IP \- 2
gibt die Übersetzung der Zeichenkette (wie sie in po_in gefunden wurde) zurück, so dass der Parser das doc_out bauen kann
.IP \- 2
handhabt die Zeichensätze, um den Zeichensatz der Zeichenkette umzuwandeln, bevor sie an po_out gesandt werden und bevor die Übersetzungen zurückgegeben werden
.RE
.RS 4
.RE
.SS "Verschiedene Funktionen"
.IX Subsection "Verschiedene Funktionen"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
kehrt zurück, falls die Option »verbose« während der Erstellung von TransTractor übergeben wurde
.IP \fBdebug()\fR 4
.IX Item "debug()"
kehrt zurück, falls die Option »debug« während der Erstellung von TransTractor übergeben wurde
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
Diese Funktion liefert den Zeichensatz zurück, der als Hauptzeichensatz bereitgestellt wurde
.IP \fBget_out_charset()\fR 4
.IX Item "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).
.Sp
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.
.SH "ZUKÜNFTIGE ENTWICKLUNGEN"
.IX Header "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.
.PP
Um dieses Problem anzugehen, sind nur bestimmte Schnittstellenänderungen notwendig:
.IP \- 2
einen Hash in po_in_name nehmen (eine Liste pro Sprache)
.IP \- 2
ein zu übersetzendes Argument hinzufügen, um die Zielsprache anzugeben
.IP \- 2
ein Funktion pushline_all erstellen, die pushline ihres Inhalts für alle Sprachen unter Benutzung einer kartenähnlichen Syntax ausführen würde:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Es wird sich zeigen, ob das ausreicht. ;)
.SH AUTOREN
.IX Header "AUTOREN"
.Vb 3
\& Denis Barbier