Man page 1 : po4a

Specifying the template languages

Specifying the paths to translator inputs

Autodetection of the paths and languages

Specifying the documents to translate

Specifying options for the modules

Specifying aliases

Split mode

Note: It is recommended to use [po_directory] rather than [po4a_langs] and [po4a_paths]. See section Autodetection of the paths and languages below.

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 \f(CB$lang\fB to all the specified languages in the rest of the config file.

Note: It is recommended to use [po_directory] rather than [po4a_langs] and [po4a_paths]. See section Autodetection of the paths and languages below.

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 \f(CB$master\fB to refer to the document basename. In this case, po4a will use a split mode: one POT and one PO (for each language) will be created for each document specified in the po4a configuration file. See the Split mode section.

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

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 \f(CB$lang\fB variable in the rest of the configuration file.

This command should not be used together with the [po4a_langs] or [po4a_paths] commands.

When using this command, you have to create an empty POT file on the first invocation of po4a to let it know the name of the POT file.

[po_directory] po4a/po/

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>:<modifier>*<addendum_path>)*

If there is no modifier, addendum_path is a path to an addendum. Modifiers are

? 2 Include addendum_path if this file does exist, otherwise do nothing.

@ 2 addendum_path is not a regular addendum but a file containg a list of addenda, one by line. Each addendum may be preceded by modifiers.

! 2 addendum_path is discarded, it is not loaded and will not be loaded by any further addendum specification.

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

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 \f(CW$lang:tmp\fR/test2_man.$lang.1 \ opt:\*(L"-k 75\*(R" opt_it:\*(L"-L UTF-8\*(R" opt_fr:-v

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

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:\*(L"...\*(R" opt_fr:\*(L"...\*(R"

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:\*(L"-k 21\*(R" opt_es:\*(L"-o debug=splitargs\*(R"

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 \f(CW$lang:tmp\fR/test2_man.$lang.1 \ opt_it:\*(L"-L UTF-8\*(R" opt_fr:-v

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

The split mode is used when \f(CB$master\fB 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.

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:

[po_directory] 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 add 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