Ubuntu Manpage: po4a - aggiorna i file PO e i documenti tradotti in un colpo solo

NOME

       po4a - aggiorna i file PO e i documenti tradotti in un colpo solo

SINTASSI

       po4a [opzioni] file_config

DESCRIZIONE

       Lo scopo del progetto po4a (PO for anything - PO per tutto) è di facilitare la traduzione
       e, cosa ancor più interessante, la manutenzione delle traduzioni usando gettext e i
       relativi strumenti in campi in cui il loro uso non era programmato, come la
       documentazione.

       Il programma po4a è utile se si vuole evitare di chiamare po4a-gettextize(1),
       po4a-updatepo(1), e po4a-translate(1) in Makefile complessi quando si hanno più file da
       tradurre, diversi formati, o serve specificare diverse opzioni per diversi documenti.

Sommario

       Questo documento è organizzato come segue:

   DESCRIZIONE
   INTRODUZIONE
   SINTASSI DEL FILE DI CONFIGURATIONE
       Specificare l'elenco delle lingue

       Specificare i file di lavoro dei traduttori

       Autorilevamento dei percorsi e delle lingue

       Specificare i documenti da tradurre

       Specificare le opzioni per i moduli

       Specificare gli alias

       Modalità split

   OPZIONI
   ESEMPIO
   DIFETTI E MANCANZE
   VEDERE ANCHE
   AUTORI
   COPYRIGHT E LICENZA

INTRODUZIONE

       Il programma po4a si occupa di aggiornare sia i file PO (per mantenerli sincronizzati con
       i documenti originali) sia i documenti tradotti (per mantenerli sincronizzati con i file
       PO). È stato creato principalmente per permettere di usare po4a più facilmente, senza
       dover ricordare le opzioni da riga di comando.

       Ma questa non è la sua unica ragion d'essere; il programma rende inoltre possibile
       combinare documenti in formati diversi in un unico file POT, consentendo di averne uno
       solo per progetto.

       Gli stessi risultati si possono ottenere combinando gli altri strumenti della suite po4a
       (ad es. tramite dei Makefile), ma solo per mezzo di un notevole sforzo, che si rivela
       snervante se ripetuto per ogni progetto che usa po4a.

       Il flusso dati può essere riassunto come segue. Ogni cambiamento al documento master verrà
       riflesso nei file PO, e tutti i cambiamenti ai file PO (sia manuali che causati dai passi
       precedenti) verranno riflessi nei documenti tradotti.

       Caso normale senza specificare pot_in:

        <- file sorgenti->|<---- risultati della compilazione ----->

        addendum ----------------------------------+
                                                   |
        documento master--+---------------------+  |
                          V                     +--+--> traduzioni
        vecchi file PO ---+-> file PO aggiornati+
             ^                      |
             |                      V
             +<.....................+
           (i file PO aggiornati vengono copiati
            manualmente sulla sorgente del prossimo
            rilascio mentre si aggiornano manualmente
            i contenuti della traduzione)

       Caso speciale con la specifica di pot_in:

        <- file sorgenti->|<---- risultati della compilazione ------->

        documento master -+--------------------------+
                          :                          |
        programma         :    documento             |
        di filtro ========X..> master                |
        esterno                filtrato              |
                               |                     |
                               V                     +--> traduzioni
        vecchi file PO --------+-> file PO aggiornati+
             ^                           |
             |                           V
             +<..........................+
           (i file PO aggiornati vengono copiati
            manualmente sulla sorgente del prossimo
            rilascio mentre si aggiornano manualmente
            i contenuti della traduzione)
       Il flusso dati non può essere invertito in questo strumento, e i cambiamenti
       nelle traduzioni vengono sovrascritti dal contenuto dei file PO. Difatti,
       questo strumento non può essere usato per convertire traduzioni esistenti al
       sistema di po4a. Per questo lavoro, fare riferimento a
       L<po4a-gettextize(1)>.

SINTASSI DEL FILE DI CONFIGURATIONE

