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

NOME

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

SINTASSI

       po4a-gettextize -f formato -m master.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 aiuta a convertire le traduzioni già esistenti in un flusso di lavoro basato su
po4a. Effettua il salvataggio della traduzione esistente in modo che sia pronta per la conversione a
po4a, e quindi non serve più usarlo dopo la conversione del progetto. Questo noioso processo è spiegato
in dettaglio nella sezione seguente 'Convertire la traduzione di un manuale a po4a'.

È necessario fornire sia un file master (ad es. la sorgente in inglese) sia un file tradotto esistente
(ad es. un precedente tentativo di traduzione senza po4a). Se si fornisce più di un file master o di
traduzione, verranno utilizzati in sequenza, ma potrebbe essere più semplice gettext-izzare ciascuna
pagina o capitolo separatamente e quindi utilizzare msgmerge per unire tutti i file PO prodotti. Fate
come volete.

Se il documento master contiene dei caratteri non ASCII, il file PO generato sarà in UTF-8. Se il
documento master è completamente in ASCII, il PO generato userà la codifica del documento tradotto in
ingresso.

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.

-k --keep-temps
Mantiene il master temporaneo e i file POT localizzati creati prima della fusione. Può essere utile
per capire perché questi file vengono desincronizzati, causando i problemi di gettex-tizzazione.

-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 sincronizza il master i e file localizzati per estrarre i loro contenuti e metterli in un
file PO. Il contenuto del master file produce i msgid mentre i contenuti dei file localizzati danno i
msgstr. Questo processo è un po' fragile: la N-esima stringa del file tradotto si suppone sia la
traduzione dell'N-esima stringa nell'originale.

La gettext-izzazione funziona meglio se si riesce a recuperare la versione esatta del documento originale
che è stato utilizzato per la traduzione. Anche così, potrebbe essere necessario giocherellare con i file
master e localizzati per allineare la loro struttura se è stata modificata dal traduttore originale,
quindi si consiglia di lavorare su copie dei file originali.

Internamente, ogni analizzatore 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. Nell'esempio
mostrato sotto, è molto improbabile che la quarta stringa nella traduzione (di tipo 'chapter') sia la
traduzione della quarta stringa nell'originale (di tipo 'paragraph'). È più probabile che un nuovo
paragrafo sia stato aggiunto all'originale, o che due paragrafi nell'originale siano stati 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 per aggiungere paragrafi falsi o rimuovere
alcuni contenuti in uno dei documenti (o entrambe le cose) per correggere le disparità segnalate, fino a
quando la struttura di entrambi i documenti non corrisponde perfettamente. Di seguito alcuni trucchi per
recuperare il più possibile della traduzione esistente.

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à il perché
questo processo ha un nome così brutto :). In ogni caso, la gettext-izzazione spesso è sempre più veloce
che ritradurre tutto daccapo. L'autore della documentazione ha gettext-izzato l'intera traduzione della
documentazione Perl in un giorno malgrado molti problemi di sincronizzazione. Data la quantità di testo
(2MB di testo originale), la traduzione senza il recupero delle vecchie traduzioni avrebbe richiesto
diversi mesi di lavoro. Inoltre, questo brutto lavoro è 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.

Dopo una corretta gettext-izzazione, i documenti prodotti si dovrebbero controllare manualmente per le
disparità non rilevate e gli errori silenziosi, come spiegato di seguito.

Suggerimenti e trucchi per il processo di gettext-izzazione

La gettext-izzazione si ferma non appena viene rilevata una desincronizzazione. Quando ciò accade,
bisogna modificare i file quel tanto che basta per riallinearne le strutture. po4a-gettextize è piuttosto
prolisso quando qualcosa non funziona: indica le stringhe che non corrispondono, la loro posizione nel
testo, e il tipo di ognuna di esse. Inoltre, il file PO generato fino a quel punto viene salvato in
gettextization.failed.po per consentirne la successiva analisi.

Ecco alcuni altri trucchi per alleviare questo noioso lavoro e assicurarsi che non si distrugga buona
parte del precedente lavoro di traduzione:

• Rimuovere tutto il contenuto extra delle traduzioni, come per esempio la sezione riconoscimenti ai
traduttori. Le si potranno riaggiungere con po4a in seguito, usando gli addenda (vedere po4a(7)).

• Se si sta modificando i file per allineare le loro strutture, è preferibile modificare la traduzione,
se possibile. Infatti, se le modifiche all'originale sono troppe, la vecchia e la nuova versione non
collimeranno durante la prima esecuzione di po4a dopo la gettext-izzazione (vedere più avanti). Ogni
traduzione non corrispondente verrà comunque scaricata. Detto questo, si vorrà comunque modificare il
documento originale se è troppo difficile ottenere la continuazione del processo di gettext-izzazione
in altro modo, anche se ciò significherà che un paragrafo della traduzione venga gettato via.
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. Problemi nell'originale andrebbero comunicati all'autore. La
correzione nella traduzione corregge solo per una parte della comunità. Inoltre è impossibile usando
po4a ;). Ma è probabile si voglia aspettare la fine della conversione a po4a prima di cambiare i file
originali.

