1PO4A(1p)                          Po4a Tools                          PO4A(1p)
2
3
4

NAME

6       po4a - update both the PO files and translated documents in one shot
7

SYNOPSIS

9       po4a [options] config_file
10

DESCRIPTION

12       The po4a (PO for anything) project goal is to ease translations (and
13       more interestingly, the maintenance of translations) using gettext
14       tools on areas where they were not expected like documentation.
15
16       The po4a program is useful if you want to avoid calling
17       po4a-gettextize(1), po4a-updatepo(1), and po4a-translate(1) in complex
18       Makefiles when you have multiple files to translate, different format,
19       or need to specify different options for different documents.
20

Table of content

22       This document is organized as follow:
23
24   DESCRIPTION
25   INTRODUCTION
26   CONFIGURATION FILE SYNTAX
27       Specifying the template languages
28
29       Specifying the paths to translator inputs
30
31       Autodetection of the paths and languages
32
33       Specifying the documents to translate
34
35       Specifying options for the modules
36
37       Specifying aliases
38
39       Split mode
40
41   OPTIONS
42   EXAMPLE
43   SHORTCOMINGS
44   SEE ALSO
45   AUTHORS
46   COPYRIGHT AND LICENSE
47
48

INTRODUCTION

50       The po4a program is in charge of updating both the PO files (to sync
51       them to the original documents) and the translated documents (to sync
52       them to the PO files). The main point is to make the use of po4a easier
53       without having to remember of the command line options.
54
55       It also allows you to mix documents having different formats into the
56       same POT file so that you can have only one such file per project.
57
58       This behaviour can be mimicked by the other tools of the po4a suite
59       (for example with Makefiles), but it is rather difficult to do, and
60       exhausting to redo the same complicated Makefiles for each project
61       using po4a.
62
63       The dataflow can be summarized as follow. Any changes to the master
64       document will be reflected in the PO files, and all changes to the PO
65       files (either manual or caused by previous step) will be reflected in
66       translation documents.
67
68       Normal case without specifying pot_in:
69
70        <- source files ->|<--------- build results --------------->
71
72        addendum ----------------------------------+
73                                                   |
74        master document --+---------------------+  |
75                          V                     +--+--> translations
76        old PO files -----+--> updated PO files +
77             ^                      |
78             |                      V
79             +<.....................+
80           (the updated PO files are manually
81            copied to the source of the next
82            release while manually updating
83            the translation contents)
84
85       Special case with specifying pot_in:
86
87        <- source files ->|<--------- build results ----------------->
88
89        master document --+--------------------------+
90                          :                          |
91        external          :    filtered              |
92        filtering ========X..> master                |
93        program                document              |
94                               |                     |
95                               V                     +--> translations
96        old PO files ----------+--> updated PO files +
97             ^                           |
98             |                           V
99             +<..........................+
100           (the updated PO files are manually
101            copied to the source of the next
102            release while manually updating
103            the translation contents)
104
105       The dataflow cannot be reversed in this tool, and changes in
106       translations are overwritten by the content of the PO files. As a
107       matter of fact, this tool cannot be used to convert existing
108       translations to the po4a system. For that task, please refer to
109       po4a-gettextize(1).
110

CONFIGURATION FILE SYNTAX

