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

po4a-gettextize - converte un documento originale (e la sua traduzione) in
un file PO

=head1 SINTASSI

B<po4a-gettextize> B<-f> I<formatoE> B<-m> I<originale.doc> [B<-l>
I<XX.doc>] B<-p> I<XX.po>

dove I<XX.po> è l'output e tutti gli altri sono input.

=head1 DESCRIZIONE

po4a (PO for anything - N.d.T. PO per tutto) semplifica la manutenzione
delle traduzioni della documentazione usando i classici strumenti forniti da
gettext. La caratteristica principale di po4a è che separa la traduzione dei
contenuti dalla struttura del relativo documento.  Fare riferimento alla
pagina L<po4a(7)> per un'introduzione a questo progetto.

Lo script B<po4a-gettextize> si occupa di convertire i documenti in file
PO. È necessario solo all'inizio quando si deve impostare il progetto di
traduzione con po4a, mai successivamente.

If you start from scratch, B<po4a-gettextize> will extract the translatable
strings from the documentation and write a POT file. If you provide a
previously existing translated file with the B<-l> flag, B<po4a-gettextize>
will try to use the translations that it contains in the produced PO
file. This process remains tedious and manual, as explained in Section
'Converting a manual translation to po4a' below.

Se il documento master contiene dei caratteri non ASCII, il file PO generato
sarà in UTF-8. Altrimenti (se il documento master è completamente in ASCII),
il PO userà la codifica del documento tradotto in ingresso, o UTF-8 se non
viene fornito alcun documento.

=head1 OPZIONI

=over 4

=item B<-f>, B<--format>

Formato del documento in questione. L'opzione B<--help-format> mostra
l'elenco dei formati disponibili.

=item B<-m>, B<--master>

Il file contenente il documento master da tradurre. Si può usare questa
opzione più volte se si vuole "gettext-izzare" più documenti.

=item B<-M>, B<--master-charset>

Set di caratteri del file contenente il documento da tradurre.

=item B<-l>, B<--localized>

Il file contenente la versione localizzata (tradotta) del documento. Se si
hanno più documenti master, è probabile si voglia anche fornire più
documenti localizzati usando quest'opzione più di una volta.

=item B<-L>, B<--localized-charset>

Set di caratteri del file contenente il documento tradotto.

=item B<-p>, B<--po>

File su cui scrivere il catalogo messaggi. Se non specificato, il catalogo
messaggi viene scritto sullo standard output.

=item B<-o>, B<--option>

Opzioni extra da passare al plugin di formato. Vedere la documentazione per
ogni plugin per ulteriori informazioni sulle opzioni valide e sul loro
significato. Per esempio si può passare "-o tablecells" al parser AsciiDoc
mentre il parser di testo semplice accetta "-o tabs=split".

=item B<-h>, B<--help>

Mostra un breve messaggio di aiuto.

=item B<--help-format>

Elenca i formati di documento gestiti da po4a.

=item B<-V>, B<--version>

Mostra la versione del programma ed esce.

=item B<-v>, B<--verbose>

Rende il programma più prolisso.

=item B<-d>, B<--debug>

Mostra delle informazioni di debug

=item B<--msgid-bugs-address> I<indirizzo@email>

Imposta l'indirizzo a cui inviare i rapporti di errore per i msgid. Come
impostazione predefinita, i file POT creati non hanno campi
Report-Msgid-Bugs-To.

=item B<--copyright-holder> I<stringa>

Imposta l'intestatario del copyright nell'intestazione del POT. Il valore
predefinito è "Free Software Foundation, Inc."

=item B<--package-name> I<stringa>

Imposta il nome del pacchetto nell'intestazione del POT. Il valore
predefinito è "PACKAGE".

=item B<--package-version> I<stringa>

Imposta la versione del pacchetto nell'intestazione del POT. Il valore
predefinito è "VERSION".

=back

=head2 Convertire la traduzione di un manuale a po4a