• 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. Cercare il
punto di desincronizzazione ispezionando il file gettextization.failed.po prodotto, per vedere quando
inizia veramente il problema e correggerlo dov'è effettivamente.

• Altri problemi possono derivare da stringhe duplicate nell'originale o nella traduzione. Le stringhe
duplicate vengono fuse nei file PO, con due riferimenti. Ciò costituisce un problema per l'algoritmo
di gettext-izzazione, che consiste in un semplice accoppiamento uno a uno tra i msgid del file master
e quelli dei file localizzati. Le versioni recenti di po4a dovrebbero però gestire correttamente le
stringhe duplicate, quindi, per qualsiasi problema residuo riscontrato, si prega di segnalarlo agli
sviluppatori.

Revisione dei file prodotti da po4a-gettextize
Qualsiasi file prodotto da po4a-gettextize dovrebbe essere rivisto manualmente, anche quando lo script
viene terminato correttamente. Si dovrebbe scorrere il file PO, assicurandosi che msgid e msgstr
corrispondano effettivamente. Non è ancora necessario assicurarsi che la traduzione sia perfettamente
corretta, poiché tutte le voci sono comunque contrassegnate come traduzioni fuzzy. Bisogna solo
verificare la presenza di evidenti problemi di corrispondenza poiché le traduzioni con corrispondenza
errata verranno scaricate nei passaggi successivi mentre (è probabile) si desideri salvarle.

Fortunatamente, questo passaggio non richiede la padronanza delle lingue di destinazione poiché si
desidera solo riconoscere elementi simili in ogni msgid e nel corrispondente msgstr. In quanto
madrelingua francese, inglese e un po' di tedesco, l'autore di questa guida può farlo almeno per tutte le
lingue europee, mentre non può dire una parola della maggior parte di queste lingue. A volte riesco a
rilevare problemi di corrispondenza nelle lingue non latine osservando la lunghezza delle stringhe, le
strutture delle frasi (la quantità di punti di interrogazione corrisponde?) e altri indizi, ma preferisco
che qualcun altro riveda la traduzione di quelle lingue.

Se si rileva una mancata corrispondenza, modificare i file originale e di traduzione come se
po4a-gettextize segnalasse un errore e riprovare. Una volta che si ha un file PO decente per la
traduzione precedente, eseguire il backup fino a quando po4a non funziona correttamente.

Eseguire po4a per la prima volta
Il modo più semplice per configurare po4a è scrivere un file di configurazione po4a.conf e utilizzare il
programma integrato po4a (po4a-updatepo e po4a-translate sono deprecati). Si prega di controllare la
sezione "FILE DI CONFIGURAZIONE" nella documentazione po4a(1) per maggiori dettagli.

Quando po4a viene eseguito per la prima volta, la versione corrente dei documenti master verrà usata per
aggiornare i file PO contenenti le vecchie traduzioni salvate tramite gettext-izzazione. Ciò può
richiedere molto tempo, perché molti dei msgid prodotti dalla gettext-izzazione non corrispondono
esattamente agli elementi del file POT creato dai file master recenti. Ciò costringe gettext a cercare
quello più simile utilizzando un algoritmo computazionalmente pesante di similitudine di stringa. Ad
esempio, la prima esecuzione della traduzione francese della documentazione Perl (file PO da 5,5 MB) ha
richiesto circa 48 ore (sì, due giorni), mentre le successive solo pochi secondi.

Spostare la traduzione in produzione
Dopo questa prima esecuzione, i file PO sono pronti per essere esaminati dai traduttori. Tutte le voci
sono state contrassegnate come fuzzy nel file PO dalla po4a-gettext-izzazione, imponendo così la loro
attenta revisione prima dell'uso. I traduttori devono: esaminare ogni voce per verificare che la
traduzione salvata corrisponda effettivamente al testo originale corrente, aggiornare la traduzione ove
necessario, rimuovere i marcatori fuzzy.

Una volta rimossi un numero sufficiente di marcatori fuzzy, po4a inizierà a generare i file di traduzione
su disco e sarà il momento di spostare il flusso di lavoro di traduzione alla produzione. Alcuni progetti
trovano utile affidarsi a weblate per coordinare traduttori e manutentori, ma questo va oltre lo scopo di
po4a.

VEDERE ANCHE

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

AUTORI

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <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-2023 by SPI, inc.

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

perl v5.38.2                                       2024-08-28                              PO4A-GETTEXTIZE.1P(1)