L'argomento (obbligatorio) è il percorso del file di configurazione da usarei. La sintassi
è volutamente semplice e simile a quella dei file di configurazione usati da intl-tools.

Il carattere "#" inizia un commento, che si estende fino alla fine della riga. Una riga
che termina con un carattere di escape continua su quella successiva. Ogni riga non vuota
deve iniziare con un comando racchiuso tra "[]", seguito dai suoi argomenti. So che detto
così sembra difficile, ma in realtà non lo è... o almeno spero ;)

Specificare l'elenco delle lingue
Nota: si raccomanda l'uso di [po_directory] invece che [po4a_langs] e [po4a_paths].
Vedere sezione Autorilevamento dei percorsi e delle lingue più avanti.

Questo è un comando facoltativo che può semplificare l'intero file di configurazione e
aumentarne la scalabilità. Occorre solo specificare un elenco delle lingue in cui tradurre
i documenti, ad esempio:

[po4a_langs] fr it

Questo fa sì che, nel resto del file di configurazione, $lang verrà espanso per indicare
tutte le lingue specificate.

Specificare i file di lavoro dei traduttori
Nota: si raccomanda l'uso di [po_directory] invece che [po4a_langs] e [po4a_paths].
Vedere sezione Autorilevamento dei percorsi e delle lingue più avanti.

Per prima cosa si deve specificare la posizione dei file usati dai traduttori durante il
loro lavoro. È sufficiente scrivere una riga del genere:

[po4a_paths] doc/l10n/project.doc.pot \
fr:doc/l10n/fr.po it:doc/l10n/it.po

Il comando in questo caso è [po4a_paths]. Il primo argomento è il percorso del file POT,
mentre tutti gli argomenti successivi sono in questa semplice forma:

Se è stato definito un elenco delle lingue, si può riscrivere il comando come:

