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
           un'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-2022 by SPI, inc.

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