112       The (mandatory) argument is the path to the configuration file to use.
113       Its syntax aims at being simple and close to the configuration files
114       used by the intl-tools projects.
115
116       Comments in these files are noted by the char '#'. It comments
117       everything until the end of the line. Lines can be continued by
118       escaping the end of line.  All non blank lines must begin with a []
119       command, followed by its arguments.  (sound difficult said that way,
120       but it is rather easy, I hope ;)
121
122   Specifying the template languages
123       Note: It is recommended to use [po_directory] rather than [po4a_langs]
124       and [po4a_paths].  See section Autodetection of the paths and languages
125       below.
126
127       This is an optional command that can simplify the whole config file,
128       and will make it more scalable. You have to specify a list of the
129       languages in which you want to translate the documents. This is as
130       simple as:
131
132        [po4a_langs] fr de
133
134       This will enable you to expand $lang to all the specified languages in
135       the rest of the config file.
136
137   Specifying the paths to translator inputs
138       Note: It is recommended to use [po_directory] rather than [po4a_langs]
139       and [po4a_paths].  See section Autodetection of the paths and languages
140       below.
141
142       First, you have to specify where the translator input files (I.E. the
143       files used by translators to do their job) are located. It can be done
144       by such a line:
145
146        [po4a_paths] doc/l10n/project.doc.pot \
147                     fr:doc/l10n/fr.po de:doc/l10n/de.po
148
149       The command is thus [po4a_paths]. The first argument is the path to the
150       POT file to use. All subsequent arguments are of the self-explanatory
151       form:
152
153           <lang>:<path to the PO file for this lang>
154
155       If you've defined the template languages, you can rewrite the line
156       above this way:
157
158        [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
159
160       You can also use $master to refer to the document filename. In this
161       case, po4a will use a split mode: one POT and one PO (for each
162       language) will be created for each document specified in the po4a
163       configuration file.  See the Split mode section.
164
165        [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
166
167   Autodetection of the paths and languages
168       Another command can be used to specify the name of a directory where
169       the PO and POT files are located.  When it is used, po4a will detect
170       the POT file as the only *.pot file from the specified directory.  po4a
171       will also use the list of *.po files to define the list of languages
172       (by stripping out the extension).  These languages will be used for the
173       substitution of the $lang variable in the rest of the configuration
174       file.
175
176       This command should not be used together with the [po4a_langs] or
177       [po4a_paths] commands.
178
179       When using this command, you have to create an empty POT file on the
180       first invocation of po4a to let it know the name of the POT file.
181
182        [po_directory] po4a/po/
183
184   Specifying the documents to translate
185       You now naturally have to specify which documents are translated, their
186       format, and where to put the translations. It can be made by such
187       lines:
188
189        [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
190                     de:doc/de/mein_kram.sgml
191        [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
192                    add_fr:doc/l10n/script.fr.add
193        [type: docbook] doc/script.xml fr:doc/fr/script.xml \
194                    de:doc/de/script.xml \
195                    pot_in:doc/script.filtered.xml
196
197       This should be rather self-explanatory also. Note that in the second
198       case, doc/l10n/script.fr.add is an addendum to add to the French
199       version of this document.  Please refer to po4a(7) for more information
200       about the addenda.
201
202       More formally, the format is:
203
204        [type: <format>] <master_doc> (<lang>:<localized_doc>)* \
205                         (pot_in:<filtered_master_doc>)? \
206                         (add_<lang>:<modifier>*<addendum_path>)*
207
208       If pot_in is specified, filtered_master_doc is used to create POT file
209       instead of master_doc.  This feature allows user to create flexible
210       ways to avoid contents which shouldn't be included in the PO files.
211       Tools such as C preprocessor (cpp) or XSL Transformation utility (e.g.,
212       xsltproc) can be used to create the external filtering program and call
213       it before invoking po4a.
214
215       If there is no modifier, addendum_path is a path to an addendum.
216       Modifiers are
217
218       ? Include addendum_path if this file does exist, otherwise do nothing.
219
220       @ addendum_path is not a regular addendum but a file containing a list
221         of addenda, one by line.  Each addendum may be preceded by modifiers.
222
223       ! addendum_path is discarded, it is not loaded and will not be loaded
224         by any further addendum specification.
225
226       If you've defined the template languages, you can rewrite the line
227       above this way:
228
229        [type: pod] script $lang:doc/$lang/script.1 \
230                    add_fr:doc/l10n/script.fr.add
231
232       If all the languages had addenda with similar paths, you could also
233       write something like:
234
235        [type: pod] script $lang:doc/$lang/script.1 \
236                    add_$lang:doc/l10n/script.$lang.add
237
238   Specifying options for the modules
239       po4a accepts options that will be passed to the module. These options
240       are module specific and are specified with the -o switch.
241
242       If you need a specific option for one of the documents you want to
243       translate, you can also specify it in the configuration file. Options
244       are introduced by the opt keyword. The argument of the opt keyword must
245       be quoted with double quotes if it contains a space (e.g. if you
246       specify multiple options, or an option with an argument).  You can also
247       specify options that will only apply to a specific language by using
248       the opt_lang keyword.
249
250       Here is an example:
251        [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
252                   opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v
253
254       Arguments may contain spaces if you use single quotes or escaped double
255       quotes:
256        [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"
257
258       If you want to specify the same options for many documents, you may
259       want to use an alias (see the Specifying aliases section below).
260
261       You can also set options for all the documents specified in the
262       configuration file:
263        [options] opt:"..." opt_fr:"..."
264
265   Specifying aliases
266       If you must specify the same options for multiple files, you may be
267       interested in defining a module alias. This can be done this way:
268
269        [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
270
271       This defines a module alias named test, based on the man module, with
272       the -k 21 applied to all the languages and with -o debug=splitargs
273       applied to the Spanish translation.
274
275       This module alias can then be used like a regular module:
276
277        [type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
278                   opt_it:"-L UTF-8" opt_fr:-v
279
280       Note that you can specify additional options on a per file basis.
281
282   Split mode
283       The split mode is used when $master is used in the [po4a_paths] line.
284
285       When the split mode is used, a temporary big POT and temporary big POs
286       are used. This permits to share the translations between all the POs.
287
288       If two POs have different translations for the same string, po4a will
289       mark this string as fuzzy and will submit both translations in all the
290       POs which contain this string. Then, when a translator updates the
291       translation and removes the fuzzy tag in one PO, the translation of
292       this string will be updated in every POs automatically.
293
294       If there are name conflicts because several files have the same
295       filename, the name of the master file can be specified by adding a
296       "master:file="name option:
297
298        [po4a_langs] de fr ja
299        [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
300        [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
301        [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui
302

OPTIONS

304       -k, --keep
305           Minimal threshold for translation percentage to keep (i.e. write)
306           the resulting file (default: 80). I.e. by default, files have to be
307           translated at least at 80% to get written.
308
309       -h, --help
310           Show a short help message.
311
312       -M, --master-charset
313           Charset of the files containing the documents to translate. Note
314           that all master documents must use the same charset for now. This
315           is a known limitation, and we are working on solving this.
316
317       -L, --localized-charset
318           Charset of the files containing the localized documents. Note that
319           all translated documents will use the same charset for now. This is
320           a known limitation, and we are working on solving this.
321
322       -A, --addendum-charset
323           Charset of the addenda. Note that all the addenda should be in the
324           same charset.
325
326       -V, --version
327           Display the version of the script and exit.
328
329       -v, --verbose
330           Increase the verbosity of the program.
331
332       -q, --quiet
333           Decrease the verbosity of the program.
334
335       -d, --debug
336           Output some debugging information.
337
338       -o, --option
339           Extra option(s) to pass to the format plugin. Specify each option
340           in the 'name=value' format. See the documentation of each plugin
341           for more information about the valid options and their meanings.
342
343       -f, --force
344           Always generate the POT and PO files, even if po4a considers it is
345           not necessary.
346
347           The default behavior (when --force is not specified) is the
348           following:
349
350               If the POT file already exists, it is regenerated if a master
351               document or the configuration file is more recent.  The POT
352               file is also written in a temporary document and po4a verifies
353               that the changes are really needed.
354
355               Also, a translation is regenerated only if its master document,
356               the PO file, one of its addenda or the configuration file is
357               more recent.  To avoid trying to regenerate translations which
358               do not pass the threshold test (see --keep), a file with the
359               .po4a-stamp extension can be created (see --stamp).
360
361           If a master document includes files, you should use the --force
362           flag because the modification time of these included files are not
363           taken into account.
364
365           The PO files are always re-generated based on the POT with msgmerge
366           -U.
367
368       --stamp
369           Tells po4a to create stamp files when a translation is not
370           generated because it does not reach the threshold. These stamp
371           files are named according to the expected translated document, with
372           the .po4a-stamp extension.
373
374           Note: This only activates the creation of the .po4a-stamp files.
375           The stamp files are always used if they exist, and they are removed
376           with --rm-translations or when the file is finally translated.
377
378       --no-translations
379           Do not generate the translated documents, only update the POT and
380           PO files.
381
382       --no-update
383           Do not change the POT and PO files, only the translation may be
384           updated.
385
386       --keep-translations
387           Keeps the existing translation files even if the translation
388           doesn't meet the threshold specified by --keep.  This option does
389           not create new translation files with few content, but it will save
390           existing translations which decay because of changes to the master
391           files.
392
393           WARNING: This flag changes the po4a behavior in a rather drastic
394           way: your translated files will not get updated at all until the
395           translation improves. Only use this flag if you prefer shipping an
396           outdated translated documentation rather than only shipping an
397           accurate untranslated documentation.
398
399       --rm-translations
400           Remove the translated files (implies --no-translations).
401
402       --no-backups
403           This flag does nothing since 0.41, and may be removed in later
404           releases.
405
406       --rm-backups
407           This flag does nothing since 0.41, and may be removed in later
408           releases.
409
410       --translate-only translated-file
411           Translate only the specified file.  It may be useful to speed up
412           processing if a configuration file contains a lot of files.  Note
413           that this option does not update PO and POT files.  This option can
414           be used multiple times.
415
416       --variable var=value
417           Define a variable that will be expanded in the po4a configuration
418           file.  Every occurrence of $(var) will be replaced by value.  This
419           option can be used multiple times.
420
421       --srcdir SRCDIR
422           Set the base directory for all input documents specified in the
423           po4a configuration file.
424
425       --destdir DESTDIR
426           Set the base directory for all the output documents specified in
427           the po4a configuration file.
428
429   OPTIONS WHICH MODIFY POT HEADER
430       --porefs type[,wrap|nowrap]
431           Specify the reference format. Argument type can be one of never to
432           not produce any reference, file to only specify the file without
433           the line number, counter to replace line number by an increasing
434           counter, and full to include complete references (default: full).
435
436           Argument can be followed by a comma and either wrap or nowrap
437           keyword.  References are written by default on a single line.  The
438           wrap option wraps references on several lines, to mimic gettext
439           tools (xgettext and msgmerge).  This option will become the default
440           in a future release, because it is more sensible.  The nowrap
441           option is available so that users who want to keep the old behavior
442           can do so.
443
444       --msgid-bugs-address email@address
445           Set the report address for msgid bugs. By default, the created POT
446           files have no Report-Msgid-Bugs-To fields.
447
448       --copyright-holder string
449           Set the copyright holder in the POT header. The default value is
450           "Free Software Foundation, Inc."
451
452       --package-name string
453           Set the package name for the POT header. The default is "PACKAGE".
454
455       --package-version string
456           Set the package version for the POT header. The default is
457           "VERSION".
458
459   OPTIONS TO MODIFY PO FILES
460       --msgmerge-opt options
461           Extra options for msgmerge(1).
462
463           Note: $lang will be extended to the current language.
464
465       --no-previous
466           This option removes --previous from the options passed to msgmerge.
467           This permits to support versions of gettext earlier than 0.16.
468
469       --previous
470           This option adds --previous to the options passed to msgmerge.  It
471           requires gettext 0.16 or later, and is activated by default.
472
473   EXAMPLE
474       Let's assume you maintain a program named foo which has a man page
475       man/foo.1 which naturally is maintained in English only. Now you as the
476       upstream or downstream maintainer want to create and maintain the
477       translation.  First you need to create the POT file necessary to send
478       to translators using po4a-gettextize(1).
479
480       So for our case we would call
481
482        cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
483
484       You would then send this file to the appropriate language lists or
485       offer it for download somewhere on your website.
486
487       Now let's assume you received three translations before your next
488       release: de.po (including an addendum de.add), sv.po and pt.po.  Since
489       you don't want to change your Makefile(s) whenever a new translation
490       arrives you can use po4a with an appropriate configuration file in your
491       Makefile.  Let's call it po4a.cfg. In our example it would look like
492       the following:
493
494        [po_directory] man/po4a/po/
495
496        [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
497                   add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
498
499       In this example we assume that your generated man pages (and all PO and
500       addenda files) should be stored in man/translated/$lang/ (respectively
501       in man/po4a/po/ and man/po4a/add_$lang/) below the current directory.
502       In our example the man/po4a/po/ directory would include de.po, pt.po
503       and sv.po, and the man/po4a/add_de/ directory would include de.add.
504
505       Note the use of the modifier ? as only the German translation (de.po)
506       is accompanied by an addendum.
507
508       To actually build the translated man pages you would then (once!) add
509       the following line in the build target of the appropriate Makefile:
510
511               po4a po4a.cfg
512
513       Once this is set up you don't need to touch the Makefile when a new
514       translation arrives, i.e. if the French team sends you fr.po and fr.add
515       then you simply drop them respectively in man/po4a/po/ and
516       man/po4a/add_fr/ and the next time the program is built the French
517       translation is automatically build as well in man/translated/fr/.
518
519       Note that you still need an appropriate target to install localized
520       manual pages with English ones.
521
522       Finally if you do not store generated files into your version control
523       system, you will need a line in your clean target as well:
524               -rm -rf man/translated
525

SHORTCOMINGS

527       ·   Duplicates some code with the po4a-* programs.
528
529       Patch welcome ;)
530

SEE ALSO

532       po4a-gettextize(1), po4a-normalize(1), po4a-translate(1),
533       po4a-updatepo(1), po4a(7)
534

AUTHORS

536        Denis Barbier <barbier@linuxfr.org>
537        Nicolas François <nicolas.francois@centraliens.net>
538        Martin Quinson (mquinson#debian.org)
539
541       Copyright 2002-2012 by SPI, inc.
542
543       This program is free software; you may redistribute it and/or modify it
544       under the terms of GPL (see the COPYING file).
545
546
547
548Po4a Tools                        2019-10-26                          PO4A(1p)
Impressum