NOME

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

SINTASSI

       po4a-gettextize -f formato -m originale.doc [-l XX.doc] -p XX.po

       (XX.po è l'output, tutti gli altri sono input)

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 po4a(7) per un'introduzione a questo progetto.

       Lo script 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.

       Se parte da zero, po4a-gettextize estrarrà le stringhe traducibili dalla documentazione e
       scriverà un file POT. Se si fornisce un file tradotto già esistente con il flag -l,
       po4a-gettextize proverà a usare le traduzioni che contiene nel file PO prodotto. Questo
       processo rimane noioso e manuale, come spiegato più avanti nella sezione "Conversione di
       una traduzione manuale in po4a".

       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.

OPZIONI

       -f, --format
           Formato del documento in questione. L'opzione --help-format mostra l'elenco dei
           formati disponibili.

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

       -M, --master-charset
           Set di caratteri del file contenente il documento da tradurre.

       -l, --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.

       -L, --localized-charset
           Set di caratteri del file contenente il documento tradotto.

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

       -o, --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".

       -h, --help
           Mostra un breve messaggio di aiuto.

       --help-format
           Elenca i formati di documento gestiti da po4a.

       -V, --version
           Mostra la versione del programma ed esce.

       -v, --verbose
           Rende il programma più prolisso.

       -d, --debug
           Mostra delle informazioni di debug

       --msgid-bugs-address 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.

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

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

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

   Convertire la traduzione di un manuale a po4a
       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

       po4a-gettextize diagnostica in modo prolisso qualsiasi desincronizzazione della struttura
       rilevata. Quando ciò accade, è necessario modificare manualmente i file (ciò probabilmente
       richiede avere alcune nozioni sulla lingua di destinazione). È necessario aggiungere
       paragrafi falsi o rimuovere alcuni contenuti in uno dei documenti (o entrambi) per
       correggere le disparità segnalate, fino a quando la struttura di entrambi i documenti non
       corrisponde perfettamente. Alcuni trucchi sono forniti nella sezione successiva.

       Anche quando il documento viene elaborato correttamente, sono ancora possibili disparità
       non rilevate ed errori silenziosi. Questo è il motivo per cui qualsiasi traduzione
       associata automaticamente da po4a-gettextize viene contrassegnata come fuzzy per
       richiedere un'ispezione manuale. È necessario verificare che ogni msgstr recuperato sia
       effettivamente la traduzione del msgid associato e non la stringa prima o dopo.

       Come si può vedere, è fondamentale avere la stessa identica struttura nel documento
       tradotto e in quello originale. La cosa migliore è eseguire la "gettext-izzazione" sulla
       versione esatta di master.doc utilizzata per la traduzione e aggiornare il file PO
       rispetto al file master più recente solo una volta che la "gettext-izzazione" abbia avuto
       successo.

       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.

   Suggerimenti e trucchi per il processo di gettext-izzazione
       La gettextization si interrompe non appena viene rilevata una desincronizzazione. In
       teoria, dovrebbe probabilmente essere possibile risincronizzare la "gettext-izzazione" più
       avanti nei documenti usando ad es. lo stesso algoritmo di diff(1). Ma un intervento
       manuale sarebbe comunque obbligatorio per abbinare manualmente gli elementi che non
       possono essere abbinati automaticamente, spiegando perché la risincronizzazione automatica
       non è stata implementata (ancora?).

       Quando ciò accade, il succo del lavoro consiste nel riallineare la struttura di questi
       file tramide modifiche manuali. Quando accade, 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 gettextization.failed.po per consentirne l'analisi.

       Ecco alcuni altri trucchi per alleviare in questo noioso lavoro:

       •   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 po4a(7)).

       •   Se è necessario modificare i file per allineare le loro strutture, è preferibile
           modificare la traduzione, se possibile. Infatti, se le modifiche all'originale sono
           troppo invadenti, la vecchia e la nuova versione non verranno abbinate durante
           l'aggiornamento del PO e la traduzione corrispondente verrà comunque scaricata. Ma non
           si esitati a modificare anche il documento originale, se necessario: l'importante è
           ottenere un primo file PO con cui iniziare.

       •   Non fatevi problemi a eliminare qualsiasi contenuto originale che non esisterebbe
           nella versione tradotta. Questo contenuto verrà reintrodotto automaticamente in
           seguito, durante la sincronizzazione del file PO con il documento.

       •   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 ;).

       •   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
           =elemento e il contenuto dell'elemento stesso.

       •   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 gettextization.failed.po per vedere quando inizia veramente
           il problema e correggerlo dov'è effettivamente.

       •   Con alcune impostazioni sfortunate, si ha forte sospetto che po4a abbia mangiato
           alcune parti del testo, nell'originale o nella traduzione. 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.

           Quindi, la situazione precedente si verifica quando due paragrafi simili ma diversi
           vengono tradotti nello stesso identico modo. Apparentemente questo rimuoverà un
           paragrafo della traduzione. Per risolvere il problema, è sufficiente modificare
           leggermente una delle traduzioni nel documento. Se lo si preferisce si può anche
           eliminare il secondo paragrafo nel documento originale.

           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.

       •   Come nota finale, non siate troppo sorpresi se la prima sincronizzazione del file PO
           richiede molto tempo. Questo perché la maggior parte del msgid del file PO risultante
           dalla "gettext-izzazione" non corrisponde esattamente a nessun elemento del file POT
           creato dai file master recenti. Questo costringe gettext a cercare quello più vicino
           utilizzando un pesante algoritmo di prossimità di stringhe.

           Ad esempio, il primo po4a-updatepo della traduzione francese della documentazione Perl
           (file PO da 5,5 MB) ha impiegato circa 48 ore (sì, due giorni) mentre i successivi
           solo una dozzina di secondi.

VEDERE ANCHE

       po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTORI

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

TRADUZIONE

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

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