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¶

INTERNE FUNKTIONEN, die zum Schreiben abgeleiteter Parser verwendet werden¶

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

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>