1Locale::Po4a::Po(3pm)             Po4a Tools             Locale::Po4a::Po(3pm)
2
3
4

NAME

6       Locale::Po4a::Po - PO file manipulation module
7

SYNOPSIS

9           use Locale::Po4a::Po;
10           my $pofile=Locale::Po4a::Po->new();
11
12           # Read PO file
13           $pofile->read('file.po');
14
15           # Add an entry
16           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
17                         'flags' => "wrap", 'reference'=>'file.c:46');
18
19           # Extract a translation
20           $pofile->gettext("Hello"); # returns 'bonjour'
21
22           # Write back to a file
23           $pofile->write('otherfile.po');
24

DESCRIPTION

26       Locale::Po4a::Po is a module that allows you to manipulate message
27       catalogs. You can load and write from/to a file (which extension is
28       often po), you can build new entries on the fly or request for the
29       translation of a string.
30
31       For a more complete description of message catalogs in the PO format
32       and their use, please refer to the info documentation of the gettext
33       program (node "`PO Files"').
34
35       This module is part of the po4a project, which objective is to use PO
36       files (designed at origin to ease the translation of program messages)
37       to translate everything, including documentation (man page, info
38       manual), package description, debconf templates, and everything which
39       may benefit from this.
40

OPTIONS ACCEPTED BY THIS MODULE

42       --porefs type
43           Specify the reference format. Argument type can be one of never to
44           not produce any reference, file to only specify the file without
45           the line number, counter to replace line number by an increasing
46           counter, and full to include complete references (default: full).
47
48       --wrap-po no|newlines|number (default: 76)
49           Specify how the po file should be wrapped. This gives the choice
50           between either files that are nicely wrapped but could lead to git
51           conflicts, or files that are easier to handle automatically, but
52           harder to read for humans.
53
54           Historically, the gettext suite has reformatted the po files at the
55           77th column for cosmetics. This option specifies the behavior of
56           po4a. If set to a numerical value, po4a will wrap the po file after
57           this column and after newlines in the content. If set to newlines,
58           po4a will only split the msgid and msgstr after newlines in the
59           content. If set to no, po4a will not wrap the po file at all.  The
60           reference comments are always wrapped by the gettext tools that we
61           use internally.
62
63           Note that this option has no impact on how the msgid and msgstr are
64           wrapped, ie on how newlines are added to the content of these
65           strings.
66
67       --msgid-bugs-address email@address
68           Set the report address for msgid bugs. By default, the created POT
69           files have no Report-Msgid-Bugs-To fields.
70
71       --copyright-holder string
72           Set the copyright holder in the POT header. The default value is
73           "Free Software Foundation, Inc."
74
75       --package-name string
76           Set the package name for the POT header. The default is "PACKAGE".
77
78       --package-version string
79           Set the package version for the POT header. The default is
80           "VERSION".
81

Functions concerning entire message catalogs

83       new()
84           Creates a new message catalog. If an argument is provided, it's the
85           name of a PO file we should load.
86
87       read($)
88           Reads a PO file (which name is given as argument).  Previously
89           existing entries in self are not removed, the new ones are added to
90           the end of the catalog.
91
92       write($)
93           Writes the current catalog to the given file.
94
95       write_if_needed($$)
96           Like write, but if the PO or POT file already exists, the object
97           will be written in a temporary file which will be compared with the
98           existing file to check if the update is needed (this avoids to
99           change a POT just to update a line reference or the POT-Creation-
100           Date field).
101
102       gettextize($$)
103           This function produces one translated message catalog from two
104           catalogs, an original and a translation. This process is described
105           in po4a(7), section Gettextization: how does it work?.
106
107       filter($)
108           This function extracts a catalog from an existing one. Only the
109           entries having a reference in the given file will be placed in the
110           resulting catalog.
111
112           This function parses its argument, converts it to a Perl function
113           definition, evals this definition and filters the fields for which
114           this function returns true.
115
116           I love Perl sometimes ;)
117
118       to_utf8()
119           Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is
120           not specified in the PO file ("CHARSET" value), or if it's already
121           UTF-8 or ASCII.
122

Functions to use a message catalog for translations

