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 master document --> PO files --> translations
69 The dataflow cannot be inversed in this tool, and changes in
71 translations are overwritten by the content of the PO files. As a
72 matter of fact, this tool cannot be used to convert existing
73 translations to the po4a system. For that task, please refer to
74 po4a-gettextize(1).
75
77 The (mandatory) argument is the path to the configuration file to use.
78 Its syntax aims at being simple and close to the configuration files
79 used by the intl-tools projects.
80 Comments in this files are noted by the char '#'. It comments
82 everything until the end of the line. Lines can be continued by
83 escaping the end of line. All non blank lines must begin with a []
84 command, followed by its arguments. (sound difficult said that way,
85 but it is rather easy, I hope ;)
86 Specifying the template languages
88 Note: It is recommended to use [po_directory] rather than [po4a_langs]
89 and [po4a_paths]. See section Autodetection of the paths and languages
90 below.
91 This is an optional command that can simplify the whole config file,
93 and will make it more scalable. You have to specify a list of the
94 languages in which you want to translate the documents. This is as
95 simple as:
96 [po4a_langs] fr de
98 This will enable you to expand $lang to all the specified languages in
100 the rest of the config file.
101 Specifying the paths to translator inputs
103 Note: It is recommended to use [po_directory] rather than [po4a_langs]
104 and [po4a_paths]. See section Autodetection of the paths and languages
105 below.
106 First, you have to specify where the translator input files (i.e. the
108 files used by translators to do their job) are located. It can be done
109 by such a line:
110 [po4a_paths] doc/l10n/project.doc.pot \
112 fr:doc/l10n/fr.po de:doc/l10n/de.po
113 The command is thus [po4a_paths]. The first argument is the path to the
115 POT file to use. All subsequent arguments are of the self-explanatory
116 form:
117 <lang>:<path to the PO file for this lang>
119 If you've defined the template languages, you can rewrite the line
121 above this way:
122 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
124 You can also use $master to refer to the document basename. In this
126 case, po4a will use a split mode: one POT and one PO (for each
127 language) will be created for each document specified in the po4a
128 configuration file. See the Split mode section.
129 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
131 Autodetection of the paths and languages
133 Another command can be used to specify the name of a directory where
134 the PO and POT files are located. When it is used, po4a will detect
135 the POT file as the only *.pot file from the specified directory. po4a
136 will also use the list of *.po files to define the list of languages
137 (by stripping out the extension). These languages will be used for the
138 substitution of the $lang variable in the rest of the configuration
139 file.
140 This command should not be used together with the [po4a_langs] or
142 [po4a_paths] commands.
143 When using this command, you have to create an empty POT file on the
145 first invocation of po4a to let it know the name of the POT file.
146 [po_directory] po4a/po/
148 Specifying the documents to translate
150 You now naturally have to specify which documents are translated, their
151 format, and where to put the translations. It can be made by such
152 lines:
153 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
155 de:doc/de/mein_kram.sgml
156 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
157 add_fr:doc/l10n/script.fr.add
158 This should be rather self-explanatory also. Note that in the second
160 case, doc/l10n/script.fr.add is an addendum to add to the French
161 version of this document. Please refer to po4a(7) for more information
162 about the addenda.
163 More formally, the format is:
165 [type: <format>] <master_doc> (<lang>:<localized_doc>)* \
167 (add_<lang>:<modifier>*<addendum_path>)*
168 If there is no modifier, addendum_path is a path to an addendum.
170 Modifiers are
171 ? Include addendum_path if this file does exist, otherwise do nothing.
173 @ addendum_path is not a regular addendum but a file containg a list of
175 addenda, one by line. Each addendum may be preceded by modifiers.
176 ! addendum_path is discarded, it is not loaded and will not be loaded
178 by any further addendum specification.
179 If you've defined the template languages, you can rewrite the line
181 above this way:
182 [type: pod] script $lang:doc/$lang/script.1 \
184 add_fr:doc/l10n/script.fr.add
185 If all the languages had addenda with similar paths, you could also
187 write something like:
188 [type: pod] script $lang:doc/$lang/script.1 \
190 add_$lang:doc/l10n/script.$lang.add
191 Specifying options for the modules
193 po4a accepts options that will be passed to the module. These options
194 are module specific and are specified with the -o switch.
195 If you need a specific option for one of the document you want to
197 translate, you can also specify it in the configuration file. Options
198 are introduced by the opt keyword. The argument of the opt keyword must
199 be quoted with double quotes if it contains a space (e.g. if you
200 specify multiple options, or an option with an argument). You can also
201 specify options that will only apply to a specific language by using
202 the opt_lang keyword.
203 Here is an example:
205 [type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
206 opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v
207 Arguments may contain spaces if you use single quotes or escaped double
209 quotes:
210 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"
211 If you want to specify the same options for many documents, you may
213 want to use an alias (see the Specifying aliases section below).
214 You can also set options for all the documents specified in the
216 configuration file:
217 [options] opt:"..." opt_fr:"..."
218 Specifying aliases
220 If you must specify the same options for multiple files, you may be
221 interested in defining a module alias. This can be done this way:
222 [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
224 This defines a module alias named test, based on the man module, with
226 the -k 21 applied to all the languages and with -o debug=splitargs
227 applied to the Spanish translation.
228 This module alias can then be use like a regular module:
230 [type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
232 opt_it:"-L UTF-8" opt_fr:-v
233 Note that you can specify additional options on a per file basis.
235 Split mode
237 The split mode is used when $master is used in the [po4a_paths] line.
238 When the split mode is used, a temporary big POT and temporary big POs
240 are used. This permits to share the translations between all the POs.
241 If two POs have different translations for the same string, po4a will
243 mark this string as fuzzy and will submit both translations in all the
244 POs which contain this string. Then, when a translator updates the
245 translation and removes the fuzzy tag in one PO, the translation of
246 this string will be updated in every POs automatically.
247
249 -k, --keep
250 Minimal threshold for translation percentage to keep (i.e. write)
251 the resulting file (default: 80). I.e. by default, files have to be
252 translated at at least 80% to get written.
253 -h, --help
255 Show a short help message.
256 -M, --master-charset
258 Charset of the files containing the documents to translate. Note
259 that all master documents must use the same charset for now. This
260 is a known limitation, and we are working on solving this.
261 -L, --localized-charset
263 Charset of the files containing the localized documents. Note that
264 all translated documents will use the same charset for now. This is
265 a known limitation, and we are working on solving this.
266 -A, --addendum-charset
268 Charset of the addenda. Note that all the addenda should be in the
269 same charset.
270 -V, --version
272 Display the version of the script and exit.
273 -v, --verbose
275 Increase the verbosity of the program.
276 -q, --quiet
278 Decrease the verbosity of the program.
279 -d, --debug
281 Output some debugging information.
282 -o, --option
284 Extra option(s) to pass to the format plugin. Specify each option
285 in the 'name=value' format. See the documentation of each plugin
286 for more information about the valid options and their meanings.
287 -f, --force
289 Always generate the POT and PO files, even if po4a considers it is
290 not necessary.
291 The default behavior (when --force is not specified) is the
293 following:
294 If the POT file already exists, it is regenerated if a master
296 document or the configuration file is more recent. The POT
297 file is also written in a temporary document and po4a verifies
298 that the changes are really needed.
299 Also, a translation is regenerated only if its master document,
301 the PO file, one of its addenda or the configuration file is
302 more recent. To avoid trying to regenerate translations which
303 do not pass the threshold test (see --keep), a file with the
304 .po4a-stamp extension can be created (see --stamp).
305 If a master document includes files, you should use the --force
307 flag because the modification time of these included files are not
308 taken into account.
309 The PO files are always re-generated based on the POT with msgmerge
311 -U.
312 --stamp
314 Tells po4a to create stamp files when a translation is not
315 generated because it does not reach the threshold. These stamp
316 files are named according to the expected translated document, with
317 the .po4a-stamp extension.
318 Note: This only activates the creation of the .po4a-stamp files.
320 The stamp files are always used if they exist, and they are removed
321 with --rm-translations or when the file is finally translated.
322 --no-translations
324 Do not generate the translated documents, only update the POT and
325 PO files.
326 --rm-translations
328 Remove the translated files (implies --no-translations).
329 --no-backups
331 This flag does nothing since 0.41, and may be removed in later
332 releases.
333 --rm-backups
335 This flag does nothing since 0.41, and may be removed in later
336 releases.
337 --translate-only translated-file
339 Translate only the specified file. It may be useful to speed up
340 processing if a configuration file contains a lot of files. Note
341 that this option does not update PO and POT files. This option can
342 be used multiple times.
343 --variable var=value
345 Define a variable that will be expanded in the po4a configuration
346 file. Every occurrence of $(var) will be replaced by value. This
347 option can be used multiple times.
348 --srcdir SRCDIR
350 Set the base directory for all input documents specified in the
351 po4a configuration file.
352 --destdir DESTDIR
354 Set the base directory for all the output documents specified in
355 the po4a configuration file.
356 OPTIONS WHICH MODIFY POT HEADER
358 porefs type[,wrap|nowrap]
359 Specify the reference format. Argument type can be one of none to
360 not produce any reference, noline to not specify the line number
361 (more accurately all line numbers are replaced by 1), counter to
362 replace line number by an increasing counter, and full to include
363 complete references.
364 Argument can be followed by a comma and either wrap or nowrap
366 keyword. References are written by default on a single line. The
367 wrap option wraps references on several lines, to mimic gettext
368 tools (xgettext and msgmerge). This option will become the default
369 in a future release, because it is more sensible. The nowrap
370 option is available so that users who want to keep the old behavior
371 can do so.
372 --msgid-bugs-address email@address
374 Set the report address for msgid bugs. By default, the created POT
375 files have no Report-Msgid-Bugs-To fields.
376 --copyright-holder string
378 Set the copyright holder in the POT header. The default value is
379 "Free Software Foundation, Inc."
380 --package-name string
382 Set the package name for the POT header. The default is "PACKAGE".
383 --package-version string
385 Set the package version for the POT header. The default is
386 "VERSION".
387 OPTIONS TO MODIFY PO FILES
389 --msgmerge-opt options
390 Extra options for msgmerge.
391 Note: $lang will be extended to the current language.
393 --no-previous
395 This option removes --previous from the options passed to msgmerge.
396 This permits to support versions of gettext earlier than 0.16.
397 --previous
399 This option adds --previous to the options passed to msgmerge. It
400 requires gettext 0.16 or later, and is activated by default.
401 EXAMPLE
403 Let's assume you maintain a program named foo which has a man page
404 man/foo.1 which naturally is maintained in English only. Now you as the
405 upstream or downstream maintainer want to create and maintain the
406 translation. First you need to create the POT file necessary to send
407 to translators using po4a-gettextize(1).
408 So for our case we would call
410 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
412 You would then send this file to the appropriate language lists or
414 offer it for download somewhere on your website.
415 Now let's assume you received three translations before your next
417 release: de.po (including an addendum de.add), sv.po and pt.po. Since
418 you don't want to change your Makefile(s) whenever a new translation
419 arrives you can use po4a with an appropriate configuration file in your
420 Makefile. Let's call it po4a.cfg. In our example it would look like
421 the following:
422 [po_directory] man/po4a/po/
424 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
426 add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
427 In this example we assume that your generated man pages (and all PO and
429 addenda files) should be stored in man/translated/$lang/ (respectively
430 in man/po4a/po/ and man/po4a/add_$lang/) below the current directory.
431 In our example the man/po4a/po/ directory would include de.po, pt.po
432 and sv.po, and the man/po4a/add_de/ directory would include de.add.
433 Note the use of the modifier ? as only the German translation (de.po)
435 is accompanied by an addendum.
436 To actually build the translated man pages you would then (once!) add
438 the following line in the build target of the appropriate Makefile:
439 po4a po4a.cfg
441 Once this is set up you don't need to touch the Makefile when a new
443 translation arrives, i.e. if the French team sends you fr.po and fr.add
444 then you simply drop them respectively in man/po4a/po/ and
445 man/po4a/add_fr/ and the next time the programm is build the French
446 translation is automatically build as well in man/translated/fr/.
447 Note that you still need an appropriate target to install localized
449 manual pages with English ones.
450 Finally if you do not store generated files into your version control
452 system, you will need a line in your clean target as well:
453 -rm -rf man/translated
454
456 · Duplicates some code with the po4a-* programs.
457 Patch welcome ;)
459
461 po4a-build(1), po4a-gettextize(1), po4a-normalize(1),
462 po4a-translate(1), po4a-updatepo(1), po4a-build.conf(5), po4a(7)
463
465 Denis Barbier <barbier@linuxfr.org>
466 Nicolas François <nicolas.francois@centraliens.net>
467 Martin Quinson (mquinson#debian.org)
468
470 Copyright 2002-2012 by SPI, inc.
471 This program is free software; you may redistribute it and/or modify it
473 under the terms of GPL (see the COPYING file).
474Po4a Tools 2014-06-10 PO4A(1p)