B<po4a-gettextize> cercherà di estrarre il contenuto di qualunque file di
traduzione gli venga fornito, ed usare questo contenuto come voci msgstr nel
file PO prodotto. Si osservi che tale processo è molto fragile: esso si basa
sulla supposizione che la stringa in posizione N nel file tradotto
corrisponda alla stringa di posizione N nel file originale. Ciò naturalmente
non funzionerà se i file non condividono esattamente la stessa struttura.

Internamente, ogni parser po4a riporta il tipo di sintassi di ogni stringa
estratta. Questo è il modo in cui la desincronizzazione viene rilevata
durante la fase di gettext-izzazione. Per esempio, se i file hanno la
seguente struttura, è molto improbabile che la quarta stringa nella
traduzione (di tipo 'capitolo') sia la traduzione della quarta stringa
nell'originale (di tipo 'paragrafo'), o che due paragrafi originali vengano
fusi assieme nella traduzione.

    Originale        Traduzione

  capitolo           capitolo
    paragrafo          paragrafo
    paragrafo          paragrafo
    paragrafo        chapter
  capitolo             paragrafo
    paragrafo          paragrafo

B<po4a-gettextize> will verbosely diagnose any detected structure
desynchronization. When this happens, you should manually edit the files
(this probably requires that you have some notions of the target
language). You must add fake paragraphs or remove some content in one of the
documents (or both) to fix the reported disparities, until the structure of
both documents perfectly match. Some tricks are given in the next section.

Even when the document is successfully processed, undetected disparities and
silent errors are still possible. That is why any translation associated
automatically by po4a-gettextize is marked as I<fuzzy> to require an manual
inspection by humans. One has to check that each retrieved msgstr is
actually the translation of the associated msgid, and not the string before
or after.

As you can see, the key here is to have the exact same structure in the
translated document and in the original one. The best is to do the
gettextization on the exact version of F<master.doc> that was used for the
translation, and only update the PO file against the latest master file once
the gettextization was successful.

Se si è abbastanza fortunati da avere le strutture di entrambi i documenti
che combaciano perfettamente, si lavorerà senza intoppi e si otterranno
risultati in pochi secondi. Altrimenti, si scoprirà perché questo processo
ha un nome così brutto, e sarà meglio essere preparati ad un bel po' di
lavoro. In ogni caso, è meglio ricordarsi che è il prezzo da pagare per
ottenere in seguito la comodità di po4a. Una volta fatta la conversione, la
sincronizzazione tra documenti master e le loro traduzioni sarà per sempre
completamente automatica.

Anche se le cose dovessero andare male, la gettext-izzazione rimane molto
più veloce che tradurre tutto nuovamente. Sono stato in grado di
gettext-izzare l'esistente traduzione francese della documentazione Perl in
un giorno, anche se la struttura di molti documenti era desincronizzata (2
milioni di caratteri): ripartire con una traduzione da zero avrebbe
richiesto dei mesi di lavoro.

=head2 Suggerimenti e trucchi per il processo di gettext-izzazione

The gettextization stops as soon as a desynchronization is detected. In
theory, it should probably be possible resynchronize the gettextization
later in the documents using e.g. the same algorithm than the L<diff(1)>
utility. But a manual intervention would still be mandatory to manually
match the elements that couldn't be automatically matched, explaining why
automatic resynchronization is not implemented (yet?).

Quando ciò accade, il succo del lavoro consiste nel riallineare la struttura
di questi file tramide modifiche manuali. Quando accade, B<po4a-gettextize>
è piuttosto prolisso nel descrivere cosa non ha funzionato. Indica le
stringhe che non corrispondono, la loro posizione nel testo, e il tipo di
ognuna di esse. Inoltre, il file PO generato fin lì verrà scaricato in
F<gettextization.failed.po> per consentirne l'analisi.

Ecco alcuni altri trucchi per alleviare in questo noioso lavoro:

=over 

=item 

Rimuovere tutto il contenuto extra delle traduzioni, come per esempio la
sezione riconoscimenti ai traduttori. Le si potranno riaggiungere in po4a in
seguito, usando un'addenda (vedere L<po4a(7)>).

=item 

If you need to edit the files to align their structures, you should prefer
editing the translation if possible. Indeed, if the changes to the original
are too intrusive, the old and new versions will not be matched during the
PO update, and the corresponding translation will be dumped anyway. But do
not hesitate to also edit the original document if required: the important
thing is to get a first PO file to start with.

