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[,wrap|nowrap]
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           Argument can be followed by a comma and either wrap or nowrap
49           keyword.  References are written by default on a single line.  The
50           wrap option wraps references on several lines, to mimic gettext
51           tools (xgettext and msgmerge).  This option will become the default
52           in a future release, because it is more sensible.  The nowrap
53           option is available so that users who want to keep the old behavior
54           can do so.
55
56       --msgid-bugs-address email@address
57           Set the report address for msgid bugs. By default, the created POT
58           files have no Report-Msgid-Bugs-To fields.
59
60       --copyright-holder string
61           Set the copyright holder in the POT header. The default value is
62           "Free Software Foundation, Inc."
63
64       --package-name string
65           Set the package name for the POT header. The default is "PACKAGE".
66
67       --package-version string
68           Set the package version for the POT header. The default is
69           "VERSION".
70

Functions concerning entire message catalogs

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

Functions to use a message catalog for translations

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

Functions to build a message catalog

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

Miscellaneous functions

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

AUTHORS

243        Denis Barbier <barbier@linuxfr.org>
244        Martin Quinson (mquinson#debian.org)
245
246
247
248Po4a Tools                        2018-09-24             Locale::Po4a::Po(3pm)
Impressum