Guida di avvio rapido¶

Supponiamo di mantenere un programma chiamato foo che ha una pagina man man/foo.1 scritta in inglese (il linguaggio ponte nella maggior parte dei progetti open-source, ma po4a può essere usato da o verso qualsiasi linguaggio). Qualche tempo fa, qualcuno ha fornito una traduzione manuale in tedesco chiamata man/foo.de.1 ed è scomparso. Questo è un problema perché hai appena ricevuto una segnalazione di bug che dice che la tua documentazione contiene informazioni gravemente fuorvianti che devono essere corrette in tutte le lingue, ma non parli tedesco quindi puoi solo modificare l'originale, non la traduzione. Ora, un altro collaboratore vuole contribuire con una traduzione in giapponese, un'altra lingua che non si mastica.

È ora di convertire la documentazione a po4a per risolvere la manutenzione da incubo della documentazione. Si vuole aggiornare il documento quando serve, facilitare il lavoro dei colleghi traduttori e assicurare che gli utenti non vedano mai documentazioni obsolete e quindi fuorviante.

La conversione comprende due passaggi: configurare l'infrastruttura po4a e convertire la precedente traduzione tedesca per salvare il lavoro precedente. Quest'ultima parte viene eseguita utilizzando po4a-gettextize, come segue. Come dettagliato nella documentazione di po4a-gettextize(1), questo processo raramente è anche completamente automatico, ma una volta terminato, il file de.po contenente la traduzione tedesca può essere integrato nel flusso di lavoro di po4a.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Configuriamo ora po4a. Con la disposizione file appropriata, la configurazione potrebbe assomigliare ad un semplice file come questo:

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

Specifica che tutti i file PO (contenenti il lavoro dei traduttori) sono la cartella man/po4a/ e che si ha un solo file master, man/foo.1. Se si avesse più file master, si avrebbero più righe simili alla seconda. Ciascuna di queste righe specifica anche dove scrivere i file di traduzione corrispondenti. Qui, la traduzione tedesca di man/foo.1 è in man/translated/foo.de.1.

L'ultima cosa di cui abbiamo bisogno per completare la configurazione di po4a è un file POT contenente il materiale del modello che dovrebbe essere usato per iniziare una nuova traduzione. Basta creare un file vuoto con l'estensione .pot nella po_directory specificata (ad es. man/po4a/foo.pot) e po4a lo riempirà con il contenuto previsto.

Ecco un riassunto dei file in questa impostazione:

  ├── man/
  │   ├── foo.1        <- La pagina man originale, in inglese
  │   ├── po4a/
  │   │   ├── de.po    <- La traduzione PO in tedesco, dalla gettext-izzazione
  │   │   └── foo.pot  <- Il modello POT per future traduzioni (all'inizio vuoto)
  │   └── translated/  <- La cartella dove verranno create le traduzioni
  └── po4a.cfg         <- Il file di configurazione

Una volta impostato, l'esecuzione di po4a analizzerà la documentazione, aggiornerà il file modello POT, lo utilizzerà per aggiornare i file di traduzione PO e li utilizzerà per aggiornare i file di traduzione della documentazione. Tutto in un comando:

        po4a --verbose po4a.cfg

Fatto. po4a è ora completamente configurato. Dopo aver corretto l'errore in man/foo.1, il paragrafo colpevole nella traduzione tedesca sarà sostituito dal testo corretto in inglese. Mescolare le lingue non è ottimale, ma è l'unico modo per rimuovere errori nelle traduzioni (in lingue) che non si comprendono e garantire che il contenuto presentato agli utenti non sia mai forviante. Anche l'aggiornamento della traduzione tedesca è molto più semplice nel file PO corrispondente, quindi il disguido linguistico potrebbe non durare a lungo. Infine, quando un traduttore giapponese volesse contribuire con una nuova traduzione, questi dovrebbe rinominare foo.pot in jp.po e completare la traduzione. Una volta ottenuto questo file, basterà metterlo in man/po4a/po/. Una pagina tradotta apparirà come man/translated/foo.jp.1 quando si eseguirà nuovamente po4a (sempre che il contenuto tradotto sia sufficientemente completo).

Ozioni che modificano l'intestazione POT¶

--porefs tipo

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

--wrap-po no|newlines|numero (predefinito: 76)

Specifica come il file po deve essere mandato a capo. Consente di scegliere tra file con righe mandate capo ben formattate e quindi ben leggibili ma che potrebbero portare a conflitti in git o file che sono più facili da gestire automaticamente, ma più difficili da leggere per le persone.

Storicamente, la suite gettext riformattava i file po alla 77a colonna per questioni estetiche. Questa opzione specifica il comportamento di po4a. Se impostato su un valore numerico, po4a manderà a capo il file po a questo numero di colonna e dopo i caratteri di a capo nel testo. Se impostato su newlines, po4a dividerà msgstr e msgstr solo dopo i caratteri di a capo nel testo. Se impostato su no, po4a non metterà a capo nel testo del file po. L'andare a capo nei commenti di riferimento è controllato dagli strumenti gettext che vengono usati internamente.

Si noti che questa opzione non ha alcun impatto sul modo in cui msgstr e msgstr vanno a capo, cioè su come i caratteri di a capo vengono aggiunti al contenuto di queste stringhe.

--master-language

La lingua dei file contenenti il documento da tradurre. Tutti i file devono usare la stessa lingua.

--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 che modificano 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ò è necessario per 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.

Trovare i file POT e PO¶

La soluzione più semplice è indicare il percorso ai file POT e PO nel modo seguente:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Questo specifica prima il percorso verso il file POT, e poi i percorsi ai file PO tedesco e francese.

La stessa informazione può essere scritta come di seguito per ridurre il rischio di errori di copia/incolla:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

La componente $lang viene automaticamente espansa usando l'elenco lingue fornito, riducendo il rischio di errori di copia/incolla quando una nuova lingua viene aggiunta.

Si possono compattare ulteriormente le stesse informazioni fornendo solamente il percorso per la cartella contenente il progetto di traduzione, come di seguito.

 [po_directory] man/po/

La cartella fornita deve contenere un insieme di file PO, ognuno con nome XX.po dove "XX" è il codice ISO 639-1 della lingua usata in questo file. La cartella deve anche contenere un singolo file POT, con estensione file ".pot" . Nella prima esecuzione, quest'ultimo può essere vuoto ma deve esistere (po4a non può indovinare il nome da usare davanti all'estensione).

