
        *****************************************************
        *           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ò:

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

=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--; ) {
               # 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.

=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 usato nel documento in ingresso (se non specificato, usa
UTF-8).

=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, usa
UTF-8).

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

=item wrapcol ($)

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

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

=back

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

=back

=head2 Gestione file dei documenti

=over 4

=item read($$$)

Aggiunge i dati di un altro documento in ingresso alla fine della schiera
esistente C<< @{$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 C<< @{$self->{TT}{doc_in}} >> holds this input document data as an
array of strings with alternating meanings.
 * The string C<$textline> holding each line of the input text data.
 * The string C<< $filename:$linenum >> holding its location and called as
   "reference" (C<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.

=item write($)

Scrive il documento tradotto con il nome file specificato.

This translated document data are provided by:
 * C<< $self->docheader() >> holding the header text for the plugin, and
 * C<< @{$self->{TT}{doc_out}} >> holding each line of the main translated text in the 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:

    [normal use of the po4a document...]

    ($percent,$hit,$queries) = $document->stats();
    print "We found translations for $percent\%  ($hit from $queries) of strings.\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 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.

=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 alla quale si dovrebbe andare a capo (predefinita: il valore di
B<wrapcol> specificato durante la creazione del TransTractor o 76).

Il valore negativo verrà sottratto dal valore predefinito.

=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 get_in_charset()

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

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

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

