1PO4A(1p) Po4a Tools PO4A(1p)
2
6 po4a - update both the PO files and translated documents in one shot
7
9 po4a [options] config_file
10
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 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
22 This document is organized as follow:
23 DESCRIPTION
25 INTRODUCTION
26 CONFIGURATION FILE SYNTAX
27 Specifying the template languages
28 Specifying the paths to translator inputs
30 Autodetection of the paths and languages
32 Specifying the documents to translate
34 Specifying options for the modules
36 Specifying aliases
38 Split mode
40 OPTIONS
42 EXAMPLE
43 SHORTCOMINGS
44 SEE ALSO
45 AUTHORS
46 COPYRIGHT AND LICENSE
47
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 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 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 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 Normal case without specifying pot_in:
69 <- source files ->|<--------- build results --------------->
71 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 Special case with specifying pot_in:
86 <- source files ->|<--------- build results ----------------->
88 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 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
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 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 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 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 [po4a_langs] fr de
133 This will enable you to expand $lang to all the specified languages in
135 the rest of the config file.
136 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 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 [po4a_paths] doc/l10n/project.doc.pot \
147 fr:doc/l10n/fr.po de:doc/l10n/de.po
148 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 <lang>:<path to the PO file for this lang>
154 If you've defined the template languages, you can rewrite the line
156 above this way:
157 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
159 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 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
166 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 This command should not be used together with the [po4a_langs] or
177 [po4a_paths] commands.
178 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 [po_directory] po4a/po/
183 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 [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 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 More formally, the format is:
203 [type: <format>] <master_doc> (<lang>:<localized_doc>)* \
205 (pot_in:<filtered_master_doc>)? \
206 (add_<lang>:<modifier>*<addendum_path>)*
207 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 If there is no modifier, addendum_path is a path to an addendum.
216 Modifiers are
217 ? Include addendum_path if this file does exist, otherwise do nothing.
219 @ 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 ! addendum_path is discarded, it is not loaded and will not be loaded
224 by any further addendum specification.
225 If you've defined the template languages, you can rewrite the line
227 above this way:
228 [type: pod] script $lang:doc/$lang/script.1 \
230 add_fr:doc/l10n/script.fr.add
231 If all the languages had addenda with similar paths, you could also
233 write something like:
234 [type: pod] script $lang:doc/$lang/script.1 \
236 add_$lang:doc/l10n/script.$lang.add
237 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 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 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 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 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 You can also set options for all the documents specified in the
262 configuration file:
263 [options] opt:"..." opt_fr:"..."
264 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 [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
270 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 This module alias can then be used like a regular module:
276 [type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
278 opt_it:"-L UTF-8" opt_fr:-v
279 Note that you can specify additional options on a per file basis.
281 Split mode
283 The split mode is used when $master is used in the [po4a_paths] line.
284 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 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 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 [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
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 -h, --help
310 Show a short help message.
311 -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 -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 -A, --addendum-charset
323 Charset of the addenda. Note that all the addenda should be in the
324 same charset.
325 -V, --version
327 Display the version of the script and exit.
328 -v, --verbose
330 Increase the verbosity of the program.
331 -q, --quiet
333 Decrease the verbosity of the program.
334 -d, --debug
336 Output some debugging information.
337 -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 -f, --force
344 Always generate the POT and PO files, even if po4a considers it is
345 not necessary.
346 The default behavior (when --force is not specified) is the
348 following:
349 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 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 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 The PO files are always re-generated based on the POT with msgmerge
366 -U.
367 --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 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 --no-translations
379 Do not generate the translated documents, only update the POT and
380 PO files.
381 --no-update
383 Do not change the POT and PO files, only the translation may be
384 updated.
385 --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 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 --rm-translations
400 Remove the translated files (implies --no-translations).
401 --no-backups
403 This flag does nothing since 0.41, and may be removed in later
404 releases.
405 --rm-backups
407 This flag does nothing since 0.41, and may be removed in later
408 releases.
409 --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 --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 --srcdir SRCDIR
422 Set the base directory for all input documents specified in the
423 po4a configuration file.
424 --destdir DESTDIR
426 Set the base directory for all the output documents specified in
427 the po4a configuration file.
428 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 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 --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 --copyright-holder string
449 Set the copyright holder in the POT header. The default value is
450 "Free Software Foundation, Inc."
451 --package-name string
453 Set the package name for the POT header. The default is "PACKAGE".
454 --package-version string
456 Set the package version for the POT header. The default is
457 "VERSION".
458 OPTIONS TO MODIFY PO FILES
460 --msgmerge-opt options
461 Extra options for msgmerge(1).
462 Note: $lang will be extended to the current language.
464 --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 --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 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 So for our case we would call
481 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
483 You would then send this file to the appropriate language lists or
485 offer it for download somewhere on your website.
486 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 [po_directory] man/po4a/po/
495 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
497 add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
498 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 Note the use of the modifier ? as only the German translation (de.po)
506 is accompanied by an addendum.
507 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 po4a po4a.cfg
512 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 Note that you still need an appropriate target to install localized
520 manual pages with English ones.
521 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
527 · Duplicates some code with the po4a-* programs.
528 Patch welcome ;)
530
532 po4a-gettextize(1), po4a-normalize(1), po4a-translate(1),
533 po4a-updatepo(1), po4a(7)
534
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 This program is free software; you may redistribute it and/or modify it
544 under the terms of GPL (see the COPYING file).
545Po4a Tools 2019-10-26 PO4A(1p)