Provided by: po4a_0.66-1_all 
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).
Strumenti Po4a 2022-01-02 PO4A-GETTEXTIZE(1p)