1PO4A(1) User Contributed Perl Documentation PO4A(1)
2
6 po4a - update both the po files and translated documents in one shot
7
9 po4a [-dhvV] <config_file>
10
12 The po4a (po for anything) project goal is to ease translations (and
13 more interestingly, the maintenance of translations) using gettext
14 tools on areas where they were not expected like documentation.
15 The "po4a" program is in charge of updating both the po files (to sync
17 them to the original documents) and the translated documents (to sync
18 them to the po files). The main point is to make the use of po4a easier
19 without having to remember of the command line options.
20 It also allows you to mix documents having different formats into the
22 same pot file so that you can have only one such file per project.
23 This behaviour can be mimicked by the other tools of the po4a suite
25 (for example with makefiles), but it is rather difficult to do, and
26 exhausting to redo the same complicated makefiles for each project
27 using po4a.
28 The dataflow can be summarized as follow. Any changes to the master
30 document will be reflected in the po files, and all changes to the po
31 files (either manual or caused by previous step) will be reflected in
32 translation documents.
33 master document --> po files --> translations
35 The dataflow cannot be inversed in this tool, and changes in transla‐
37 tions are overwritten by the content of the po files. As a matter of
38 fact, this tool cannot be used to convert existing translations to the
39 po4a system. For that task, please refer to po4a-gettextize(1).
40
42 The (mandatory) argument is the path to the configuration file to use.
43 Its syntax aims at being simple and close to the configuration files
44 used by the intl-tools projects.
45 Comments in this files are noted by the char '#'. It comments every‐
47 thing until the end of the line. Lines can be continued by escaping the
48 end of line. All non blank lines must begin with a [] command, fol‐
49 lowed by its arguments. (sound difficult said that way, but it is
50 rather easy, I hope ;)
51 Specifying the template languages
53 This is an optional command that can simplify the whole config file,
55 and will make it more scalable. You have to specify a list of the lan‐
56 guages in which you want to translate the documents. This is as simple
57 as:
58 [po4a_langs] fr de
60 This will enable you to expand $lang to all the specified languages in
62 the rest of the config file.
63 Specifying the paths to translator inputs
65 First, you have to specify where the translator input files (ie, the
67 files used by translators to do their job) are located. It can be done
68 by such a line:
69 [po4a_paths] doc/l10n/project.doc.pot fr:doc/l10n/fr.po de:doc/l10n/de.po
71 The command is thus 'po4a_paths'. The first argument is the path to the
73 pot file to use. All subsequent arguments are of the self-explanation‐
74 ary form:
75 <lang>:<path to the po file for this lang>
77 If you've defined the template languages, you can rewrite the line
79 above this way:
80 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po
82 You can also use $master to refer to the document basename. In this
84 case, po4a will use a splitted mode: one POT and one PO (for each lan‐
85 guage) will be created for each document specified in the po4a configu‐
86 ration file. See the Splitted mode section.
87 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
89 Specifying the documents to translate
91 You now naturally have to specify which documents are translated, their
93 format, and where to put the translations. It can be made by such
94 lines:
95 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
97 de:doc/de/mein_cram.sgml
98 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
99 add_fr:doc/l10n/script.fr.add
100 This should be rather self-explanatory also. Note that in the second
102 case, doc/l10n/script.fr.add is an addendum to add to the French ver‐
103 sion of this document. Please refer to po4a(7) for more information
104 about the addenda.
105 More formally, the format is:
107 [type: <format>] <master_doc> <lang>:<localized_doc>* add_<lang>:<addendum>*
109 If you've defined the template languages, you can rewrite the line
111 above this way:
112 [type: pod] script $lang:doc/$lang/script.1 \
114 add_fr:doc/l10n/script.fr.add
115 If all the languages had addenda with similar paths, you could also
117 write something like:
118 [type: pod] script $lang:doc/$lang/script.1 \
120 add_$lang:doc/l10n/script.$lang.add
121 Specifying options for the modules
123 po4a accepts options that will be passed to the module. These options
125 are module specific and are specified with the -o switch.
126 If you need a specific option for one of the document you want to
128 translate, you can also specify it in the configuration file. Options
129 are introduced by the opt keyword. The argument of the opt keyword must
130 be quoted with double quotes if it contains a space (e.g. if you spec‐
131 ify multiple options, or an option with an argument). You can also
132 specify options that will only apply to a specific language by using
133 the opt_lang keyword.
134 Here is an example:
136 [type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
137 opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v
138 Arguments may contain spaces if you use single quotes or escaped double
140 quotes:
141 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"
142 If you want to specify the same options for many documents, you may
144 want to use an alias (see the Specifying aliases section below).
145 You can also set options for all the documents specified in the config‐
147 uration file:
148 [options] opt:"..." opt_fr:"..."
149 Specifying aliases
151 If you must specify the same options for multiple files, you may be
153 interested in defining a module alias. This can be done this way:
154 [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
156 This define a module alias named test, based on the man module, with
158 the -k 21 apply to all the languages and with -o debug=splitargs
159 applied to the Spanish translation.
160 This module alias can then be use like a regular module:
162 [type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
164 opt_it:"-L UTF-8" opt_fr:-v
165 Note that you can specify additional options on a per file basis.
167 Splitted mode
169 The splitted mode is used when $master is used in the [po4a_paths]
171 line.
172 When the splitted mode is used, a temporary big POT and temporary big
174 POs are used. This permits to share the translations between all the
175 POs.
176 If two POs have different translations for the same string, po4a will
178 mark this string as fuzzy and will submit both translations in all the
179 POs which contain this string. Then, when a translator updates the
180 translation and removes the fuzzy tag in one PO, the translation of
181 this string will be updated in every POs automatically.
182
184 -k, --keep
185 Minimal threshold for translation percentage to keep (ie, write)
186 the resulting file (default: 80). Ie, by default, files have to be
187 translated at at least 80% to get written.
188 -h, --help
190 Show a short help message.
191 -M, --master-charset
193 Charset of the files containing the documents to translate. Note
194 that all master documents must use the same charset for now. This
195 is a known limitation, and we are working on solving this.
196 -L, --localized-charset
198 Charset of the files containing the localized documents. Note that
199 all translated documents will use the same charset for now. This is
200 a known limitation, and we are working on solving this.
201 -A, --addendum-charset
203 Charset of the addenda. Note that all the addenda should be in the
204 same charset.
205 -V, --version
207 Display the version of the script and exit.
208 -v, --verbose
210 Increase the verbosity of the program.
211 -q, --quiet
213 Decrease the verbosity of the program.
214 -d, --debug
216 Output some debugging information.
217 -f, --force
219 Always generate the POT and PO files, even if po4a considers it is
220 not necessary.
221 The default behavior (when --force is not specified) is the follow‐
223 ing:
224 If the POT file already exists, it is regenerated if a master
226 document or the configuration file is more recent. The POT
227 file is also written in a temporary document and po4a verifies
228 that the changes are really needed.
229 Also, a translation is regenerated only if its master document,
231 the PO file, one of its addenda or the configuration file is
232 more recent. To avoid trying to regenerate translations which
233 do not pass the threshold test (see --keep), a file with the
234 '.po4a-stamp' extension can be created (see --stamp).
235 If a master document includes files, you should use the --force
237 flag because the modification time of these included files are not
238 taken into account.
239 The PO files are always re-generated based on the POT with msgmerge
241 -U.
242 --stamp
244 Tells po4a to create stamp files when a translation is not gener‐
245 ated because it it does not reach the threshold. These stamp files
246 are named according to the expected translated document, with the
247 .po4a-stamp extension.
248 Note: This only activates the creation of the .po4a-stamp files.
250 The stamp files are always used if they exist, and they are removed
251 with --rm-translations or when the file is finally translated.
252 --no-translations
254 Do not generate the translated documents, only update the POT and
255 PO files.
256 --rm-translations
258 Remove the translated files (implies --no-translations).
259 --no-backups
261 Do not generate the .po~ backup files.
262 --rm-backups
264 Remove the .po~ backup files (implies --no-backups).
265 --variable var=value
267 Define a variable that will be expanded in the po4a configuration
268 file. Every occurrence of $(var) will be replaced by value. This
269 option can be used multiple times.
270 --msgid-bugs-address email@address
272 Set the report address for msgid bugs. By default, the created POT
273 files have no Report-Msgid-Bugs-To fields.
274 --copyright-holder string
276 Set the copyright holder in the POT header. The default value is
277 "Free Software Foundation, Inc."
278 --msgmerge-opt options
280 Extra options for msgmerge.
281 --previous
283 This option adds '--previous' to the options passed to msgmerge.
284 It requires gettext 0.16 or later.
285
287 · Duplicates some code with the po4a-* programs.
288 Patch welcome ;)
290
292 po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
293 po4a-normalize(1).
294
296 Denis Barbier <barbier@linuxfr.org>
297 Martin Quinson (mquinson#debian.org)
298
300 Copyright 2002, 2003, 2004 by SPI, inc.
301 This program is free software; you may redistribute it and/or modify it
303 under the terms of GPL (see the COPYING file).
304perl v5.8.8 2008-06-01 PO4A(1)