Si noti che bisogna scegliere solo uno tra "po_directory" e "po4a_paths". Il primo ("po_directory") è più compatto, inoltre riduce il rischio degli errori di copia/incolla, ma forza ad usare la struttura progetto e i nomi file previsti. Il secondo ("po4a_paths"), è più esplicito, probabilmente più leggibile, e suggerito quando si imposta il primo progetto con po4a.

File PO centralizzati o separati?

Per impostazione predefinita, po4a produce un singolo file PO per lingua obiettivo, con l'intero contenuto del progetto di traduzione. Come il progetto cresce, la dimensione di questi file può diventare problematica. Quando si usa weblate, è possibile specificare priorità per ogni segmento di traduzione (cioè msgid) in modo tale da far tradurre i più importanti per primi. Comunque, alcune squadre di traduzione preferiscono dividere il contenuto in più file.

Per avere un file PO per file master, basta semplicemente usare la stringa $master nel nome dei file PO nella riga "[po4a_paths]", come di seguito.

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

Con questa riga, po4a produrrà file POT e PO separati per ogni documento da tradurre. Ad esempio, se si hanno 3 documenti e 5 lingue, ciò porterà ad avere 3 file POT e 15 file PO. Questi file saranno denominati come specificato nel modello "po4a_paths", con $master sostituito con il nome di base di ciascun documento da tradurre. In caso di conflitto di nomi, è possibile specificare il file POT da utilizzare come segue, con il parametro "pot=".

