po4a(1)

NAME

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

SYNOPSIS

po4a [options] <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-explanatory
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; You can also use $master to refer to the document basename. In this
case, po4a will use a splitted mode: one POT and one PO (for each
language) will be created for each document specified in the po4a
configuration file. See the Splitted mode section.

[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Autodetection of the paths and languages: Another command can be used to specify the name of a directory where
the PO and POT files are located. When it is used, po4a will detect
the POT file as the only "*.pot" file from the specified directory.
Po4a will also use the list of "*.po" files to define the list of
languages (by stripping out the extension). These languages will be
used for the substitution of the $lang variable in the rest of the
configuration file.; This command should not be used together with the po4a_langs or
po4a_paths commands.

[po_directory] po4a/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 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:"..."
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.
Splitted mode: The splitted mode is used when $master is used in the [po4a_paths]
line.; When the splitted 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.

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:
-o, --option: Extra option(s) to pass to the format plugin. Specify each option
in the 'name=value' format. See the documentation of each plugin
for more information about the valid options and their meanings.

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 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.
--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.
--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".
--msgmerge-opt options: Extra options for msgmerge.; 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.
--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.

SHORTCOMINGS

o Duplicates some code with the po4a-* programs.

Patch welcome ;)

AUTHORS

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

COPYRIGHT AND LICENSE

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

docs.sk

comprehensive documentation repository

See also