NAMN¶

Locale::Po4a::TransTractor – generisk trans(lator ex)tractor.

BESKRIVNING¶

Målet med po4a-projektet (PO för allt) är att underlätta översättningar (och, ännu mer intressant, underhållet av översättningar) med hjälp av gettext-verktyg på områden där de inte förväntades användas, såsom dokumentation.

Denna klass är föregångaren till alla po4a-parsers som används för att analysera ett dokument, söka efter översättningsbara strängar, extrahera dem till en PO-fil och ersätta dem med deras översättning i utdatadokumentet.

Mer formellt tar den följande argument som indata:

• ett dokument att översätta;
• en PO-fil som innehåller de översättningar som ska användas.

Som utdata producerar den:

• en annan PO-fil, som är resultatet av extraheringen av översättningsbara strängar från indatadokumentet;
• ett översatt dokument med samma struktur som det ursprungliga, men där alla översättningsbara strängar har ersatts med översättningarna i den PO-fil som angetts som indata.

Här är en grafisk representation av detta:

   Input document --\                             /---> Output document
                     \                           /       (translated)
                      +-> parse() function -----+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                         (extracted)

FUNKTIONER SOM DIN PARSARE BÖR ÖVERSKRIVA¶

parse()

Det är här allt arbete utförs: analys av indata, generering av utdata och extrahering av översättningsbara strängar. Detta är ganska enkelt med hjälp av de funktioner som presenteras i avsnittet INTERNAL FUNCTIONS nedan. Se även SYNOPSIS, som innehåller ett exempel.

Denna funktion anropas av funktionen process() nedan, men om du väljer att använda funktionen new() och lägga till innehåll manuellt i ditt dokument måste du själv anropa denna funktion.

docheader()

Denna funktion returnerar den rubrik som vi ska lägga till i det producerade dokumentet, korrekt citerad för att vara en kommentar på målspråket. Se avsnittet Educating developers about translations, från po4a(7), för information om vad den är bra för.

SYNOPSIS¶

Följande exempel analyserar en lista med stycken som börjar med "<p>". För enkelhetens skull antar vi att dokumentet är välformaterat, dvs. att '<p>" är de enda taggarna som finns, och att denna tagg finns i början av varje stycke.

 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>/ &amp;&amp; !$first--; ) {
               # Inte första gången vi ser <p>.
               # Sätt tillbaka den aktuella raden i indata,
               #  och lägg den byggda paragrafen till utdata
               $self->unshiftline($line,$lref);
               # Nu när dokumentet är format, översätt det:
               #   - Ta bort den inledande taggen
               $paragraph =~ s/^<p>//s;
               #   - skicka den inledande taggen (oöversatt) och
               #     resten av stycket (översatt) till utdata
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );
               nästa PARAGRAF;
           } else {
               # Lägg till i paragrafen
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }
           # Starta om slingan
           ($line,$lref)=$self->shiftline();
       }
       # Fick du inte en definierad rad? Slut på inmatningsfilen.
       return;
   }
 }

När du har implementerat parse-funktionen kan du använda din dokumentklass med hjälp av det offentliga gränssnittet som presenteras i nästa avsnitt.

Som standard läser din dokumentklass endast från den fil som användaren tillhandahåller. För att hantera filinkludering (t.ex. med \include i LaTeX eller liknande) måste du anropa read() för varje fil som ska inkluderas. Se modulen Tex.pm för ett exempel på en överskriven read()-funktion som inte bara laddar huvudfilen utan också söker efter inkluderingsförfrågningar och elegant lägger till de inkluderade filerna i raden av rader som ska analyseras. De inkluderade filerna infogas i det översatta dokumentet av modulen Tex.pm: allt innehåll placeras i det översatta dokumentet istället för att skapa separata filer för översättningen av inkluderade filer. Detta är något suboptimalt, särskilt om en inkluderad fil används i många filer, men att ändra detta skulle vara ganska komplicerat och ingen dokumentklass gör det hittills. Det skulle innebära att man överbelastar write()-funktionen som ansvarar för att skriva innehållet till den producerade lokaliserade filen, men jag är inte säker på att användningsfördelen skulle vara värd kodkomplexiteten. Lokaliserade filer är värdelösa filer som kan tas bort från disken när dokumentkompileringen är klar, så slöseriet med utrymme är mycket diskutabelt.

Observera att det är valfritt att använda read() för att lägga till innehåll i listan och shiftline() för att hämta detta innehåll. Modulen Sgml.pm använder till exempel inte denna mekanism, eftersom den istället använder en extern parser. Kontrollera funktionen read() från Sgml.pm för att se hur filnamnen sparas i en privat array och hur parse() sedan åsidosätts för att inte använda de klassiska parsningsfunktionerna utan istället en SGML-specifik parse_file(). Den senare funktionen skiljer sig mycket från resten av po4a-kodbasen, eftersom allt grovjobb utförs av den externa binären "onsgmls".

PUBLIC INTERFACE för skript som använder din parser¶

INTERNA FUNKTIONER som används för att skriva derivatparsers¶

 * Perl shift returnerar det första arrayelementet och tar bort det från arrayen.
 * Perl unshift lägger till ett element i början av arrayen som det första arrayelementet.
 * Perl pop returnerar det sista arrayelementet och tar bort det från arrayen.
 * Perl push lägger till ett element i slutet av arrayen som det sista arrayelementet.

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

FRAMTIDA RIKTNINGAR¶

En brist hos den nuvarande TransTractor är att den inte kan hantera översatta dokument som innehåller alla språk, såsom debconf-mallar eller .desktop-filer.

För att lösa detta problem behövs endast följande gränssnittsändringar:

• ta en hash som po_in_name (en lista per språk)
• lägg till ett argument för översättning för att ange målspråket
• skapa en pushline_all-funktion, som skulle skapa en pushline av dess innehåll för alla språk, med hjälp av en kartliknande syntax:

      $self->pushline_all({ "Description[".$langcode."]=".
                            $self->translate($line,$ref,$langcode)
                          });
      

Vi får se om det räcker ;)

UPPHOVSPERSONER¶

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