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       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
18       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
24       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
29       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
34       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
42       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
48   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
61       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

OPTIONS

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
76       -h, --help
77           Show a short help message.
78
79       -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
83       -L, --localized-charset
84           Charset of the files containing the localized documents. Note that
85           all translated documents will use the same charset.
86
87       -A, --addendum-charset
88           Charset of the addenda. Note that all the addenda should be in the
89           same charset.
90
91       -V, --version
92           Display the version of the script and exit.
93
94       -v, --verbose
95           Increase the verbosity of the program.
96
97       -q, --quiet
98           Decrease the verbosity of the program.
99
100       -d, --debug
101           Output some debugging information.
102
103       -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
110       -f, --force
111           Always generate the POT and PO files, even if po4a considers it is
112           not necessary.
113
114           The default behavior (when --force is not specified) is the
115           following:
116
117               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
123               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
129           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
133           The PO files are always re-generated based on the POT with msgmerge
134           -U.
135
136       --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
142           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
146       --no-translations
147           Do not generate the translated documents, only update the POT and
148           PO files.
149
150       --no-update
151           Do not change the POT and PO files, only the translation may be
152           updated.
153
154       --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
161           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
167       --rm-translations
168           Remove the translated files (implies --no-translations).
169
170       --no-backups
171           This flag does nothing since 0.41, and may be removed in later
172           releases.
173
174       --rm-backups
175           This flag does nothing since 0.41, and may be removed in later
176           releases.
177
178       --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
184       --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
189       --srcdir SRCDIR
190           Set the base directory for all input documents specified in the
191           po4a configuration file.
192
193           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
198       --destdir DESTDIR
199           Set the base directory for all the output documents specified in
200           the po4a configuration file (see --srcdir above).
201
202   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
209       --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
215           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
224           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
228       --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
232       --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
236       --copyright-holder string
237           Set the copyright holder in the POT header. The default value is
238           "Free Software Foundation, Inc."
239
240       --package-name string
241           Set the package name for the POT header. The default is "PACKAGE".
242
243       --package-version string
244           Set the package version for the POT header. The default is
245           "VERSION".
246
247   Options to modify the PO files
248       --msgmerge-opt options
249           Extra options for msgmerge(1).
250
251           Note: $lang will be extended to the current language.
252
253       --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
257       --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

CONFIGURATION FILE

262       po4a expects a configuration file as argument. This file must contain
263       the following elements:
264
265       •   The path to the PO files and the list of languages existing in the
266           project;
267
268       •   Optionally, some global options and so-called configuration aliases
269           that are used as templates to configure individual master files;
270
271       •   The list of each master file to translate, along with specific
272           parameters.
273
274       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
279       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
282   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
286        [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
287
288       This specifies the path to the POT file first, and then the paths to
289       the German and French PO files.
290
291       The same information can be written as follows to reduce the risk of
292       copy/paste errors:
293
294        [po4a_langs] fr de
295        [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
296
297       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
301       You can further compact the same information by only providing the path
302       to the directory containing your translation project, as follows.
303
304        [po_directory] man/po/
305
306       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
312       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
319       Centralized or split PO files?
320
321       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
329       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
333        [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
334
335       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
339        [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
344       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
351   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
357        [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
363       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
367        [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
371   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
381       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
387        [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
388
389       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
396         [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
400       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
407       Configuration aliases
408
409       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
414         [po4a_alias:test] man opt_it:"--keep 0"
415         [type: test] man/page.1 $lang:man/$lang/page.1
416
417       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
421         [po4a_alias:man] man opt_it:"--keep 0"
422         [type: man] man/page.1 $lang:man/$lang/page.1
423
424       Global default options
425
426       You can also use "[options]" lines to define options that must be used
427       for all files, regardless of their type.
428
429         [options] --keep 20 --option nostrip
430
431       As with the command line options, you can abbreviate the parameters
432       passed in the configuration file:
433
434         [options] -k 20 -o nostrip
435
436       Option priorities
437
438       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
442       •   "[options]" lines provide default values that can be overridden by
443           any other source.
444
445       •   Type aliases are then used. Language specific settings override the
446           ones applicable to all languages.
447
448       •   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
452       •   Finally, parameters provided on the po4a command line override any
453           settings from the configuration file.
454
455       Example
456
457       Here is an example showing how to quote the spaces and quotes:
458
459        [po_directory] man/po/
460
461        [options] --master-charset UTF-8
462
463        [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
467   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
473        [type: pod] script fr:doc/fr/script.1 \
474                    add_fr:doc/l10n/script.fr.add
475
476       You can also use language templates as follow:
477
478        [type: pod] script $lang:doc/$lang/script.1 \
479                    add_$lang:doc/l10n/script.$lang.add
480
481       If an addendum fails to apply, the translation is discarded.
482
483       Modifiers for the addendum declaration
484
485       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
490       ? Include addendum_path if this file does exist, otherwise do nothing.
491
492       @ 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
495       ! addendum_path is discarded, it is not loaded and will not be loaded
496         by any further addendum specification.
497
498       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
501        [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add
502
503       The following includes a list of addendum for every language:
504
505        [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add
506
507   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
513         [type:docbook] book.xml          \
514                 pot_in:book-filtered.xml \
515                 $lang:book.$lang.xml
516
517       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
527   CONFIGURATION EXAMPLE
528       TODO: Is this section really useful?
529
530       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
536       So for our case we would call
537
538        cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
539
540       You would then send this file to the appropriate language lists or
541       offer it for download somewhere on your website.
542
543       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
550        [po_directory] man/po4a/po/
551
552        [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
553                   add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
554
555       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
561       Note the use of the modifier ? as only the German translation (de.po)
562       is accompanied by an addendum.
563
564       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
567               po4a po4a.cfg
568
569       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
575       Note that you still need an appropriate target to install localized
576       manual pages with English ones.
577
578       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

SEE ALSO

583       po4a-gettextize(1), po4a-normalize(1), po4a-translate(1),
584       po4a-updatepo(1), po4a(7).
585

AUTHORS

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
594       This program is free software; you may redistribute it and/or modify it
595       under the terms of GPL (see the COPYING file).
596
597
598
599Po4a Tools                        2021-11-01                          PO4A(1p)
Impressum