NAME¶

BESCHREIBUNG¶

-

ein zu übersetzendes Dokument

-

eine PO-Datei, die die zu verwendende Übersetzung enthält.

-

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.

   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¶

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

Ö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:

new(%)

erstellt ein neues Po4a-Dokument; akzeptiert Optionen (aber nur in Form eines Hashs):

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¶

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¶

translate($$$)

vorgeschriebene Argumente:

  $self->translate("string","ref","type",
                   'wrap' => 1);

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¶

-

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) 
                        });
    

AUTOREN¶

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>