=item 

Do not hesitate to kill any original content that would not exist in the
translated version. This content will be automatically reintroduced
afterward, when synchronizing the PO file with the document.

=item 

Si dovrebbe probabilmente informare l'autore originale di ogni cambiamento
strutturale nella traduzione che sembra giustificato. Se ci sono problemi
nell'originale, bisogna informarne l'autore. La correzione nella traduzione
corregge solo per una parte della comunità. Inoltre è in pratica impossibile
quando si usa po4a ;).

=item 

A volte, il contenuto dei paragrafi corrisponde, ma i loro tipi no. La
correzione è abbastanza dipendente dal formato. Nel POD e nelle pagine man,
spesso deriva dal fatto che uno dei due paragrafi contiene una riga che
inizia con uno spazio bianco mentre l'altro paragrafo no. In quei formati,
tali paragrafi non possono essere mandati a capo e quindi diventare di un
tipo diverso. In tal caso basta rimuovere lo spazio e si è a posto. Alle
volte si tratta anche di un semplice refuso nel nome del marcatore XML.

Allo stesso modo, due paragrafi possono venire uniti assieme nel POD quando
la riga di separazione contiene alcuni spazi, o quando non c'è una riga
vuota tra la riga B<=elemento> e il contenuto dell'elemento stesso.

=item 

A volte, il messaggio di desincronizzazione sembra strano perché la
traduzione viene collegata al paragrafo originale sbagliato. È il segno di
problema non rilevato prima nel processo. Controllare
F<gettextization.failed.po> per vedere quando inizia veramente il problema e
correggerlo dov'è effettivamente.

=item 

Con alcune impostazioni sfortunate, si ha forte sospetto che po4a abbia
mangiato alcune parti del testo, nell'originale o nella
traduzione. F<gettextization.failed.po> indica che entrambi i file
corrispondevano, come previsto, fino al paragrafo N. Ma poi, è stato
effettuato un tentativo (fallito) di abbinare il paragrafo N+1 nel file
originale non con il paragrafo N+1 nella traduzione come avrebbe dovuto, ma
con il paragrafo N+2. Come se il paragrafo N+1 che vedi nel documento fosse
semplicemente scomparso nel processo.

Questa sfortunata situazione si verifica quando uno stesso paragrafo si
ripete più volte nel documento. In questo caso nel file PO non viene creata
nessuna voce aggiuntiva, ma viene invece aggiunto un nuovo riferimento
all'esistente.

So, the previous situation occurs when two similar but different paragraphs
are translated in the exact same way. This will apparently remove a
paragraph of the translation. To fix the problem, it is sufficient to
slightly alter one of the translations in the document. You can also prefer
to kill the second paragraph in the original document.

All'opposto, se lo stesso paragrafo che appare due volte nel documento
originale non viene tradotto allo stesso modo in entrambe le posizioni, si
avrà la sensazione che un paragrafo dell'originale sia scomparso. Per
risolvere il problema basta copiare la migliore traduzione sopra l'altra nel
documento tradotto.

=item 

As a final note, do not be too surprised if the first synchronization of
your PO file takes a long time. This is because most of the msgid of the PO
file resulting from the gettextization don't match exactly any element of
the POT file built from the recent master files. This forces gettext to
search for the closest one using a costly string proximity algorithm.

For example, the first B<po4a-updatepo> of the Perl documentation's French
translation (5.5 MB PO file) took about 48 hours (yes, two days) while the
subsequent ones only take a dozen of seconds.

=back

=head1 VEDERE ANCHE

L<po4a(1)>, L<po4a-normalize(1)>, L<po4a-translate(1)>, L<po4a-updatepo(1)>,
L<po4a(7)>.

=head1 AUTORI

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)


=head1 TRADUZIONE

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

=head1 COPYRIGHT E LICENZA

Copyright 2002-2020 by SPI, inc.

Questo programma è software libero; è lecito ridistribuirlo o modificarlo
secondo i termini della licenza GPL (vedere il file COPYING).

