1LOCALE::PO4A::PO.3PM(1)User Contributed Perl DocumentatioLnOCALE::PO4A::PO.3PM(1)
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       filter($)
103           This function extracts a catalog from an existing one. Only the
104           entries having a reference in the given file will be placed in the
105           resulting catalog.
106
107           This function parses its argument, converts it to a Perl function
108           definition, evals this definition and filters the fields for which
109           this function returns true.
110
111           I love Perl sometimes ;)
112
113       to_utf8()
114           Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is
115           not specified in the PO file ("CHARSET" value), or if it's already
116           UTF-8 or ASCII.
117

Functions to use a message catalog for translations

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

Functions to build a message catalog

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

Miscellaneous functions

213       count_entries()
214           Returns the number of entries in the catalog (without the header).
215
216       count_entries_doc()
217           Returns the number of entries in document. If a string appears
218           multiple times in the document, it will be counted multiple times.
219
220       msgid($)
221           Returns the msgid of the given number.
222
223       msgid_doc($)
224           Returns the msgid with the given position in the document.
225
226       type_doc($)
227           Returns the type of the msgid with the given position in the
228           document. This is probably only useful to gettextization, and it's
229           stored separately from {$msgid}{'type'} because the later location
230           may be overwritten by another type when the $msgid is duplicated in
231           the master document.
232
233       get_charset()
234           Returns the character set specified in the PO header. If it hasn't
235           been set, it will return "UTF-8".
236
237       set_charset($)
238           This sets the character set of the PO header to the value specified
239           in its first argument. If you never call this function (and no file
240           with a specified character set is read), the default value is left
241           to "UTF-8". This value doesn't change the behavior of this module,
242           it's just used to fill that field in the header, and to return it
243           in get_charset().
244

AUTHORS

246        Denis Barbier <barbier@linuxfr.org>
247        Martin Quinson (mquinson#debian.org)
248
249
250
251perl v5.38.0                      2023-10-12           LOCALE::PO4A::PO.3PM(1)
Impressum