Questa funzione può essere utilizzata anche per raggruppare più file tradotti nello stesso file POT. L'esempio seguente produce solo 2 file POT: l10n/po/foo.pot (contenente il materiale di foo/gui.xml) e l10n/po/bar.pot (contenente il materiale di entrambi bar/gui.xml e bar/cli.xml).

 [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 pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

In modalità split, po4a crea un compendio temporaneo durante l'aggiornamento PO, per condividere le traduzioni tra tutti i file 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.

Specificare i documenti da tradurre¶

È necessario elencare anche i documenti che devono essere tradotti. Per ogni file master, bisogna specificare l'elaboratore del formato da usare, la posizione del documento tradotto da produrre, e opzionalmente qualche configurazione. Se i nomi dei file dovessero contenere degli spazi, a questi ultimi dovranno essere apposti dei caratteri di escape oppure i nomi interi dovranno essere essere messi tra virgolette. Ecco un esempio:

 [type: sgml] "doc/my stuff.sgml"  "fr:doc/fr/mon truc.sgml"  de:doc/de/mein\ kram.sgml
 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml

Ma ancora, queste righe complesse sono difficili da leggere e da modificare, per es. quando si vuole aggiungere una lingua. È molto più semplice riorganizzare le cose usando il modello $lang come di seguito:

 [type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Specificare le opzioni¶

Ci sono due tipi di opzioni: le opzioni po4a sono valori predefiniti alle opzioni di riga di comando po4a mentre le opzioni di formato vengono usate per cambiare il comportamento dei parser di formato. Con una opzione po4a, si può per esempio specificare nel file di configurazione che il valore predefinito del parametro a riga di comando --keep è 50% invece che 80%. Le opzioni di formato sono documentate nella pagina specifica di ogni modulo di elaborazione, per es. Locale::Po4a::Xml(3pm). Si può per esempio passare nostrip al parser XML per non eliminare gli spazi attorno alle stringhe estratte.

È possibile passare queste opzioni per un file master specifico, o persino per una specifica traduzione di quel file, usando "opt:" e "opt_XX:" per la lingua "XX". Nell'esempio seguente, viene passata l'opzione nostrip al parser XML (per tutte le lingue), mentre la soglia viene ridotta a 0% per la traduzione francese (che significa perciò che sarà sempre mantenuta).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

In ogni caso, questi blocchi di configurazione devono essere posizionati alla fine della riga. La dichiarazione dei file viene prima, poi l'addendum se presente (vedere sotto), e solo poi le opzioni. Il raggruppamento dei blocchi di configurazione non è molto importante, dato che gli elementi sono internamente concatenati come stringhe. Gli esempi seguenti sono tutti equivalenti:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Si noti che le opzioni specifiche della lingua non vengono usate durante la costruzione del file POT. È per esempio impossibile passare nostrip al parser solo quando crea la traduzione francese, perché lo stesso file POT viene usato per aggiornare tutte le lingue. Perciò le sole opzioni che possono essere specifiche per una lingua sono quelle che vengono usate durante la produzione della traduzione, come l'opzione "--keep".

Alias di configurazione

Per passare le stesse opzioni a più file, è meglio definire un alias di tipo come di seguito. Nel prossimo esempio, "--keep 0" viene passata ad ogni traduzione italiana usando il tipo "test", che è un'estensione del tipo "man".

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Si può anche estendere un tipo esistente riutilizzando lo stesso nome per l'alias come di seguito. Ciò non viene interpretato come una definizione erroneamente ricorsiva.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Opzioni predefinite globali

Si può anche usare righe di "[options]" per definire opzioni che devono essere usate per tutti i file, indipendentemente dal loro tipo.

  [options] --keep 20 --option nostrip

Come con le opzioni a riga di comando, si possono abbreviare i parametri passati nel file di configurazione:

  [options] -k 20 -o nostrip

Priorità delle opzioni

Le opzioni di ogni sorgente vengono concatenate, assicurando così che i valori predefiniti possano essere facilmente ridefiniti da opzioni più specifiche. L'ordine è il seguente:

• Le righe "[options]" forniscono i valori predefiniti che possono essere ridefiniti da qualsiasi altra sorgente.
• Vengono poi usati gli alias dei tipi. Le impostazioni specifiche per la lingua sovrascrivono quelle applicabili a tutte le lingue.
• Le impostazioni specifiche ad ogni dato file master sovrascrivono sia quelle predefinite che quelle che provengono dagli alias dei tipi. In questo caso inoltre, le impostazioni specifiche della lingua sovrascrivono quelle globali.
• Infine, i parametri forniti sulla riga di comando di po4a sovrascrivono qualsiasi impostazione proveniente dal file di configurazione.

Esempio

Ecco un esempio che mostra come commentare gli spazi e il virgolettato:

 [po_directory] man/po/
 
 [options] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

Addendum: aggiunta di contenuto extra nella traduzione¶

Se si vuole aggiungere una sezione extra alla traduzione, per esempio per dare credito al lavoro del traduttore, allora è necessario definire un addendum alla riga che difinisce il file master. Fare riferimento alla pagina po4a(7) per ulteriori dettagli sulla sintassi dei file addendum.

 [type: pod] script fr:doc/fr/script.1 \
             add_fr:doc/l10n/script.fr.add

Si può usare anche i modelli di lingua nel modo seguente:

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

Se un file addendum fallisce nell'applicazione, la traduzione viene scartata.

Modificatori per la dichiarazione dell'addendum

I modificatori dell'addendum possono semplificare il file di configurazione nel caso in cui non tutte le lingue forniscano un addendum, o quando l'elenco degli addenda cambia da una lingua all'altra. Il modificatore è un singolo carattere posizionato prima del nome del file.

?

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.

Il seguente include un addendum in ogni lingua, ma solo se questo esiste. Non viene generato nessun errore se l'addendum non esiste.

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

Il seguente include un elenco di addendum per ogni lingua:

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

Filtro delle stringhe tradotte¶

Talvolta si vorrebbe nascondere alcune stringhe dal processo di traduzione. A tale scopo, si può passare un parametro "pot_in" al file master per specificare il nome del file da usare invece del master reale quando si crea il file POT. Ecco un esempio:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Con questa impostazione, le stringhe da tradurre verranno estratte da book-filtered.xml (che deve essere prodotto prima di chiamare po4a) mentre i file tradotti verranno creati da book.xml. Di conseguenza, qualsiasi stringa che fa parte di book.xml ma non di book-filtered.xml non verrà inclusa nei file PO, impedendo ai traduttori di fornire una traduzione per essi. Quindi queste stringhe non verranno modificate durante la produzione dei documenti tradotti. Questo naturalmente riduce il livello di traduzione, quindi si potrebbe aver bisogno dell'opzione "--keep" per assicurarsi che il documento venga prodotto comunque.