[po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po

È possibile anche usare $master per fare riferimento al nomefile del documento. In questo
caso, po4a userà una modalità divisa: verranno creati un POT e un PO (per ogni lingua) per
ogni documento specificato nel file di configurazione di po4a. Consultare la sezione
Modalità split.

[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

Autorilevamento dei percorsi e delle lingue
Un altro comando può essere usato per specificare il nome di una cartella dove sono
posizionati i file PO e POT. Se usato, po4a rileverà il file POT come unico file *.pot
dalla cartella specificata. po4a userà anche l'elenco di file *.po per definire l'elenco
delle lingue (togliendo le estensioni). Queste lingue verranno usate per la sostituzione
della variabile $lang nel resto del file di configurazione.

Questo comando non dovrebbe essere usato assieme ai comandi [po4a_langs] o [po4a_paths].

Quando si usa questo comando, bisogna creare un file POT vuoto alla prima esecuzione di
po4a per fornirgli il nome del file POT.

[cartella_po] po4a/po/

Specificare i documenti da tradurre
Ora si devono soltanto indicare i documenti che vanno tradotti, il loro formato e il
percorso delle traduzioni. Il tutto può essere specificato in questo modo:

[type: sgml] doc/my_stuff.sgml it:doc/it/mia_roba.sgml \
de:doc/de/mein_kram.sgml
[type: pod] script it:doc/it/script.1 de:doc/de/script.1 \
add_it:doc/l10n/script.it.add
[type: docbook] doc/script.xml it:doc/it/script.xml \
de:doc/de/script.xml \
pot_in:doc/script.filtered.xml

L'esempio dovrebbe aver chiarito ogni dubbio. Si noti che, nel secondo caso, il file
doc/l10n/script.it.add è un addendum da apporre alla versione italiana del documento. Per
maggiori informazioni riguardo agli addenda, fare riferimento a po4a(7).

In maniera più formale, il formato è:

[type: <formato>] <doc_master> (<ling>:<doc_localizzato>)* \
(pot_in:<doc_master_filtrato>)? \
(add_<ling>:<modificatore>*<percorso_addendum>)*

Se viene specificato pot_in, viene usato il doc_master_filtrato per creare il file POT
invece di master_doc. Questa caratteristica permette all'utente di creare modi flessibili
per evitare contenuti che non dovrebbero venire inclusi nei file PO. Strumenti quali
preprocessori C (cpp) o utilità di trasformazione XSL (per es. xsltproc) possono venire
usati per creare programmi filtro esterni da chiamare prima dell'esecuzione di po4a.

Se non c'è un modificatore, addendum_path è il percorso ad un addendum. I modificatori
sono

? Include addendum_path se questo file esiste, altrimenti non fa nulla.

@ addendum_path non è un un addendum normale ma un file contenente una lista di addendum,
uno per riga. Ogni addendum può essere preceduto da modificatori.

! percorso_addendum viene scartato, non viene caricato e non verrà caricato da
nessun'altra successiva specifica di addendum.

Se è stato definito un elenco delle lingue, si può riscrivere il comando come:

[type: pod] script $lang:doc/$lang/script.1 \
add_it:doc/l10n/script.it.add

Se tutte le lingue usano degli addenda con nomi simili, si può scrivere invece:

[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add

Specificare le opzioni per i moduli
po4a accetta opzioni che verranno passate al modulo. Queste opzioni sono specifiche del
modulo e vengono specificate con l'opzione -o.

Se serve una opzione specifica per uno dei documenti che si desidera tradurre, si può
anche specificarlo nel file di configurazione. Le opzioni vengono inserite dalla parola
chiave opt. L'argomento della parola chiave opt deve essere virgolettato se contiene uno o
più spazi (per es. se si specifica più opzioni, o un'opzione con un argomento). È anche
possibile specificare opzioni che verranno applicate solo su una specifica lingua usando
la parola chiave opt_lang.

Ecco un esempio:
[type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v

Gli argomenti possono contenere degli spazi se si usano gli apici o le virgolette
precedute dal carattere backslash:
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"

Se si vuole specificare le stesse opzioni per molti documenti, si può voler usare un alias
(consultare la sezione Specificare alias sottostante).

È anche possibile impostare opzioni per tutti i documenti specificati nel file di
configurazione:
[opzioni] opt:"..." opt_fr:"..."

Specificare gli alias
Se si deve specificare le stesse opzioni per più file, si potrebbe essere interessati a
definire un alias di modulo. Questo può essere effettuato in questo modo:

[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"

Questo definisce un alias di modulo di nome test, basato sul modulo man, con -k 21
applicata a tutte le lingue e con -o debug=splitargs applicata alla traduzione in
spagnolo.

Questo alias di modulo può essere usato come un normale modulo:

[type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v

Si noti che si possono specificare opzioni aggiuntive per ogni file.

Modalità split
La modalità split viene usata se $master viene usato nella riga [po4a_paths].

Quando la modalità split viene usata, vengono usati un grande file temporaneo POT e grandi
file temporanei PO. Ciò permette di condividere le traduzioni tra tutti i PO.

Se due PO hanno traduzioni diverse per la stessa stringa, po4a marcherà questa stringa
come fuzzy e inserirà entrambe le traduzioni in tutti i file PO contenenti questa stringa.
Poi, quando un traduttore aggiornerà la traduzione e rimuoverà la marcatura fuzzy in un
file PO, la traduzione di questa stringa verrà aggiornata in ogni file PO automaticamente.

Se ci sono conflitti di nomi a causa del fatto che i diversi file hanno lo stesso
nomefile, il nome del file master può essere specificato aggiungendo l'opzione
"master:file="nome:

[po4a_langs] de fr ja
[po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
[type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
[type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

OPZIONI

-k, --keep
Minima percentuale di traduzione richiesta affinché il file generato sia conservato e
scritto su disco. Il valore predefinito è 80, vale a dire che una traduzione viene
accettata solo se è completa almeno per l'80%.

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

-M, --master-charset
Set di caratteri dei file contenenti il documento da tradurre. Tutti i documenti
originali devono usare la stessa codifica, almeno per ora: stiamo lavorando per
rimuovere questa limitazione.

-L, --localized-charset
Set di caratteri dei file contenenti il documento tradotto. Tutti i documenti tradotti
useranno la stessa codifica, almeno per ora: stiamo lavorando per rimuovere questa
limitazione.

-A, --addendum-charset
Set di caratteri degli addenda. Tutti gli addenda devono usare la stessa codifica.

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

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

-q, --quiet
Rende il programma meno prolisso.

-d, --debug
Mostra delle informazioni di debug

-o, --option
Opzioni extra da passare al plugin di formato. Specifica ogni opzione nel formato
'nome=valore'. Vedere la documentazione per ogni plugin per ulteriori informazione
sulle opzioni valide e sul loro significato.

-f, --force
Genera sempre i file POT e PO, anche se po4a non lo considera necessario.

Il comportamento predefinito (quando non è specificato --force) è il seguente:

Se il file POT esiste già, viene rigenerato se un documento master o il file di
configurazione sono più recenti. Il file POT viene scritto anche in un documento
temporaneo e po4a verifica che i cambiamenti siano veramente necessari.

Inoltre, una traduzione viene rigenerata solo se il suo documento master, il file
PO, uno dei suoi addendum o il file di configurazione sono più recenti. Per
evitare di provare a rigenerare le traduzioni che non passano il test di soglia
(vedere --keep), un file con estensione .po4a-stamp può venir creato (vedere
--stamp).

Se un documento master include dei file, si dovrebbe usare la flag --force perché il
tempo di modifica di questi file inclusi non sono tenuti in considerazione.

I file PO vengono sempre rigenerati in base al POT con msgmerge -U.

--stamp
Dice a po4a di creare dei file stamp quando una traduzione non viene generata perché
essa non raggiunge la soglia. A questi file stamp viene assegnato un nome in accordo
con il nome previsto del documento tradotto, ed applicata estensione .po4a-stamp.

Nota: ciò attiva solo la creazione dei file .po4a-stamp. I file stamp vengono sempre
usati se esistono, e vengono rimossi con l'uso di --rm-translations o quando il file
viene infine tradotto.

--no-translations
Non generare i documenti tradotti, aggiorna solo i file POT e PO.

--no-update
Non cambiare i file POT e PO, solo la traduzione può essere aggiornata.

--keep-translations
Mantiene i file di traduzione esistenti anche se la traduzione non incontra la soglia
specificata da --keep. Questa opzione non crea nuovi file di traduzione con poco
contenuto, ma salverà le traduzioni esistenti che decadranno a causa dei cambiamenti
ai file master.

ATTENZIONE: questo flag cambia il comportamento di po4a in modo piuttosto radicale: i
file tradotti non verranno aggiornati per nulla fino a quando la traduzione non
migliorerà. Usare questo flag se si preferisce inviare una documentazione tradotta non
aggiornata piuttosto che spedire solo una documentazione accurata non tradotta.

--rm-translations
Rimuovi i file tradotti (implica --no-translations).

--no-backups
Questo flag non fa nulla dalla versione 0.41, e potrebbe venir rimosso dalle prossime
versioni.

--rm-backups
Questo flag non fa nulla dalla versione 0.41, e potrebbe venir rimosso dalle prossime
versioni.

--translate-only file-tradotto
Traduce solo il file specificato. Può essere utile per velocizzare il processo se un
file di configurazione contiene molti file. Si noti che questa opzione non aggiorna i
file PO e POT. Questa opzione può essere usata più volte.

--variable var=valore
Definisce una variabile che verrà espansa nel file di configurazione po4a. Ogni
occorrenza di $(var) verrà rimpiazzata da value. Questa opzione può essere usata più
volte.

--srcdir SRCDIR
Imposta la cartella di base per tutti i documenti in ingresso specificati nel file di
configurazione po4a.

--destdir DESTDIR
Imposta la cartella di base per tutti i documenti in uscita specificati nel file di
configurazione po4a.

OPZIONI CHE MODIFICANO L'INTESTAZIONE POT
--porefs type[,wrap|nowrap]
Specifica il formato di riferimento. L'argomento type può essere un valore qualsiasi
tra: never per non produrre nessun riferimento, file per specificare solo il file
senza il numero di riga, counter per rimpiazzare il numero di riga con un contatore
incrementale, e full per includere il riferimento completo (valore predefinito: full).

L'argomento può essere seguito da una virgola e da una delle due parole chiave wrap o
nowrap. I riferimenti, come impostazione predefinita, vengono scritti su una singola
riga. L'opzione wrap manda a capo i riferimento su più righe, per emulare il
comportamento degli strumenti di gettext (xgettext e msgmerge). Questa opzione
diventerà predefinita in una versione futura, perchè è il comportamento più logico.
L'opzione nowrap è disponibile per permettere agli utenti che lo desiderassero, di
mantenere il vecchio comportamento.

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

OPZIONI PER MODIFICARE I FILE PO
--msgmerge-opt opzioni
Opzioni extra per msgmerge(1).

Nota: $lang verrà estesa alla lingua corrente.

--no-previous
Questa opzione rimuove --previous dalle opzioni passate a msgmerge. Ciò permette di
supportare versioni di gettext precedenti alla 0.16.

--previous
Questa opzione aggiunge --previous alle opzioni passate a msgmerge. Richiede gettext
0.16 o successive, ed è attivata come impostazione predefinita.

ESEMPIO
Poniamo di essere il responsabile di un programma di nome foo il quale è dotato di una
pagina man man/foo.1 che naturalmente viene mantenuta solo in inglese. Ora si vorrebbe
creare e mantenere anche le traduzioni. Per prima cosa è necessario creare il file POT da
inviare necessariamente ai traduttori, usando po4a-gettextize(1).

Perciò nel nostro caso eseguiremmo

cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Poi invieremmo questo file alle mailing list dei gruppi linguistici appropriati o lo
renderemmo disponibile per scaricamento da qualche parte sul sito web del progetto.

Poniamo ora di aver ricevuto tre traduzioni prima del rilascio della prossima versione:
de.po (incluso un file addendum de.add), sv.po e pt.po. Dato che non si vuole cambiare i
propri Makefile ogni qualvolta arrivi una nuova traduzione si può usare po4a con un file
di configurazione appropriato nel proprio Makefile. Chiamiamolo po4a.cfg. Nel nostro
esempio questo somiglierebbe al seguente:

[cartella_po] man/po4a/po/

[type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

In questo esempio si presume che le pagine man generate (e tutti il file po e addendum)
siano stati posti in man/translated/$lang/ (rispettivamente in man/po4a/po/ e
man/po4a/add_$lang/) sotto la cartella corrente. Nel nostro esempio la cartella
man/po4a/po/ includerà de.po, pt.po e sv.po, e la cartella man/po4a/add_de/ includerà
de.add.

Si noti l'utilizzo del modificatore ? in quanto solo la traduzione tedesca (de.po) è
accompagnata da un addendum.

Per creare realmente le pagine man tradotte aggiungere (una sola volta!) la seguente riga
nel target build del Makefile appropriato:

po4a po4a.cfg

Una volta impostato tutto questo non è necessario toccare il Makefile quando arriva una
nuova traduzione, cioè se la squadra francese vi spedisce fr.po e fr.add basta
semplicemente metterli rispettivamente in man/po4a/po/ e man/po4a/add_fr/ e la prossima
volta che il programma verrà compilato la traduzione francese verrà automaticamente
aggiornata in man/translated/fr/.

Si noti che è necessario un obiettivo appropriato per installare le pagine man localizzate
con quelle inglesi.

Infine, se non si memorizza i file generati nel proprio sistema di versionamento, sarà
necessaria anche una riga nell'obiettivo clean:
-rm -rf man/translated

DIFETTI E MANCANZE

       •   Contiene codice duplicato dai programmi po4a-*.

       Ogni patch è bene accetta ;)

VEDERE ANCHE

       po4a-gettextize(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@libero.it>

COPYRIGHT E LICENZA

       Copyright © 2002-2012 by SPI, inc.

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