1Locale::Po4a::Po(3pm) Po4a Tools Locale::Po4a::Po(3pm)
2
6 Locale::Po4a::Po - PO file manipulation module
7
9 use Locale::Po4a::Po;
10 my $pofile=Locale::Po4a::Po->new();
11 # Read PO file
13 $pofile->read('file.po');
14 # Add an entry
16 $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
17 'flags' => "wrap", 'reference'=>'file.c:46');
18 # Extract a translation
20 $pofile->gettext("Hello"); # returns 'bonjour'
21 # Write back to a file
23 $pofile->write('otherfile.po');
24
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 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 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
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 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 --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 --copyright-holder string
61 Set the copyright holder in the POT header. The default value is
62 "Free Software Foundation, Inc."
63 --package-name string
65 Set the package name for the POT header. The default is "PACKAGE".
66 --package-version string
68 Set the package version for the POT header. The default is
69 "VERSION".
70
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 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 write($)
82 Writes the current catalog to the given file.
83 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 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 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 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 I love Perl sometimes ;)
106 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
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 After the string to translate, you can pass a hash of extra
119 arguments. Here are the valid entries:
120 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 wrapcol
127 the column at which we should wrap (default: 76).
128 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 [some use of the PO file to translate stuff]
137 ($percent,$hit,$queries) = $pofile->stats_get();
139 print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
140 stats_clear()
142 Clears the statistics about gettext hits.
143
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 msgid
150 the string in original language.
151 msgstr
153 the translation.
154 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 comment
161 a comment added here manually (by the translators). The format
162 here is free.
163 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 flags
170 space-separated list of all defined flags for this entry.
171 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 See the gettext documentation for their meaning.
177 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 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 wrap
194 boolean indicating whether whitespaces can be mangled in
195 cosmetic reformattings. If true, the string is canonized before
196 use.
197 This information is written to the PO file using the wrap or
199 no-wrap flag.
200 wrapcol
202 the column at which we should wrap (default: 76).
203 This information is not written to the PO file.
205
207 count_entries()
208 Returns the number of entries in the catalog (without the header).
209 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 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 If $uptodate is false, then $diagnostic contains a diagnostic of
222 why this is so.
223 msgid($)
225 Returns the msgid of the given number.
226 msgid_doc($)
228 Returns the msgid with the given position in the document.
229 get_charset()
231 Returns the character set specified in the PO header. If it hasn't
232 been set, it will return "CHARSET".
233 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
243 Denis Barbier <barbier@linuxfr.org>
244 Martin Quinson (mquinson#debian.org)
245Po4a Tools 2018-09-24 Locale::Po4a::Po(3pm)