LOCALE::PO4A::TRANSTRACTOR.3PM(1)

NOME
Locale::Po4a::TransTractor - Modulo generico di traduzione ed estrazione del testo.

DESCRIZIONE
L'obiettivo del progetto po4a (PO per tutto) è di facilitare le traduzioni (e cosa più interessante, la manutenzione delle traduzioni) usando gli strumenti associati a gettext in aree inaspettate come la documentazione.

Questa classe è l'antenato di ogni parser po4a usato per analizzare un documento, per cercare stringhe traducibili, per estrarle in un file PO e per sostituirle con la loro traduzione nel documento in uscita.

Più formalmente, prende i seguenti argomenti in ingresso:

-   un documento da tradurre;

-   un file PO contenente le traduzioni da usare.

In uscita, produce:

-   un altro file PC, risultante dall'estrazione delle stringe traducibili dal documento in ingresso;

-   un documento tradotto, con la stessa struttura di quello in ingresso, ma con tutte le stringhe traducibili sostituite con le traduzioni trovate nel file PO fornito in ingresso.

Ecco una rappresentazione grafica di ciò:

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

FUNZIONI CHE IL PROPRIO PARSER DOVREBBE RIDEFINIRE

parse()
    È qui che si svolge tutto il lavoro: l'analisi dei documenti di ingresso, la generazione del risultato in uscita e l'estrazione delle stringhe traducibili. Tutto ciò è abbastanza semplice facendo uso delle funzioni presentate nella sezione FUNZIONI INTERNE di seguito. Vedere anche SINTASSI, che presenta un esempio.

    Questa funzione viene chiamata dalla funzione process() di seguito, ma se si sceglie di usare la funzione new() e di aggiungere contenuto manualmente al documento, si dovrà chiamare questa funzione.

docheader()
    Questa funzione restituisce l'intestazione che dovremmo aggiungere al documento prodotto, quotata opportunamente tanto da essere considerata un commento nella lingua di destinazione. Vedere la sezione Educare gli sviluppatori sulle traduzioni, da po4a(7), per sapere a cosa serve.

SINTASSI
L'esempio seguente analizza un elenco di paragrafi che iniziano con "<p>". Per semplicità, assumiamo che il documento sia ben formattato, ovvero che i tag '<p>' siano gli unici tag presenti e che questo tag sia all'inizio di ogni paragrafo.

 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--; ) {
               # Not the first time we see <p>.
               # Reput the current line in input,
               #  and put the built paragraph to output
               $self->unshiftline($line,$lref);

               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $paragraph =~ s/^<p>//s;

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       return;
   }
 }

Una volta implementata la funzione di analisi, si può usare la propria classe documento, usando l'interfaccia pubblica presentata nella sezione successiva.

INTERFACCIA PUBBLICA per gli script che usano il proprio parser

  Costruttore

processo(%)
    Questa funzione può fare tutto quello che si deve fare con un documento po4a in una sola chiamata. I suoi argomenti devono essere impacchettati come un hash. AZIONI:

    a.  Legge tutti i file PO specificati in po_in_name

    b.  Legge tutti i documenti originali specificati in file_in_name

    c.  Analizza il documento

    d.  Legge e applica tutte le addenda specificate

    e.  Scrive il documento tradotto in file_out_name (se fornito)

    f.  Scrive il file PO estratto in po_out_name (se fornito)

    ARGOMENTI, oltre a quelli accettati da new() (di tipo atteso):

    file_in_name (@)
        Elenco di nomi di file in cui si dovrebbe leggere il documento di ingresso.

    file_in_charset ($)
        Set di caratteri usato nel documento in ingresso (se non specificato, usa UTF-8).

    file_out_name ($)
        Nome file dove si dovrà scrivere il documento di uscita.

    file_out_charset ($)
        Set di caratteri usato nel documento in uscita (se non specificato, usa UTF-8).

    po_in_name (@)
        Elenco di nomi di file da cui leggere i file PO in ingresso, contenente la traduzione che verrà usata per tradurre il documento.

    po_out_name ($)
        Nome file dove si dovrà scrivere il file PO in uscita, contenente le stringhe estratte dal documento in ingresso.

    addendum (@)
        Elenco di nomi di file da cui si dovrà leggere le addenda.

    addendum_charset ($)
        Set di caratteri delle addenda.

