PO4A

Section: Strumenti Po4a (1p)
Updated: 2017-04-07
Index Return to Main Contents
 

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.

 documento master --> file PO --> traduzioni

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 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:

    <lingua>:<percorso del file PO per questa lingua>

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

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>)* \
                  (add_<ling>:<modificatore>*<percorso_addendum>)*

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.
!
addendum_path is discarded, it is not loaded and will not be loaded by any further addendum specification.

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 accepts options that will be passed to the module. These options are module specific and are specified with the -o switch.

If you need a specific option for one of the document you want to translate, you can also specify it in the configuration file. Options are introduced by the opt keyword. The argument of the opt keyword must be quoted with double quotes if it contains a space (e.g. if you specify multiple options, or an option with an argument). You can also specify options that will only apply to a specific language by using the opt_lang keyword.

Here is an example:
 [type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
            opt:``-k 75'' opt_it:``-L UTF-8'' opt_fr:-v

Arguments may contain spaces if you use single quotes or escaped double quotes:
 [po4a_alias:man] man opt:``-o \''mdoc=NAME,SEE ALSO\`` -k 20''

If you want to specify the same options for many documents, you may want to use an alias (see the Specifying aliases section below).

You can also set options for all the documents specified in the configuration file:
 [options] opt:``...'' opt_fr:``...''  

Specificare gli alias

If you must specify the same options for multiple files, you may be interested in defining a module alias. This can be done this way:

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

This defines a module alias named test, based on the man module, with the -k 21 applied to all the languages and with -o debug=splitargs applied to the Spanish translation.

This module alias can then be use like a regular module:

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

Note that you can specify additional options on a per file basis.  

Modalità split

The split mode is used when $master is used in the [po4a_paths] line.

When the split mode is used, a temporary big POT and temporary big POs are used. This permits to share the translations between all the POs.

If two POs have different translations for the same string, po4a will mark this string as fuzzy and will submit both translations in all the POs which contain this string. Then, when a translator updates the translation and removes the fuzzy tag in one PO, the translation of this string will be updated in every POs automatically.

If there are name conflicts because several files have the same filename, the name of the master file can be specified by adding a "master:file="name option:

 [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:

If the POT file already exists, it is regenerated if a master document or the configuration file is more recent. The POT file is also written in a temporary document and po4a verifies that the changes are really needed.

Also, a translation is regenerated only if its master document, the PO file, one of its addenda or the configuration file is more recent. To avoid trying to regenerate translations which do not pass the threshold test (see --keep), a file with the .po4a-stamp extension can be created (see --stamp).

If a master document includes files, you should use the --force flag because the modification time of these included files are not taken into account.

The PO files are always re-generated based on the POT with msgmerge -U.

--stamp
Tells po4a to create stamp files when a translation is not generated because it does not reach the threshold. These stamp files are named according to the expected translated document, with the .po4a-stamp extension.

Note: This only activates the creation of the .po4a-stamp files. The stamp files are always used if they exist, and they are removed with --rm-translations or when the file is finally translated.

--no-translations
Do not generate the translated documents, only update the POT and PO files.
--no-update
Do not change the POT and PO files, only the translation may be updated.
--rm-translations
Remove the translated files (implies --no-translations).
--no-backups
This flag does nothing since 0.41, and may be removed in later releases.
--rm-backups
This flag does nothing since 0.41, and may be removed in later releases.
--translate-only translated-file
Translate only the specified file. It may be useful to speed up processing if a configuration file contains a lot of files. Note that this option does not update PO and POT files. This option can be used multiple times.
--variable var=value
Define a variable that will be expanded in the po4a configuration file. Every occurrence of $(var) will be replaced by value. This option can be used multiple times.
--srcdir SRCDIR
Set the base directory for all input documents specified in the po4a configuration file.
--destdir DESTDIR
Set the base directory for all the output documents specified in the po4a configuration file.
 

OPTIONS WHICH MODIFY POT HEADER

--porefs type[,wrap|nowrap]
Specify the reference format. Argument type can be one of never to not produce any reference, file to only specify the file without the line number, counter to replace line number by an increasing counter, and full to include complete references (default: full).

Argument can be followed by a comma and either wrap or nowrap keyword. References are written by default on a single line. The wrap option wraps references on several lines, to mimic gettext tools (xgettext and msgmerge). This option will become the default in a future release, because it is more sensible. The nowrap option is available so that users who want to keep the old behavior can do so.

--msgid-bugs-address email@address
Set the report address for msgid bugs. By default, the created POT files have no Report-Msgid-Bugs-To fields.
--copyright-holder string
Set the copyright holder in the POT header. The default value is ``Free Software Foundation, Inc.''
--package-name string
Set the package name for the POT header. The default is ``PACKAGE''.
--package-version string
Set the package version for the POT header. The default is ``VERSION''.
 

OPTIONS TO MODIFY PO FILES

--msgmerge-opt options
Extra options for msgmerge(1).

Note: $lang will be extended to the current language.

--no-previous
This option removes --previous from the options passed to msgmerge. This permits to support versions of gettext earlier than 0.16.
--previous
This option adds --previous to the options passed to msgmerge. It requires gettext 0.16 or later, and is activated by default.
 

ESEMPIO

Let's assume you maintain a program named foo which has a man page man/foo.1 which naturally is maintained in English only. Now you as the upstream or downstream maintainer want to create and maintain the translation. First you need to create the POT file necessary to send to translators using po4a-gettextize(1).

So for our case we would call

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

You would then send this file to the appropriate language lists or offer it for download somewhere on your website.

Now let's assume you received three translations before your next release: de.po (including an addendum de.add), sv.po and pt.po. Since you don't want to change your Makefile(s) whenever a new translation arrives you can use po4a with an appropriate configuration file in your Makefile. Let's call it po4a.cfg. In our example it would look like the following:

 [directory_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 this example we assume that your generated man pages (and all PO and addenda files) should be stored in man/translated/$lang/ (respectively in man/po4a/po/ and man/po4a/add_$lang/) below the current directory. In our example the man/po4a/po/ directory would include de.po, pt.po and sv.po, and the man/po4a/add_de/ directory would include de.add.

Note the use of the modifier ? as only the German translation (de.po) is accompanied by an addendum.

To actually build the translated man pages you would then (once!) add the following line in the build target of the appropriate Makefile:

        po4a po4a.cfg

Once this is set up you don't need to touch the Makefile when a new translation arrives, i.e. if the French team sends you fr.po and fr.add then you simply drop them respectively in man/po4a/po/ and man/po4a/add_fr/ and the next time the programm is build the French translation is automatically build as well in man/translated/fr/.

Note that you still need an appropriate target to install localized manual pages with English ones.

Finally if you do not store generated files into your version control system, you will need a line in your clean target as well:
        -rm -rf man/translated  

DIFETTI E MANCANZE

Contiene codice duplicato dai programmi po4a-*.

Ogni patch è bene accetta ;)  

VEDERE ANCHE

po4a-build(1), po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a-build.conf(5), 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).


 

Index

NOME
SINTASSI
DESCRIZIONE
Sommario
DESCRIZIONE
INTRODUZIONE
SINTASSI DEL FILE DI CONFIGURATIONE
OPZIONI
ESEMPIO
DIFETTI E MANCANZE
VEDERE ANCHE
AUTORI
COPYRIGHT E LICENZA
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
OPTIONS WHICH MODIFY POT HEADER
OPTIONS TO MODIFY PO FILES
ESEMPIO
DIFETTI E MANCANZE
VEDERE ANCHE
AUTORI
TRADUZIONE
COPYRIGHT E LICENZA

This document was created by using the manual pages.
Time: 22:20:48 GMT, April 07, 2017