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 With this line, po4a will produce separate POT and PO files for each
336 document to translate. For example, if you have 3 documents and 5
337 languages, this will result in 3 POT files and 15 PO files. These files
338 are named as specified on the "po4a_paths" template, with $master
339 substituted to the basename of each document to translate. In case of
340 name conflict, you can specify the POT file to use as follows, with the
341 "pot=" parameter. This feature can also be used to group several
342 translated files into the same POT file.
343 [po4a_langs] de fr ja
345 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
346 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo-gui
347 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
348 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar
349 In split mode, po4a builds a temporary compendium during the PO update,
351 to share the translations between all the PO files. If two PO files
352 have different translations for the same string, po4a will mark this
353 string as fuzzy and will submit both translations in all the PO files
354 containing this string. When unfuzzied by the translator, the
355 translation is automatically used in every PO files.
356 Specifying the documents to translate
358 You must also list the documents that should be translated. For each
359 master file, you must specify the format parser to use, the location of
360 the translated document to produce, and optionally some configuration.
361 Here is an example:
362 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
364 de:doc/de/mein_kram.sgml
365 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
366 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
367 de:doc/de/script.xml
368 But again, these complex lines are difficult to read and modify, e.g.
370 when adding a new language. It is much simpler to reorganize things
371 using the $lang template as follows:
372 [type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
374 [type: man] script.1 $lang:po/$lang/script.1
375 [type: docbook] doc/script.xml $lang:doc/$lang/script.xml
376 Specifying options
378 There is two types of options: po4a options are default values to the
379 po4a command line options while format options are used to change the
380 behavior of the format parsers. As a po4a options, you could for
381 example specify in your configuration file that the default value of
382 the --keep command line parameter is 50% instead of 80%. Format options
383 are documented on the specific page of each parsing module, e.g.
384 Locale::Po4a::Xml(3pm). You could for example pass nostrip to the XML
385 parser to not strip the spaces around the extracted strings.
386 You can pass these options for a specific master file, or even for a
388 specific translation of that file, using "opt:" and "opt_XX:" for the
389 "XX" language. In the following example, the nostrip option is passed
390 to the XML parser (for all languages), while the threshold will be
391 reduced to 0% for the French translation (that is thus always kept).
392 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
394 In any case, these configuration chunks must be located at the end of
396 the line. The declaration of files must come first, then the addendum
397 if any (see below), and then only the options. The grouping of
398 configuration chunks is not very important, since elements are
399 internally concatenated as strings. The following examples are all
400 equivalent:
401 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
403 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
404 [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0
405 Note that language specific options are not used when building the POT
407 file. It is for example impossible to pass nostrip to the parser only
408 when building the French translation, because the same POT file is used
409 to update every languages. So the only options that can be language-
410 specific are the ones that are used when producing the translation, as
411 the "--keep" option.
412 Configuration aliases
414 To pass the same options to several files, the best is to define a type
416 alias as follows. In the next example, "--keep 0" is passed to every
417 Italian translation using this "test" type, that is an extension of the
418 "man" type.
419 [po4a_alias:test] man opt_it:"--keep 0"
421 [type: test] man/page.1 $lang:man/$lang/page.1
422 You can also extend an existing type reusing the same name for the
424 alias as follows. This is not interpreted as as an erroneous recursive
425 definition.
426 [po4a_alias:man] man opt_it:"--keep 0"
428 [type: man] man/page.1 $lang:man/$lang/page.1
429 Global default options
431 You can also use "[options]" lines to define options that must be used
433 for all files, regardless of their type.
434 [options] --keep 20 --option nostrip
436 As with the command line options, you can abbreviate the parameters
438 passed in the configuration file:
439 [options] -k 20 -o nostrip
441 Option priorities
443 The options of every sources are concatenated, ensuring that the
445 default values can easily be overridden by more specific options. The
446 order is as follows:
447 • "[options]" lines provide default values that can be overridden by
449 any other source.
450 • Type aliases are then used. Language specific settings override the
452 ones applicable to all languages.
453 • Settings that are specific to a given master file override both the
455 default ones and the ones coming from the type alias. In this case
456 also, language specific settings override the global ones.
457 • Finally, parameters provided on the po4a command line override any
459 settings from the configuration file.
460 Example
462 Here is an example showing how to quote the spaces and quotes:
464 [po_directory] man/po/
466 [options] --master-charset UTF-8
468 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
470 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
471 opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose
472 Addendum: Adding extra content in the translation
474 If you want to add an extra section to the translation, for example to
475 give credit to the translator, then you need to define an addendum to
476 the line defining your master file. Please refer to the page po4a(7)
477 for more details on the syntax of addendum files.
478 [type: pod] script fr:doc/fr/script.1 \
480 add_fr:doc/l10n/script.fr.add
481 You can also use language templates as follow:
483 [type: pod] script $lang:doc/$lang/script.1 \
485 add_$lang:doc/l10n/script.$lang.add
486 If an addendum fails to apply, the translation is discarded.
488 Modifiers for the addendum declaration
490 Addendum modifiers can simplify the configuration file in the case
492 where not all languages provide an addendum, or when the list of
493 addenda changes from one language to the other. The modifier is a
494 single char located before the file name.
495 ? Include addendum_path if this file does exist, otherwise do nothing.
497 @ addendum_path is not a regular addendum but a file containing a list
499 of addenda, one by line. Each addendum may be preceded by modifiers.
500 ! addendum_path is discarded, it is not loaded and will not be loaded
502 by any further addendum specification.
503 The following includes an addendum in any language, but if only it
505 exists. No error is reported if the addendum does not exist.
506 [type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
508 The following includes a list of addendum for every language:
510 [type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
512 Filtering the translated strings
514 Sometimes, you want to hide some strings from the translation process.
515 To that extend, you can give a "pot_in" parameter to your master file
516 to specify the name of the file to use instead of the real master when
517 building the POT file. Here is an example:
518 [type:docbook] book.xml \
520 pot_in:book-filtered.xml \
521 $lang:book.$lang.xml
522 With this setting, the strings to translate will be extracted from the
524 book-filtered.xml (that must be produced before calling po4a) while the
525 translated files will be built from book.xml. As a result, any string
526 that is part of book.xml but not in book-filtered.xml will not be
527 included in the PO files, preventing the translators from providing a
528 translation for them. So these strings will be left unmodified when
529 producing the translated documents. This naturally decreases the level
530 of translation, so you may need the "--keep" option to ensure that the
531 document is produced anyway.
532 CONFIGURATION EXAMPLE
534 TODO: Is this section really useful?
535 Let's assume you maintain a program named foo which has a man page
537 man/foo.1 which naturally is maintained in English only. Now you as the
538 upstream or downstream maintainer want to create and maintain the
539 translation. First you need to create the POT file necessary to send
540 to translators using po4a-gettextize(1).
541 So for our case we would call
543 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
545 You would then send this file to the appropriate language lists or
547 offer it for download somewhere on your website.
548 Now let's assume you received three translations before your next
550 release: de.po (including an addendum de.add), sv.po and pt.po. Since
551 you don't want to change your Makefile(s) whenever a new translation
552 arrives you can use po4a with an appropriate configuration file in your
553 Makefile. Let's call it po4a.cfg. In our example it would look like
554 the following:
555 [po_directory] man/po4a/po/
557 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
559 add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
560 In this example we assume that your generated man pages (and all PO and
562 addenda files) should be stored in man/translated/$lang/ (respectively
563 in man/po4a/po/ and man/po4a/add_$lang/) below the current directory.
564 In our example the man/po4a/po/ directory would include de.po, pt.po
565 and sv.po, and the man/po4a/add_de/ directory would include de.add.
566 Note the use of the modifier ? as only the German translation (de.po)
568 is accompanied by an addendum.
569 To actually build the translated man pages you would then (once!) add
571 the following line in the build target of the appropriate Makefile:
572 po4a po4a.cfg
574 Once this is set up you don't need to touch the Makefile when a new
576 translation arrives, i.e. if the French team sends you fr.po and fr.add
577 then you simply drop them respectively in man/po4a/po/ and
578 man/po4a/add_fr/ and the next time the program is built the French
579 translation is automatically build as well in man/translated/fr/.
580 Note that you still need an appropriate target to install localized
582 manual pages with English ones.
583 Finally if you do not store generated files into your version control
585 system, you will need a line in your clean target as well:
586 -rm -rf man/translated
587
589 po4a-gettextize(1), po4a-normalize(1), po4a-translate(1),
590 po4a-updatepo(1), po4a(7).
591
593 Denis Barbier <barbier@linuxfr.org>
594 Nicolas Francois <nicolas.francois@centraliens.net>
595 Martin Quinson (mquinson#debian.org)
596
598 Copyright 2002-2020 by SPI, inc.
599 This program is free software; you may redistribute it and/or modify it
601 under the terms of GPL (see the COPYING file).
602Po4a Tools 2022-01-21 PO4A(1p)