124       gettext($%)
125           Request the translation of the string given as argument in the
126           current catalog.  The function returns the original (untranslated)
127           string if the string was not found.
128
129           After the string to translate, you can pass a hash of extra
130           arguments. Here are the valid entries:
131
132           wrap
133               boolean indicating whether we can consider that whitespaces in
134               string are not important. If yes, the function canonizes the
135               string before looking for a translation, and wraps the result.
136
137           wrapcol
138               the column at which we should wrap (default: 76).
139
140       stats_get()
141           Returns statistics about the hit ratio of gettext since the last
142           time that stats_clear() was called. Please note that it's not the
143           same statistics than the one printed by msgfmt --statistic. Here,
144           it's statistics about recent usage of the PO file, while msgfmt
145           reports the status of the file.  Example of use:
146
147               [some use of the PO file to translate stuff]
148
149               ($percent,$hit,$queries) = $pofile->stats_get();
150               print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";
151
152       stats_clear()
153           Clears the statistics about gettext hits.
154

Functions to build a message catalog

156       push(%)
157           Push a new entry at the end of the current catalog. The arguments
158           should form a hash table. The valid keys are:
159
160           msgid
161               the string in original language.
162
163           msgstr
164               the translation.
165
166           reference
167               an indication of where this string was found. Example:
168               file.c:46 (meaning in 'file.c' at line 46). It can be a space-
169               separated list in case of multiple occurrences.
170
171           comment
172               a comment added here manually (by the translators). The format
173               here is free.
174
175           automatic
176               a comment which was automatically added by the string
177               extraction program. See the --add-comments option of the
178               xgettext program for more information.
179
180           flags
181               space-separated list of all defined flags for this entry.
182
183               Valid flags are: c-text, python-text, lisp-text, elisp-text,
184               librep-text, smalltalk-text, java-text, awk-text, object-
185               pascal-text, ycp-text, tcl-text, wrap, no-wrap and fuzzy.
186
187               See the gettext documentation for their meaning.
188
189           type
190               this is mostly an internal argument: it is used while
191               gettextizing documents. The idea here is to parse both the
192               original and the translation into a PO object, and merge them,
193               using one's msgid as msgid and the other's msgid as msgstr. To
194               make sure that things get ok, each msgid in PO objects are
195               given a type, based on their structure (like "chapt", "sect1",
196               "p" and so on in DocBook). If the types of strings are not the
197               same, that means that both files do not share the same
198               structure, and the process reports an error.
199
200               This information is written as automatic comment in the PO file
201               since this gives to translators some context about the strings
202               to translate.
203
204           wrap
205               boolean indicating whether whitespaces can be mangled in
206               cosmetic reformattings. If true, the string is canonized before
207               use.
208
209               This information is written to the PO file using the wrap or
210               no-wrap flag.
211
212           wrapcol
213               the column at which we should wrap (default: 76).
214
215               This information is not written to the PO file.
216

Miscellaneous functions

218       count_entries()
219           Returns the number of entries in the catalog (without the header).
220
221       count_entries_doc()
222           Returns the number of entries in document. If a string appears
223           multiple times in the document, it will be counted multiple times.
224
225       equals_msgid(po)
226           Returns ($uptodate, $diagnostic) with $uptodate indicating whether
227           all msgid of the current po file are also present in the one passed
228           as parameter (all other fields are ignored in the file comparison).
229           Informally, if $uptodate returns false, then the po files would be
230           changed when going through po4a-updatepo.
231
232           If $uptodate is false, then $diagnostic contains a diagnostic of
233           why this is so.
234
235       msgid($)
236           Returns the msgid of the given number.
237
238       msgid_doc($)
239           Returns the msgid with the given position in the document.
240
241       get_charset()
242           Returns the character set specified in the PO header. If it hasn't
243           been set, it will return "UTF-8".
244
245       set_charset($)
246           This sets the character set of the PO header to the value specified
247           in its first argument. If you never call this function (and no file
248           with a specified character set is read), the default value is left
249           to "UTF-8". This value doesn't change the behavior of this module,
250           it's just used to fill that field in the header, and to return it
251           in get_charset().
252

AUTHORS

254        Denis Barbier <barbier@linuxfr.org>
255        Martin Quinson (mquinson#debian.org)
256
257
258
259Po4a Tools                        2021-11-01             Locale::Po4a::Po(3pm)
Impressum