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 po4a (PO for anything) eases the maintenance of documentation
13 translation using the classical gettext tools. The main feature of po4a
14 is that it decouples the translation of content from its document
15 structure. Please refer to the page po4a(7) for a gentle introduction
16 to this project.
17 When you run the po4a program for the first time, with only a
19 configuration file and the documents to translate (called master
20 documents), it produces a POT file (also called translation template)
21 that contains all of the translatable strings in the document in a form
22 that eases the work of translators.
23 Those POT files can either be translated with a specific editor such as
25 the GNOME Translation Editor, KDE's Lokalize or poedit, or they can be
26 integrated in an online localization platform such as weblate or
27 pootle. The translation result is a set of PO files, one per language.
28 When you run the po4a program with both the master documents and the PO
30 files, it produces the translated documents by injecting the content's
31 translation (found in the PO files) into the structure of the original
32 master document.
33 If the master documents changed in the meanwhile, po4a will update the
35 PO and POT files accordingly, so that the translators can easily detect
36 the modifications and update their work. Depending on your settings,
37 po4a will discard the partially translated documents, or produce a
38 document mixing English (for the new or modified paragraphs) and the
39 target language (for paragraphs where translation is already in the PO
40 file).
41 By default, the translated documents are produced when at least 80% of
43 their content is translated (see the --keep option below). Discarding
44 translations as soon as they are not 100% may be discouraging for the
45 translators, while showing "translations" that are too incomplete may
46 be troubling for the end users.
47 Graphical overview
49 master documents ---+---->-------->---------+
50 (doc authoring) | |
51 V (po4a executions) >-----+--> translations
52 | | |
53 existing PO files -->--> updated PO files >-+ |
54 ^ | |
55 | V |
56 +----------<---------<-------+ ^
57 (manual translation process) |
58 |
59 addendum -->--------------------------------------+
60 The master documents are authored by the documentation writers. Any
62 changes are automatically reflected by po4a in the PO files, that are
63 then updated by the translators. All changes to the PO files (either
64 manual or by po4a) are automatically reflected in translated documents.
65 You can mimic this behavior using the po4a-updatepo(1) and
66 po4a-translate(1) scripts in makefiles, but this quickly becomes
67 bothersome and repetitive (see po4a(7)). It is highly recommended to
68 use the po4a program in your build process.
69
71 -k, --keep
72 Minimal threshold for translation percentage to keep (i.e. write)
73 the resulting file (default: 80). I.e. by default, files have to be
74 translated at least at 80% to be written on disk.
75 -h, --help
77 Show a short help message.
78 -M, --master-charset
80 Charset of the files containing the documents to translate. Note
81 that all master documents must use the same charset.
82 -L, --localized-charset
84 Charset of the files containing the localized documents. Note that
85 all translated documents will use the same charset.
86 -A, --addendum-charset
88 Charset of the addenda. Note that all the addenda should be in the
89 same charset.
90 -V, --version
92 Display the version of the script and exit.
93 -v, --verbose
95 Increase the verbosity of the program.
96 -q, --quiet
98 Decrease the verbosity of the program.
99 -d, --debug
101 Output some debugging information.
102 -o, --option
104 Extra option(s) to pass to the format plugin. See the documentation
105 of each plugin for more information about the valid options and
106 their meanings. For example, you could pass '-o tablecells' to the
107 AsciiDoc parser, while the text parser would accept '-o
108 tabs=split'.
109 -f, --force
111 Always generate the POT and PO files, even if po4a considers it is
112 not necessary.
113 The default behavior (when --force is not specified) is the
115 following:
116 If the POT file already exists, it is regenerated if a master
118 document or the configuration file is more recent (unless
119 --no-update is provided). The POT file is also written in a
120 temporary document and po4a verifies that the changes are
121 really needed.
122 Also, a translation is regenerated only if its master document,
124 the PO file, one of its addenda or the configuration file is
125 more recent. To avoid trying to regenerate translations which
126 do not pass the threshold test (see --keep), a file with the
127 .po4a-stamp extension can be created (see --stamp).
128 If a master document includes files, you should use the --force
130 flag because the modification time of these included files are not
131 taken into account.
132 The PO files are always re-generated based on the POT with msgmerge
134 -U.
135 --stamp
137 Tells po4a to create stamp files when a translation is not
138 generated because it does not reach the threshold. These stamp
139 files are named according to the expected translated document, with
140 the .po4a-stamp extension.
141 Note: This only activates the creation of the .po4a-stamp files.
143 The stamp files are always used if they exist, and they are removed
144 with --rm-translations or when the file is finally translated.
145 --no-translations
147 Do not generate the translated documents, only update the POT and
148 PO files.
149 --no-update
151 Do not change the POT and PO files, only the translation may be
152 updated.
153 --keep-translations
155 Keeps the existing translation files even if the translation
156 doesn't meet the threshold specified by --keep. This option does
157 not create new translation files with few content, but it will save
158 existing translations which decay because of changes to the master
159 files.
160 WARNING: This flag changes the po4a behavior in a rather drastic
162 way: your translated files will not get updated at all until the
163 translation improves. Only use this flag if you prefer shipping an
164 outdated translated documentation rather than only shipping an
165 accurate untranslated documentation.
166 --rm-translations
168 Remove the translated files (implies --no-translations).
169 --no-backups
171 This flag does nothing since 0.41, and may be removed in later
172 releases.
173 --rm-backups
175 This flag does nothing since 0.41, and may be removed in later
176 releases.
177 --translate-only translated-file
179 Translate only the specified file. It may be useful to speed up
180 processing if a configuration file contains a lot of files. Note
181 that this option does not update PO and POT files. This option can
182 be used multiple times.
183 --variable var=value
185 Define a variable that will be expanded in the po4a configuration
186 file. Every occurrence of $(var) will be replaced by value. This
187 option can be used multiple times.
188 --srcdir SRCDIR
190 Set the base directory for all input documents specified in the
191 po4a configuration file.
192 If both destdir and srcdir are specified, input files are searched
194 in the following directories, in order: destdir, the current
195 directory and srcdir. Output files are written to destdir if
196 specified, or to the current directory.
197 --destdir DESTDIR
199 Set the base directory for all the output documents specified in
200 the po4a configuration file (see --srcdir above).
201 Options modifying the POT header
203 --porefs type
204 Specify the reference format. Argument type can be one of never to
205 not produce any reference, file to only specify the file without
206 the line number, counter to replace line number by an increasing
207 counter, and full to include complete references (default: full).
208 --wrap-po no|newlines|number (default: 76)
210 Specify how the po file should be wrapped. This gives the choice
211 between either files that are nicely wrapped but could lead to git
212 conflicts, or files that are easier to handle automatically, but
213 harder to read for humans.
214 Historically, the gettext suite has reformatted the po files at the
216 77th column for cosmetics. This option specifies the behavior of
217 po4a. If set to a numerical value, po4a will wrap the po file after
218 this column and after newlines in the content. If set to newlines,
219 po4a will only split the msgid and msgstr after newlines in the
220 content. If set to no, po4a will not wrap the po file at all. The
221 reference comments are always wrapped by the gettext tools that we
222 use internally.
223 Note that this option has no impact on how the msgid and msgstr are
225 wrapped, ie on how newlines are added to the content of these
226 strings.
227 --master-language
229 Language of the source files containing the documents to translate.
230 Note that all master documents must use the same language.
231 --msgid-bugs-address email@address
233 Set the report address for msgid bugs. By default, the created POT
234 files have no Report-Msgid-Bugs-To fields.
235 --copyright-holder string
237 Set the copyright holder in the POT header. The default value is
238 "Free Software Foundation, Inc."
239 --package-name string
241 Set the package name for the POT header. The default is "PACKAGE".
242 --package-version string
244 Set the package version for the POT header. The default is
245 "VERSION".
246 Options to modify the PO files
248 --msgmerge-opt options
249 Extra options for msgmerge(1).
250 Note: $lang will be extended to the current language.
252 --no-previous
254 This option removes --previous from the options passed to msgmerge.
255 This permits to support versions of gettext earlier than 0.16.
256 --previous
258 This option adds --previous to the options passed to msgmerge. It
259 requires gettext 0.16 or later, and is activated by default.
260
262 po4a expects a configuration file as argument. This file must contain
263 the following elements:
264 • The path to the PO files and the list of languages existing in the
266 project;
267 • Optionally, some global options and so-called configuration aliases
269 that are used as templates to configure individual master files;
270 • The list of each master file to translate, along with specific
272 parameters.
273 All lines contain a command between square braces, followed by its
275 parameters. Comments begin with the char '#' and run until the end of
276 the line. You can escape the end of line to spread a command over
277 several lines.
278 Some full examples are presented on this page, while other examples can
280 be found in the "t/cfg" directory of the source distribution.
281 Finding the PO and POT files
283 The simplest solution is to explicitly give the path to POT and PO
284 files, as follows:
285 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
287 This specifies the path to the POT file first, and then the paths to
289 the German and French PO files.
290 The same information can be written as follows to reduce the risk of
292 copy/paste errors:
293 [po4a_langs] fr de
295 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
296 The $lang component is automatically expanded using the provided
298 languages list, reducing the risk of copy/paste error when a new
299 language is added.
300 You can further compact the same information by only providing the path
302 to the directory containing your translation project, as follows.
303 [po_directory] man/po/
305 The provided directory must contain a set of PO files, each named XX.po
307 with "XX" the ISO 639-1 of the language used in this file. The
308 directory must also contain a single POT file, with the ".pot" file
309 extension. For the first run, this file can be empty but it must exist
310 (po4a cannot guess the name to use before the extension).
311 Note that you must choose only one between "po_directory" and
313 "po4a_paths". The first one ("po_directory") is more compact, further
314 reduces the risk of copy/paste error, but forces you to use the
315 expected project structure and file names. The second one
316 ("po4a_paths"), is more explicit, probably more readable, and advised
317 when you setup your first project with po4a.
318 Centralized or split PO files?
320 By default, po4a produces one single PO file per target language,
322 containing the whole content of your translation project. As your
323 project grows, the size of these files may become problematic. When
324 using weblate, it is possible to specify priorities for each
325 translation segment (i.e., msgid) so that the important ones get
326 translated first. Still, some translation teams prefer to split the
327 content in several files.
328 To have one PO file per master file, you simply have to use the string
330 $master in the name of your PO files on the "[po4a_paths]" line, as
331 follows.
332 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
334 If there are name conflicts because several files have the same
336 filename, the name of the master file can be specified by adding a
337 "master:file="name option:
338 [po4a_langs] de fr ja
340 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
341 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
342 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui
343 In split mode, po4a builds a temporary compendium during the PO update,
345 to share the translations between all the PO files. If two PO files
346 have different translations for the same string, po4a will mark this
347 string as fuzzy and will submit both translations in all the PO files
348 containing this string. When unfuzzied by the translator, the
349 translation is automatically used in every PO files.
350 Specifying the documents to translate
352 You must also list the documents that should be translated. For each
353 master file, you must specify the format parser to use, the location of
354 the translated document to produce, and optionally some configuration.
355 Here is an example:
356 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
358 de:doc/de/mein_kram.sgml
359 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
360 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
361 de:doc/de/script.xml
362 But again, these complex lines are difficult to read and modify, e.g.
364 when adding a new language. It is much simpler to reorganize things
365 using the $lang template as follows:
366 [type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
368 [type: man] script.1 $lang:po/$lang/script.1
369 [type: docbook] doc/script.xml $lang:doc/$lang/script.xml
370 Specifying options
372 There is two types of options: po4a options are default values to the
373 po4a command line options while format options are used to change the
374 behavior of the format parsers. As a po4a options, you could for
375 example specify in your configuration file that the default value of
376 the --keep command line parameter is 50% instead of 80%. Format options
377 are documented on the specific page of each parsing module, e.g.
378 Locale::Po4a::Xml(3pm). You could for example pass nostrip to the XML
379 parser to not strip the spaces around the extracted strings.
380 You can pass these options for a specific master file, or even for a
382 specific translation of that file, using "opt:" and "opt_XX:" for the
383 "XX" language. In the following example, the nostrip option is passed
384 to the XML parser (for all languages), while the threshold will be
385 reduced to 0% for the French translation (that is thus always kept).
386 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
388 In any case, these configuration chunks must be located at the end of
390 the line. The declaration of files must come first, then the addendum
391 if any (see below), and then only the options. The grouping of
392 configuration chunks is not very important, since elements are
393 internally concatenated as strings. The following examples are all
394 equivalent:
395 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
397 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
398 [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0
399 Note that language specific options are not used when building the POT
401 file. It is for example impossible to pass nostrip to the parser only
402 when building the French translation, because the same POT file is used
403 to update every languages. So the only options that can be language-
404 specific are the ones that are used when producing the translation, as
405 the "--keep" option.
406 Configuration aliases
408 To pass the same options to several files, the best is to define a type
410 alias as follows. In the next example, "--keep 0" is passed to every
411 Italian translation using this "test" type, that is an extension of the
412 "man" type.
413 [po4a_alias:test] man opt_it:"--keep 0"
415 [type: test] man/page.1 $lang:man/$lang/page.1
416 You can also extend an existing type reusing the same name for the
418 alias as follows. This is not interpreted as as an erroneous recursive
419 definition.
420 [po4a_alias:man] man opt_it:"--keep 0"
422 [type: man] man/page.1 $lang:man/$lang/page.1
423 Global default options
425 You can also use "[options]" lines to define options that must be used
427 for all files, regardless of their type.
428 [options] --keep 20 --option nostrip
430 As with the command line options, you can abbreviate the parameters
432 passed in the configuration file:
433 [options] -k 20 -o nostrip
435 Option priorities
437 The options of every sources are concatenated, ensuring that the
439 default values can easily be overridden by more specific options. The
440 order is as follows:
441 • "[options]" lines provide default values that can be overridden by
443 any other source.
444 • Type aliases are then used. Language specific settings override the
446 ones applicable to all languages.
447 • Settings that are specific to a given master file override both the
449 default ones and the ones coming from the type alias. In this case
450 also, language specific settings override the global ones.
451 • Finally, parameters provided on the po4a command line override any
453 settings from the configuration file.
454 Example
456 Here is an example showing how to quote the spaces and quotes:
458 [po_directory] man/po/
460 [options] --master-charset UTF-8
462 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
464 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
465 opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose
466 Addendum: Adding extra content in the translation
468 If you want to add an extra section to the translation, for example to
469 give credit to the translator, then you need to define an addendum to
470 the line defining your master file. Please refer to the page po4a(7)
471 for more details on the syntax of addendum files.
472 [type: pod] script fr:doc/fr/script.1 \
474 add_fr:doc/l10n/script.fr.add
475 You can also use language templates as follow:
477 [type: pod] script $lang:doc/$lang/script.1 \
479 add_$lang:doc/l10n/script.$lang.add
480 If an addendum fails to apply, the translation is discarded.
482 Modifiers for the addendum declaration
484 Addendum modifiers can simplify the configuration file in the case
486 where not all languages provide an addendum, or when the list of
487 addenda changes from one language to the other. The modifier is a
488 single char located before the file name.
489 ? Include addendum_path if this file does exist, otherwise do nothing.
491 @ addendum_path is not a regular addendum but a file containing a list
493 of addenda, one by line. Each addendum may be preceded by modifiers.
494 ! addendum_path is discarded, it is not loaded and will not be loaded
496 by any further addendum specification.
497 The following includes an addendum in any language, but if only it
499 exists. No error is reported if the addendum does not exist.
500 [type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
502 The following includes a list of addendum for every language:
504 [type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
506 Filtering the translated strings
508 Sometimes, you want to hide some strings from the translation process.
509 To that extend, you can give a "pot_in" parameter to your master file
510 to specify the name of the file to use instead of the real master when
511 building the POT file. Here is an example:
512 [type:docbook] book.xml \
514 pot_in:book-filtered.xml \
515 $lang:book.$lang.xml
516 With this setting, the strings to translate will be extracted from the
518 book-filtered.xml (that must be produced before calling po4a) while the
519 translated files will be built from book.xml. As a result, any string
520 that is part of book.xml but not in book-filtered.xml will not be
521 included in the PO files, preventing the translators from providing a
522 translation for them. So these strings will be left unmodified when
523 producing the translated documents. This naturally decreases the level
524 of translation, so you may need the "--keep" option to ensure that the
525 document is produced anyway.
526 CONFIGURATION EXAMPLE
528 TODO: Is this section really useful?
529 Let's assume you maintain a program named foo which has a man page
531 man/foo.1 which naturally is maintained in English only. Now you as the
532 upstream or downstream maintainer want to create and maintain the
533 translation. First you need to create the POT file necessary to send
534 to translators using po4a-gettextize(1).
535 So for our case we would call
537 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
539 You would then send this file to the appropriate language lists or
541 offer it for download somewhere on your website.
542 Now let's assume you received three translations before your next
544 release: de.po (including an addendum de.add), sv.po and pt.po. Since
545 you don't want to change your Makefile(s) whenever a new translation
546 arrives you can use po4a with an appropriate configuration file in your
547 Makefile. Let's call it po4a.cfg. In our example it would look like
548 the following:
549 [po_directory] man/po4a/po/
551 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
553 add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
554 In this example we assume that your generated man pages (and all PO and
556 addenda files) should be stored in man/translated/$lang/ (respectively
557 in man/po4a/po/ and man/po4a/add_$lang/) below the current directory.
558 In our example the man/po4a/po/ directory would include de.po, pt.po
559 and sv.po, and the man/po4a/add_de/ directory would include de.add.
560 Note the use of the modifier ? as only the German translation (de.po)
562 is accompanied by an addendum.
563 To actually build the translated man pages you would then (once!) add
565 the following line in the build target of the appropriate Makefile:
566 po4a po4a.cfg
568 Once this is set up you don't need to touch the Makefile when a new
570 translation arrives, i.e. if the French team sends you fr.po and fr.add
571 then you simply drop them respectively in man/po4a/po/ and
572 man/po4a/add_fr/ and the next time the program is built the French
573 translation is automatically build as well in man/translated/fr/.
574 Note that you still need an appropriate target to install localized
576 manual pages with English ones.
577 Finally if you do not store generated files into your version control
579 system, you will need a line in your clean target as well:
580 -rm -rf man/translated
581
583 po4a-gettextize(1), po4a-normalize(1), po4a-translate(1),
584 po4a-updatepo(1), po4a(7).
585
587 Denis Barbier <barbier@linuxfr.org>
588 Nicolas François <nicolas.francois@centraliens.net>
589 Martin Quinson (mquinson#debian.org)
590
592 Copyright 2002-2020 by SPI, inc.
593 This program is free software; you may redistribute it and/or modify it
595 under the terms of GPL (see the COPYING file).
596Po4a Tools 2021-11-01 PO4A(1p)