new(%)
    Crea un nuovo documento po4a. Opzioni accettate (nell'hash passato come parametro):

    verbose ($)
        Imposta il livello di messaggi diagnostici.

    debug ($)
        Imposta il debug.

    wrapcol ($)
        Colonna alla quale mandare a capo il testo in uscita (predefinita: 76).

        Il valore negativo significa che le righe non vanno a capo.

    Inoltre accetta le opzioni successive per i file Po sottostanti: porefs, copyright-holder, msgid-bugs-address, package-name, package-version, wrap-po.

  Gestione file dei documenti

read($$$)
    Aggiunge i dati di un altro documento in ingresso alla fine della schiera esistente "@{$self->{TT}{doc_in}}".

    This function takes two mandatory arguments and an optional one.
     * The filename to read on disk;
     * The name to use as filename when building the reference in the PO file;
     * The charset to use to read that file (UTF-8 by default)

    This array "@{$self->{TT}{doc_in}}" holds this input document data as an array of strings with alternating meanings.
     * The string $textline holding each line of the input text data.
     * The string "$filename:$linenum" holding its location and called as
       "reference" ("linenum" starts with 1).

    Si noti che non analizza nulla. Si dovrebbe usare la funzione parse() quando si ha finito di impacchettare i file in ingresso nel documento.

write($)
    Scrive il documento tradotto con il nome file specificato.

    This translated document data are provided by:
     * "$self->docheader()" holding the header text for the plugin, and
     * "@{$self->{TT}{doc_out}}" holding each line of the main translated text in the array.

  Gestione file PO

readpo($)
    Aggiunge il contenuto di un file (il cui nome viene passato come argomento) al PO di ingresso esistente. Il vecchio contenuto non viene scartato.

writepo($)
    Scrive il file PO estratto nel nome file dato.

stats()
    Restituisce alcune statistiche sulla traduzione eseguita fino a quel momento. Si noti che non sono le stesse statistiche di quelle prodotte dal comando da msgfmt --statistic. Qui, sono le statistiche sull'utilizzo recente del file PO, mentre msgfmt riporta lo stato del file. È un wrapper per la funzione Locale::Po4a::Po::stats_get applicata al file PO di ingresso. Esempio d'uso:

        [normal use of the po4a document...]

        ($percent,$hit,$queries) = $document->stats();
        print "We found translations for $percent\%  ($hit from $queries) of strings.\n";

  Gestione addenda

addendum($)
    Fare riferimento a po4a(7) per maggiori informazioni su cosa sono gli addenda e su come i traduttori dovrebbero scriverli. Per applicare un addendum al documento tradotto, passare semplicemente il suo nome file a questa funzione ed il gioco è fatto ;)

    Questa funzione restituisce un intero non nullo in caso di errore.

FUNZIONI INTERNE usate per scrivere parser derivati

  Ottenere l'ingresso, fornire l'uscita
Vengono fornite quattro funzioni per catturare l'ingresso e restituire l'uscita. Sono molto simili a shift/unshift e push/pop di Perl.

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

La prima coppia riguarda l'ingresso, mentre la seconda riguarda l'uscita. Mnemonico: in ingresso, si è interessati alla prima riga, cosa dà shift, e in uscita si desidera aggiungere il risultato alla fine, come fa push.

shiftline()
    Questa funzione restituisce la prima riga da analizzare e il suo riferimento corrispondente (compresso come un array) dall'array "@{$self->{TT}{doc_in}}" e rilascia questi primi 2 elementi dell'array. Qui, il riferimento è fornito da una stringa "$filename:$linenum".

unshiftline($$)
    Annulla lo spostamento dell'ultima riga spostata del documento in ingresso e il relativo riferimento corrispondente all'inizio di "{$self->{TT}{doc_in}}".

pushline($)
    Inserisce una nuova riga alla fine di "{$self->{TT}{doc_out}}".

popline()
    Estrae l'ultima riga inserita dalla fine di "{$self->{TT}{doc_out}}".

  Marcatura stringhe come traducibili
Viene fornita una funzione per gestire il testo da tradurre.

translate($$$)
    Argomenti obbligatori:

    -   Una stringa da tradurre

    -   Il riferimento di questa stringa (cioè la posizione nel file di ingresso)

    -   Il tipo di questa stringa (cioè la descrizione testuale del suo ruolo strutturale; usata in Locale::Po4a::Po::gettextization(); vedere anche po4a(7), sezione Gettext-izzazione: come funziona?)

    Anche questa funzione usa alcuni argomenti extra. Questi devono essere organizzati come hash. Esempio:

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

    wrap
        booleano indicande se si può considerare gli spazi bianchi nella stringa come non importanti. Se si, la funzione canonizza la stringa prima di cercare una traduzione o estrarla, e formatta la traduzione.

    wrapcol
        la colonna alla quale si dovrebbe andare a capo (predefinita: il valore di wrapcol specificato durante la creazione del TransTractor o 76).

        Il valore negativo verrà sottratto dal valore predefinito.

    comment
        un commento extra da aggiungere alla voce.

    Azioni:

    -   Infila stringa, riferimento e tipo in po_out.

    -   Restituisce la traduzione della stringa (come trovata in po_in) in modo che l'analizzatore possa creare doc_out.

    -   Gestisce i set di caratteri per ricodificare le stringhe prima di inviarle a po_out e prima di restituire le traduzioni.

  Funzioni varie

verbose()
    Restituisce se l'opzione verbose è stata passata durante la creazione di TransTractor.

debug()
    Restituisce se l'opzione di debug è stata passata durante la creazione di TransTractor.

get_in_charset()
    Questa funzione restituisce il set di caratteri che è stato fornito come master

get_out_charset()
    Questa funzione restituirà il set di caratteri che dovrebbe essere utilizzato nel documento in uscita (solitamente utile per sostituire il set di caratteri rilevato del documento in ingresso dove è stato trovato).

    Userà il set di caratteri in uscita specificato nella riga di comando. Se non è stato specificato, userà il set di caratteri del PO in ingresso e se il PO in ingresso ha il "CHARSET" predefinito, restituirà il set di caratteri del documento in ingresso, in modo che non venga eseguita alcuna codifica.

DIREZIONI FUTURE
Un difetto dell'attuale TransTractor è che non può gestire documenti tradotti contenenti tutte le lingue, come modelli debconf o file .desktop.

Per risolvere questo problema, le uniche modifiche all'interfaccia necessarie sono:

-   prendere un hash come po_in_name (un elenco per lingua)

-   aggiungere un argomento da tradurre per indicare la lingua di destinazione

-   crea una funzione pushline_all, fa in modo di eseguire una pushline del suo contenuto per tutte le lingue, utilizzando una sintassi simile a una mappa:

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

Vedremo se è abbastanza ;)

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

TRADUZIONE
 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@posteo.net>