1PO4A.1P(1) User Contributed Perl Documentation PO4A.1P(1)
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 Upon execution, po4a parses all documentation files specified in its
19 configuration file. It updates the PO files (containing the
20 translation) to reflect any change to the documentation, and produce a
21 translated documentation by injecting the content's translation (found
22 in the PO files) into the structure of the original master document.
23 At first, the PO files only contain the strings to translate from the
25 original documentation. This file format allows the translators to
26 manually provide a translation for each paragraph extracted by po4a. If
27 the documentation is modified after translation, po4a marks the
28 corresponding translations as "fuzzy" in the PO file to request a
29 manual review by the translators. The translators can also provide so-
30 called "addendum", that are extra content stating for example who did
31 the translation and how to report bugs.
32 master documents ---+---->-------->---------+
34 (doc authoring) | |
35 V (po4a executions) >-----+--> translated
36 | | | documents
37 existing PO files -->--> updated PO files >-+ |
38 ^ | |
39 | V |
40 +----------<---------<-------+ ^
41 (manual translation process) |
42 |
43 addendum -->--------------------------------------+
44 The workflow of po4a is asynchronous, as suited to open-source
46 projects. The documentation writers author the master documents at
47 their own pace. The translators review and update the translations in
48 the PO files. The maintainers rerun po4a on need, to reflect any change
49 to the original documentation to the PO files, and to produce updated
50 documentation translations, by injecting the latest translation into
51 the latest document structure.
52 By default, a given translated document is produced when at least 80%
54 of its content is translated. The untranslated text is kept in the
55 original language. The produced documentation thus mixes languages if
56 the translation is not complete. You can change the 80% threshold with
57 the --keep option described below. Note however that discarding
58 translations as soon as they are not 100% may be discouraging for the
59 translators whose work will almost never be shown to the users, while
60 showing "translations" that are too incomplete may be troubling for the
61 end users.
62 Storing the translated documentation files in the version control
64 system is probably a bad idea, since they are automatically generated.
65 The precious files are the PO files, that contain the hard work of your
66 fellow translators. Also, some people find it easier to interact with
67 the translators through an online platform such as weblate, but this is
68 naturally fully optional.
69 Quick start tutorial
71 Let's assume you maintain a program named foo which has a man page
72 man/foo.1 written in English (the bridge language in most open-source
73 projects, but po4a can be used from or to any language). Some times
74 ago, someone provided a German translation named man/foo.de.1 and
75 disappeared. This is a problem because you just got a bug report
76 saying that your documentation contains a gravely misleading
77 information that must be fixed in all languages, but you don't speak
78 German so you can only modify the original, not the translation. Now,
79 another contributor wants to contribute a translation to Japanese, a
80 language that you don't master either.
81 It is time to convert your documentation to po4a to solve your
83 documentation maintenance nightmares. You want to update the doc when
84 needed, you want to ease the work of your fellow translators, and you
85 want to ensure that your users never see any outdated and thus
86 misleading documentation.
87 The conversion includes two steps: setup the po4a infrastructure, and
89 convert the previous German translation to salvage the previous work.
90 This latter part is done using po4a-gettextize, as follows. As detailed
91 in the documentation of po4a-gettextize(1), this process rarely fully
92 automatic, but once it's done, the de.po file containing the German
93 translation can be integrated in your po4a workflow.
94 po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po
96 Let's now configure po4a. With the appropriate file layout, your
98 configuration file could be as simple as this:
99 [po_directory] man/po4a/
101 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1
103 It specifies that all PO files (containing the work of the translators)
105 are the man/po4a/ directory, and that you have only one master file,
106 man/foo.1. If you had several master files, you would have several
107 lines similar to the second one. Each such line also specify where to
108 write the corresponding translation files. Here, the German translation
109 of man/foo.1 is in man/translated/foo.de.1.
110 The last thing we need to complete the configuration of po4a is a POT
112 file containing the template material that should be used to start a
113 new translation. Simply create an empty file with the .pot extension
114 in the specified po_directory (e.g. man/po4a/foo.pot), and po4a will
115 fill it with the expected content.
116 Here is a recap of the files in this setup:
118 ├── man/
120 │ ├── foo.1 <- The original man page, in English.
121 │ ├── po4a/
122 │ │ ├── de.po <- The German PO translation, from gettextization.
123 │ │ └── foo.pot <- The POT template of future translations (empty at first)
124 │ └── translated/ <- Directory where the translations will be created
125 └── po4a.cfg <- The configuration file.
126 Once setup, executing po4a will parse your documentation, update the
128 POT template file, use it to update the PO translation files, and use
129 them to update the documentation translation files. All in one command:
130 po4a --verbose po4a.cfg
132 This it. po4a is now fully configured. Once you've fixed your error in
134 man/foo.1, the offending paragraph in the German translation will be
135 replaced by the fixed text in English. Mixing languages is not optimal,
136 but it's the only way to remove errors in translations that you don't
137 even understand, and ensure that the content presented to the users is
138 never misleading. Updating the German translation is also much easier
139 in the corresponding PO file, so the language mix-up may not last long.
140 Finally, when the Japanese translator gives you a jp.po translated
141 file, just drop it in man/po4a/po/. A translated page will appear as
142 man/translated/foo.jp.1 (provided that enough content is translated)
143 when you run po4a again.
144
146 -k, --keep
147 Minimal threshold for translation percentage to keep (i.e. write)
148 the resulting file (default: 80). I.e. by default, files have to be
149 translated at least at 80% to be written on disk.
150 -h, --help
152 Show a short help message.
153 -M, --master-charset
155 Charset of the files containing the documents to translate. Note
156 that all master documents must use the same charset.
157 -L, --localized-charset
159 Charset of the files containing the localized documents. Note that
160 all translated documents will use the same charset.
161 -A, --addendum-charset
163 Charset of the addenda. Note that all the addenda should be in the
164 same charset.
165 -V, --version
167 Display the version of the script and exit.
168 -v, --verbose
170 Increase the verbosity of the program.
171 -q, --quiet
173 Decrease the verbosity of the program.
174 -d, --debug
176 Output some debugging information.
177 -o, --option
179 Extra option(s) to pass to the format plugin. See the documentation
180 of each plugin for more information about the valid options and
181 their meanings. For example, you could pass '-o tablecells' to the
182 AsciiDoc parser, while the text parser would accept '-o
183 tabs=split'.
184 -f, --force
186 Always generate the POT and PO files, even if po4a considers it is
187 not necessary.
188 The default behavior (when --force is not specified) is the
190 following:
191 If the POT file already exists, it is regenerated if a master
193 document or the configuration file is more recent (unless
194 --no-update is provided). The POT file is also written in a
195 temporary document and po4a verifies that the changes are
196 really needed.
197 Also, a translation is regenerated only if its master document,
199 the PO file, one of its addenda or the configuration file is
200 more recent. To avoid trying to regenerate translations which
201 do not pass the threshold test (see --keep), a file with the
202 .po4a-stamp extension can be created (see --stamp).
203 If a master document includes files, you should use the --force
205 flag because the modification time of these included files are not
206 taken into account.
207 The PO files are always re-generated based on the POT with msgmerge
209 -U.
210 --stamp
212 Tells po4a to create stamp files when a translation is not
213 generated because it does not reach the threshold. These stamp
214 files are named according to the expected translated document, with
215 the .po4a-stamp extension.
216 Note: This only activates the creation of the .po4a-stamp files.
218 The stamp files are always used if they exist, and they are removed
219 with --rm-translations or when the file is finally translated.
220 --no-translations
222 Do not generate the translated documents, only update the POT and
223 PO files.
224 --no-update
226 Do not change the POT and PO files, only the translation may be
227 updated.
228 --keep-translations
230 Keeps the existing translation files even if the translation
231 doesn't meet the threshold specified by --keep. This option does
232 not create new translation files with few content, but it will save
233 existing translations which decay because of changes to the master
234 files.
235 WARNING: This flag changes the po4a behavior in a rather drastic
237 way: your translated files will not get updated at all until the
238 translation improves. Only use this flag if you prefer shipping an
239 outdated translated documentation rather than only shipping an
240 accurate untranslated documentation.
241 --rm-translations
243 Remove the translated files (implies --no-translations).
244 --no-backups
246 This flag does nothing since 0.41, and may be removed in later
247 releases.
248 --rm-backups
250 This flag does nothing since 0.41, and may be removed in later
251 releases.
252 --translate-only translated-file
254 Translate only the specified file. It may be useful to speed up
255 processing if a configuration file contains a lot of files. Note
256 that this option does not update PO and POT files. This option can
257 be used multiple times.
258 --variable var=value
260 Define a variable that will be expanded in the po4a configuration
261 file. Every occurrence of $(var) will be replaced by value. This
262 option can be used multiple times.
263 --srcdir SRCDIR
265 Set the base directory for all input documents specified in the
266 po4a configuration file.
267 If both destdir and srcdir are specified, input files are searched
269 in the following directories, in order: destdir, the current
270 directory and srcdir. Output files are written to destdir if
271 specified, or to the current directory.
272 --destdir DESTDIR
274 Set the base directory for all the output documents specified in
275 the po4a configuration file (see --srcdir above).
276 Options modifying the POT header
278 --porefs type
279 Specify the reference format. Argument type can be one of never to
280 not produce any reference, file to only specify the file without
281 the line number, counter to replace line number by an increasing
282 counter, and full to include complete references (default: full).
283 --wrap-po no|newlines|number (default: 76)
285 Specify how the po file should be wrapped. This gives the choice
286 between either files that are nicely wrapped but could lead to git
287 conflicts, or files that are easier to handle automatically, but
288 harder to read for humans.
289 Historically, the gettext suite has reformatted the po files at the
291 77th column for cosmetics. This option specifies the behavior of
292 po4a. If set to a numerical value, po4a will wrap the po file after
293 this column and after newlines in the content. If set to newlines,
294 po4a will only split the msgid and msgstr after newlines in the
295 content. If set to no, po4a will not wrap the po file at all. The
296 reference comments are always wrapped by the gettext tools that we
297 use internally.
298 Note that this option has no impact on how the msgid and msgstr are
300 wrapped, i.e. on how newlines are added to the content of these
301 strings.
302 --master-language
304 Language of the source files containing the documents to translate.
305 Note that all master documents must use the same language.
306 --msgid-bugs-address email@address
308 Set the report address for msgid bugs. By default, the created POT
309 files have no Report-Msgid-Bugs-To fields.
310 --copyright-holder string
312 Set the copyright holder in the POT header. The default value is
313 "Free Software Foundation, Inc."
314 --package-name string
316 Set the package name for the POT header. The default is "PACKAGE".
317 --package-version string
319 Set the package version for the POT header. The default is
320 "VERSION".
321 Options to modify the PO files
323 --msgmerge-opt options
324 Extra options for msgmerge(1).
325 Note: $lang will be extended to the current language.
327 --no-previous
329 This option removes --previous from the options passed to msgmerge.
330 This is necessary to support versions of gettext earlier than 0.16.
331 --previous
333 This option adds --previous to the options passed to msgmerge. It
334 requires gettext 0.16 or later, and is activated by default.
335
337 po4a expects a configuration file as argument. This file must contain
338 the following elements:
339 • The path to the PO files and the list of languages existing in the
341 project;
342 • Optionally, some global options and so-called configuration aliases
344 that are used as templates to configure individual master files;
345 • The list of each master file to translate, along with specific
347 parameters.
348 All lines contain a command between square braces, followed by its
350 parameters. Comments begin with the char '#' and run until the end of
351 the line. You can escape the end of line to spread a command over
352 several lines.
353 Some full examples are presented on this page, while other examples can
355 be found in the "t/cfg" directory of the source distribution.
356 Finding the PO and POT files
358 The simplest solution is to explicitly give the path to POT and PO
359 files, as follows:
360 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
362 This specifies the path to the POT file first, and then the paths to
364 the German and French PO files.
365 The same information can be written as follows to reduce the risk of
367 copy/paste errors:
368 [po4a_langs] fr de
370 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
371 The $lang component is automatically expanded using the provided
373 languages list, reducing the risk of copy/paste error when a new
374 language is added.
375 You can further compact the same information by only providing the path
377 to the directory containing your translation project, as follows.
378 [po_directory] man/po/
380 The provided directory must contain a set of PO files, each named XX.po
382 with "XX" the ISO 639-1 of the language used in this file. The
383 directory must also contain a single POT file, with the ".pot" file
384 extension. For the first run, this file can be empty but it must exist
385 (po4a cannot guess the name to use before the extension).
386 Note that you must choose only one between "po_directory" and
388 "po4a_paths". The first one ("po_directory") is more compact, further
389 reduces the risk of copy/paste error, but forces you to use the
390 expected project structure and file names. The second one
391 ("po4a_paths"), is more explicit, probably more readable, and advised
392 when you setup your first project with po4a.
393 Centralized or split PO files?
395 By default, po4a produces one single PO file per target language,
397 containing the whole content of your translation project. As your
398 project grows, the size of these files may become problematic. When
399 using weblate, it is possible to specify priorities for each
400 translation segment (i.e., msgid) so that the important ones get
401 translated first. Still, some translation teams prefer to split the
402 content in several files.
403 To have one PO file per master file, you simply have to use the string
405 $master in the name of your PO files on the "[po4a_paths]" line, as
406 follows.
407 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
409 With this line, po4a will produce separate POT and PO files for each
411 document to translate. For example, if you have 3 documents and 5
412 languages, this will result in 3 POT files and 15 PO files. These files
413 are named as specified on the "po4a_paths" template, with $master
414 substituted to the basename of each document to translate. In case of
415 name conflict, you can specify the POT file to use as follows, with the
416 "pot=" parameter.
417 This feature can also be used to group several translated files into
419 the same POT file. The following example only produces 2 POT files:
420 l10n/po/foo.pot (containing the material from foo/gui.xml) and
421 l10n/po/bar.pot (containing the material from both bar/gui.xml and
422 bar/cli.xml).
423 [po4a_langs] de fr ja
425 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
426 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo
427 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
428 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar
429 In split mode, po4a builds a temporary compendium during the PO update,
431 to share the translations between all the PO files. If two PO files
432 have different translations for the same string, po4a will mark this
433 string as fuzzy and will submit both translations in all the PO files
434 containing this string. When unfuzzied by the translator, the
435 translation is automatically used in every PO files.
436 Specifying the documents to translate
438 You must also list the documents that should be translated. For each
439 master file, you must specify the format parser to use, the location of
440 the translated document to produce, and optionally some configuration.
441 Here is an example:
442 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
444 de:doc/de/mein_kram.sgml
445 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
446 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
447 de:doc/de/script.xml
448 But again, these complex lines are difficult to read and modify, e.g.
450 when adding a new language. It is much simpler to reorganize things
451 using the $lang template as follows:
452 [type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
454 [type: man] script.1 $lang:po/$lang/script.1
455 [type: docbook] doc/script.xml $lang:doc/$lang/script.xml
456 Specifying options
458 There is two types of options: po4a options are default values to the
459 po4a command line options while format options are used to change the
460 behavior of the format parsers. As a po4a options, you could for
461 example specify in your configuration file that the default value of
462 the --keep command line parameter is 50% instead of 80%. Format options
463 are documented on the specific page of each parsing module, e.g.
464 Locale::Po4a::Xml(3pm). You could for example pass nostrip to the XML
465 parser to not strip the spaces around the extracted strings.
466 You can pass these options for a specific master file, or even for a
468 specific translation of that file, using "opt:" and "opt_XX:" for the
469 "XX" language. In the following example, the nostrip option is passed
470 to the XML parser (for all languages), while the threshold will be
471 reduced to 0% for the French translation (that is thus always kept).
472 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
474 In any case, these configuration chunks must be located at the end of
476 the line. The declaration of files must come first, then the addendum
477 if any (see below), and then only the options. The grouping of
478 configuration chunks is not very important, since elements are
479 internally concatenated as strings. The following examples are all
480 equivalent:
481 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
483 [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
484 [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0
485 Note that language specific options are not used when building the POT
487 file. It is for example impossible to pass nostrip to the parser only
488 when building the French translation, because the same POT file is used
489 to update every languages. So the only options that can be language-
490 specific are the ones that are used when producing the translation, as
491 the "--keep" option.
492 Configuration aliases
494 To pass the same options to several files, the best is to define a type
496 alias as follows. In the next example, "--keep 0" is passed to every
497 Italian translation using this "test" type, that is an extension of the
498 "man" type.
499 [po4a_alias:test] man opt_it:"--keep 0"
501 [type: test] man/page.1 $lang:man/$lang/page.1
502 You can also extend an existing type reusing the same name for the
504 alias as follows. This is not interpreted as as an erroneous recursive
505 definition.
506 [po4a_alias:man] man opt_it:"--keep 0"
508 [type: man] man/page.1 $lang:man/$lang/page.1
509 Global default options
511 You can also use "[options]" lines to define options that must be used
513 for all files, regardless of their type.
514 [options] --keep 20 --option nostrip
516 As with the command line options, you can abbreviate the parameters
518 passed in the configuration file:
519 [options] -k 20 -o nostrip
521 Option priorities
523 The options of every sources are concatenated, ensuring that the
525 default values can easily be overridden by more specific options. The
526 order is as follows:
527 • "[options]" lines provide default values that can be overridden by
529 any other source.
530 • Type aliases are then used. Language specific settings override the
532 ones applicable to all languages.
533 • Settings that are specific to a given master file override both the
535 default ones and the ones coming from the type alias. In this case
536 also, language specific settings override the global ones.
537 • Finally, parameters provided on the po4a command line override any
539 settings from the configuration file.
540 Example
542 Here is an example showing how to quote the spaces and quotes:
544 [po_directory] man/po/
546 [options] --master-charset UTF-8
548 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
550 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
551 opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose
552 Addendum: Adding extra content in the translation
554 If you want to add an extra section to the translation, for example to
555 give credit to the translator, then you need to define an addendum to
556 the line defining your master file. Please refer to the page po4a(7)
557 for more details on the syntax of addendum files.
558 [type: pod] script fr:doc/fr/script.1 \
560 add_fr:doc/l10n/script.fr.add
561 You can also use language templates as follow:
563 [type: pod] script $lang:doc/$lang/script.1 \
565 add_$lang:doc/l10n/script.$lang.add
566 If an addendum fails to apply, the translation is discarded.
568 Modifiers for the addendum declaration
570 Addendum modifiers can simplify the configuration file in the case
572 where not all languages provide an addendum, or when the list of
573 addenda changes from one language to the other. The modifier is a
574 single char located before the file name.
575 ? Include addendum_path if this file does exist, otherwise do nothing.
577 @ addendum_path is not a regular addendum but a file containing a list
579 of addenda, one by line. Each addendum may be preceded by modifiers.
580 ! addendum_path is discarded, it is not loaded and will not be loaded
582 by any further addendum specification.
583 The following includes an addendum in any language, but if only it
585 exists. No error is reported if the addendum does not exist.
586 [type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
588 The following includes a list of addendum for every language:
590 [type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
592 Filtering the translated strings
594 Sometimes, you want to hide some strings from the translation process.
595 To that extend, you can give a "pot_in" parameter to your master file
596 to specify the name of the file to use instead of the real master when
597 building the POT file. Here is an example:
598 [type:docbook] book.xml \
600 pot_in:book-filtered.xml \
601 $lang:book.$lang.xml
602 With this setting, the strings to translate will be extracted from the
604 book-filtered.xml (that must be produced before calling po4a) while the
605 translated files will be built from book.xml. As a result, any string
606 that is part of book.xml but not in book-filtered.xml will not be
607 included in the PO files, preventing the translators from providing a
608 translation for them. So these strings will be left unmodified when
609 producing the translated documents. This naturally decreases the level
610 of translation, so you may need the "--keep" option to ensure that the
611 document is produced anyway.
612
614 po4a-gettextize(1), po4a(7).
615
617 Denis Barbier <barbier@linuxfr.org>
618 Nicolas François <nicolas.francois@centraliens.net>
619 Martin Quinson (mquinson#debian.org)
620
622 Copyright 2002-2022 by SPI, inc.
623 This program is free software; you may redistribute it and/or modify it
625 under the terms of GPL (see the COPYING file).
626perl v5.38.0 2023-10-12 PO4A.1P(1)