PO4A(1)

NAME
po4a - update both the po files and translated documents in one shot

SYNOPSIS
po4a [-dhvV] <config_file>

DESCRIPTION
The po4a (po for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.

The "po4a" program is in charge of updating both the po files (to sync them to the original documents) and the translated documents (to sync them to the po files). The main point is to make the use of po4a easier without having to remember of the command line options.

It also allows you to mix documents having different formats into the same pot file so that you can have only one such file per project.

This behaviour can be mimicked by the other tools of the po4a suite (for example with makefiles), but it is rather difficult to do, and exhausting to redo the same complicated makefiles for each project using po4a.

The dataflow can be summarized as follow. Any changes to the master document will be reflected in the po files, and all changes to the po files (either manual or caused by previous step) will be reflected in translation documents.

 master document --> po files --> translations

The dataflow cannot be inversed in this tool, and changes in translations are overwritten by the content of the po files. As a matter of fact, this tool cannot be used to convert existing translations to the po4a system. For that task, please refer to po4a-gettextize(1).

CONFIGURATION FILE SYNTAX
The (mandatory) argument is the path to the configuration file to use. Its syntax aims at being simple and close to the configuration files used by the intl-tools projects.

Comments in this files are noted by the char '#'. It comments everything until the end of the line. Lines can be continued by escaping the end of line. All non blank lines must begin with a [] command, followed by its arguments. (sound difficult said that way, but it is rather easy, I hope ;)

  Specifying the template languages
This is an optional command that can simplify the whole config file, and will make it more scalable. You have to specify a list of the languages in which you want to translate the documents. This is as simple as:

 [po4a_langs] fr de

This will enable you to expand $lang to all the specified languages in the rest of the config file.

  Specifying the paths to translator inputs
First, you have to specify where the translator input files (ie, the files used by translators to do their job) are located. It can be done by such a line:

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

The command is thus 'po4a_paths'. The first argument is the path to the pot file to use. All subsequent arguments are of the self-explanationary form:

    <lang>:<path to the po file for this lang>

If you've defined the template languages, you can rewrite the line above this way:

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

  Specifying the documents to translate
You now naturally have to specify which documents are translated, their format, and where to put the translations. It can be made by such lines:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_cram.sgml
 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
             add_fr:doc/l10n/script.fr.add

This should be rather self-explanatory also. Note that in the second case, doc/l10n/script.fr.add is an addendum to add to the French version of this document. Please refer to po4a(7) for more information about the addenda.

More formally, the format is:

 [type: <format>] <master_doc> <lang>:<localized_doc>* add_<lang>:<addendum>*

If you've defined the template languages, you can rewrite the line above this way:

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

If all the languages had addenda with similar paths, you could also write something like:

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

  Specifying options for the modules
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 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.

There are some known limitations: you can't specify an argument with a space or a double quote to a module option.

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

  Specifying aliases
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 define a module alias named test, based on the man module, with the -k 21 apply 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.

OPTIONS

-k, --keep
    Minimal threshold for translation percentage to keep (ie, write) the resulting file (default: 80). Ie, by default, files have to be translated at at least 80% to get written.

-h, --help
    Show a short help message.

-M, --master-charset
    Charset of the files containing the documents to translate. Note that all master documents must use the same charset for now. This is a known limitation, and we are working on solving this.

-L, --localized-charset
    Charset of the files containing the localized documents. Note that all translated documents will use the same charset for now. This is a known limitation, and we are working on solving this.

-A, --addendum-charset
    Charset of the addenda. Note that all the addenda should be in the same charset.

-V, --version
    Display the version of the script and exit.

-v, --verbose
    Increase the verbosity of the program.

-q, --quiet
    Decrease the verbosity of the program.

-d, --debug
    Output some debugging information.

-f, --force
    Always generate the POT and PO files, even if po4a considers it is not necessary.

    The default behavior (when --force is not specified) is the following:

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

        The PO files are re-generated based on the POT-Creation-Date of the POT and PO files.

--no-translations
    Do not generate the translated documents, only update the POT and PO files.

--rm-translations
    Remove the translated files (implies --no-translations).

--no-backups
    Do not generate the .po~ backup files.

--rm-backups
    Remove the .po~ backup files (implies --no-backups).

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

SHORTCOMINGS

•   Duplicates some code with the po4a-* programs.

Patch welcome ;)

SEE ALSO
po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).

AUTHORS
 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

COPYRIGHT AND LICENSE
Copyright 2002, 2003, 2004 by SPI, inc.

This program is free software; you may redistribute it and/or modify it under the terms of GPL (see the COPYING file).