
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

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

=head1 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:

=over 2

=item -

un documento da tradurre;

=item -

un file PO contenente le traduzioni da usare.

=back

In uscita, produce:

=over 2

=item -

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

=item -

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.

=back

Ecco una rappresentazione grafica di ciò:

 Documento in ingresso -\                          /--> Documento in uscita
                         \                        /         (tradotto)
                          +-> funzione parse() --+
                         /                        \
  PO in ingresso -------/                          \--> PO in uscita
                                                          (estratto)

=head1 FUNZIONI CHE IL PROPRIO PARSER DOVREBBE RIDEFINIRE

=over 4

=item 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 B<FUNZIONI INTERNE> di seguito. Vedere anche B<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.

=item 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 B<Educare gli sviluppatori sulle traduzioni>, da L<po4a(7)|po4a.7>, per sapere a cosa serve.

=back

=head1 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--; ) {
               # Non la prima volta che si vede <p>.
               # Rimette la riga corrente in ingresso,
               #  e mette il paragrafo costruito in uscita
               $self->unshiftline($line,$lref);

               # Ora che il documento è formato, lo traduce:
               #   - Rimuove il tag d'inzio
               $paragraph =~ s/^<p>//s;

               #   - inserisce in uscita il tag iniziale (non tradotto) e
               #     il resto del paragrafo (tradotto)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Accoda al paragrafo
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinizializza il ciclo
           ($line,$lref)=$self->shiftline();
       }
       # Nessuna una riga definita? Fine file in ingresso.
       return;
   }
 }

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

=head1 INTERFACCIA PUBBLICA per gli script che usano il proprio parser

=head2 Costruttore

=over 4

=item 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:

=over 3

=item a.

Legge tutti i file PO specificati in po_in_name

=item b.

Legge tutti i documenti originali specificati in file_in_name

=item c.

Analizza il documento

=item d.

Legge e applica tutte le addenda specificate

=item e.

Scrive il documento tradotto in file_out_name (se fornito)

=item f.

Scrive il file PO estratto in po_out_name (se fornito)

=back

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

=over 4

=item file_in_name (@)

Elenco di nomi di file in cui si dovrebbe leggere il documento di ingresso.

=item file_in_charset ($)

Set di caratteri utilizzato nel documento di ingresso (se non è specificato, proverà a rilevarlo dal documento di ingresso).

=item file_out_name ($)

Nome file dove si dovrà scrivere il documento di uscita.

=item file_out_charset ($)

Set di caratteri usato nel documento in uscita (se non è specificato, userà il set di caratteri del file PO).

=item 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.

=item po_out_name ($)

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

=item addendum (@)

Elenco di nomi di file da cui si dovrà leggere le addenda.

=item addendum_charset ($)

Set di caratteri delle addenda.

=back

=item new(%)

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

=over 4

=item verbose ($)

Imposta il livello di messaggi diagnostici.

=item debug ($)

Imposta il debug.

=back

=back

=head2 Gestione file dei documenti

=over 4

=item read($$)

Aggiunge un altro dato del documento di input alla fine dell'array esistente C<< @{$self->{TT}{doc_in}} >>. L'argomento è il nome del file da leggere. Se viene fornito un secondo argomento, è il nome del file da utilizzare nei riferimenti.

Questo array C<< @{$self->{TT}{doc_in}} >> contiene i dati di questo documento
di ingresso come array di stringhe con significati alternati.
  * La stringa C<$textline> contenente ogni riga dei dati di testo di ingresso.
  * La stringa C<< $filename:$linenum >> contenente la sua posizione viene
    chiamata come "riferimento" (C<linenum> inizia con 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.

=item write($)

Scrive il documento tradotto con il nome file specificato.

I dati di questo documento tradotto sono forniti da:
  * C<< $self->docheader() >> che contiene il testo dell'intestazione per il plugin, e
  * C<< @{$self->{TT}{doc_out}} >> che contiene ogni riga del testo tradotto principale nell'array.

=back

=head2 Gestione file PO

=over 4

=item 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.

=item writepo($)

Scrive il file PO estratto nel nome file dato.

=item 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:

    [uso normale del documento po4a...]

    ($percent,$hit,$queries) = $document->stats();
    print "Trovate traduzioni for $percent\%  ($hit da $queries) di stringhe.\n";

=back

=head2 Gestione addenda

=over 4

=item addendum($)

Fare riferimento a L<po4a(7)|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.

=back

=head1 FUNZIONI INTERNE usate per scrivere parser derivati

=head2 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 restituisce il primo elemento dell'array e lo toglie dall'array.
 * Perl unshift antepone un elemento all'array come primo elemento dell'array.
 * Perl pop restituisce l'ultimo elemento dell'array e lo toglie dall'array.
 * Perl push aggiunge un elemento all'array come ultimo elemento dell'array.

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.

=over 4

=item shiftline()

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

=item unshiftline($$)

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

=item pushline($)

Inserisce una nuova riga alla fine di C<< {$self->{TT}{doc_out}} >>.

=item popline()

Estrae l'ultima riga inserita dalla fine di C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Marcatura stringhe come traducibili

Viene fornita una funzione per gestire il testo da tradurre.

=over 4

=item translate($$$)

Argomenti obbligatori:

=over 2

=item -

Una stringa da tradurre

=item -

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

=item -

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

=back

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

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

=over 

=item B<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.

=item B<wrapcol>

la colonna a cui andare a capo (valore predefinito: 76).

=item B<comment>

un commento extra da aggiungere alla voce.

=back

Azioni:

=over 2

=item -

Infila stringa, riferimento e tipo in po_out.

=item -

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

=item -

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

=back

=back

=head2 Funzioni varie

=over 4

=item verbose()

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

=item debug()

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

=item detected_charset($)

Questo dice a TransTractor che un nuovo set di caratteri (il primo argomento) è stato rilevato dal documento in ingresso. Di solito può essere letto dall'intestazione del documento. Rimarrà solo il primo set di caratteri, proveniente dagli argomenti process() o rilevato dal documento.

=item 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.

=item recode_skipped_text($)

Questa funzione restituisce il testo ricodificato passato come argomento, dal set di caratteri del documento in ingresso a quello del documento in uscita. Non è indispensabile quando si traduce una stringa (dato che translate() ricodifica tutto da solo), ma è necessario quando si salta una stringa dal documento in ingresso e si desidera che il documento in uscita sia coerente con la codifica globale.

=back

=head1 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:

=over 2

=item -

prendere un hash come po_in_name (un elenco per lingua)

=item -

aggiungere un argomento da tradurre per indicare la lingua di destinazione

=item -

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

=back

Vedremo se è abbastanza ;)

=head1 AUTORI

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


=head1 TRADUZIONE

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

