1Locale::Po4a::Po(3) User Contributed Perl Documentation Locale::Po4a::Po(3)
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 documentation of the gettext
33 program.
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 none to
44 not produce any reference, noline to not specify the line number
45 (more accurately all line numbers are replaced by 1), counter to
46 replace line number by an increasing counter, and full to include
47 complete references.
48 Argument can be followed by a comma and either wrap or nowrap
50 keyword. References are written by default on a single line. The
51 wrap option wraps references on several lines, to mimic gettext
52 tools (xgettext and msgmerge). This option will become the default
53 in a future release, because it is more sensible. The nowrap
54 option is available so that users who want to keep the old behavior
55 can do so.
56 --msgid-bugs-address email@address
58 Set the report address for msgid bugs. By default, the created POT
59 files have no Report-Msgid-Bugs-To fields.
60 --copyright-holder string
62 Set the copyright holder in the POT header. The default value is
63 "Free Software Foundation, Inc."
64 --package-name string
66 Set the package name for the POT header. The default is "PACKAGE".
67 --package-version string
69 Set the package version for the POT header. The default is
70 "VERSION".
71
73 new()
74 Creates a new message catalog. If an argument is provided, it's the
75 name of a PO file we should load.
76 read($)
78 Reads a PO file (which name is given as argument). Previously
79 existing entries in self are not removed, the new ones are added to
80 the end of the catalog.
81 write($)
83 Writes the current catalog to the given file.
84 write_if_needed($$)
86 Like write, but if the PO or POT file already exists, the object
87 will be written in a temporary file which will be compared with the
88 existing file to check if the update is needed (this avoids to
89 change a POT just to update a line reference or the POT-Creation-
90 Date field).
91 gettextize($$)
93 This function produces one translated message catalog from two
94 catalogs, an original and a translation. This process is described
95 in po4a(7), section Gettextization: how does it work?.
96 filter($)
98 This function extracts a catalog from an existing one. Only the
99 entries having a reference in the given file will be placed in the
100 resulting catalog.
101 This function parses its argument, converts it to a Perl function
103 definition, evals this definition and filters the fields for which
104 this function returns true.
105 I love Perl sometimes ;)
107 to_utf8()
109 Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is
110 not specified in the PO file ("CHARSET" value), or if it's already
111 UTF-8 or ASCII.
112
114 gettext($%)
115 Request the translation of the string given as argument in the
116 current catalog. The function returns the original (untranslated)
117 string if the string was not found.
118 After the string to translate, you can pass a hash of extra
120 arguments. Here are the valid entries:
121 wrap
123 boolean indicating whether we can consider that whitespaces in
124 string are not important. If yes, the function canonizes the
125 string before looking for a translation, and wraps the result.
126 wrapcol
128 the column at which we should wrap (default: 76).
129 stats_get()
131 Returns statistics about the hit ratio of gettext since the last
132 time that stats_clear() was called. Please note that it's not the
133 same statistics than the one printed by msgfmt --statistic. Here,
134 it's statistics about recent usage of the PO file, while msgfmt
135 reports the status of the file. Example of use:
136 [some use of the PO file to translate stuff]
138 ($percent,$hit,$queries) = $pofile->stats_get();
140 print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
141 stats_clear()
143 Clears the statistics about gettext hits.
144
146 push(%)
147 Push a new entry at the end of the current catalog. The arguments
148 should form a hash table. The valid keys are:
149 msgid
151 the string in original language.
152 msgstr
154 the translation.
155 reference
157 an indication of where this string was found. Example:
158 file.c:46 (meaning in 'file.c' at line 46). It can be a space-
159 separated list in case of multiple occurrences.
160 comment
162 a comment added here manually (by the translators). The format
163 here is free.
164 automatic
166 a comment which was automatically added by the string
167 extraction program. See the --add-comments option of the
168 xgettext program for more information.
169 flags
171 space-separated list of all defined flags for this entry.
172 Valid flags are: c-text, python-text, lisp-text, elisp-text,
174 librep-text, smalltalk-text, java-text, awk-text, object-
175 pascal-text, ycp-text, tcl-text, wrap, no-wrap and fuzzy.
176 See the gettext documentation for their meaning.
178 type
180 this is mostly an internal argument: it is used while
181 gettextizing documents. The idea here is to parse both the
182 original and the translation into a PO object, and merge them,
183 using one's msgid as msgid and the other's msgid as msgstr. To
184 make sure that things get ok, each msgid in PO objects are
185 given a type, based on their structure (like "chapt", "sect1",
186 "p" and so on in DocBook). If the types of strings are not the
187 same, that means that both files do not share the same
188 structure, and the process reports an error.
189 This information is written as automatic comment in the PO file
191 since this gives to translators some context about the strings
192 to translate.
193 wrap
195 boolean indicating whether whitespaces can be mangled in
196 cosmetic reformattings. If true, the string is canonized before
197 use.
198 This information is written to the PO file using the wrap or
200 no-wrap flag.
201 wrapcol
203 the column at which we should wrap (default: 76).
204 This information is not written to the PO file.
206
208 count_entries()
209 Returns the number of entries in the catalog (without the header).
210 count_entries_doc()
212 Returns the number of entries in document. If a string appears
213 multiple times in the document, it will be counted multiple times
214 msgid($)
216 Returns the msgid of the given number.
217 msgid_doc($)
219 Returns the msgid with the given position in the document.
220 get_charset()
222 Returns the character set specified in the PO header. If it hasn't
223 been set, it will return "CHARSET".
224 set_charset($)
226 This sets the character set of the PO header to the value specified
227 in its first argument. If you never call this function (and no file
228 with a specified character set is read), the default value is left
229 to "CHARSET". This value doesn't change the behavior of this
230 module, it's just used to fill that field in the header, and to
231 return it in get_charset().
232
234 Denis Barbier <barbier@linuxfr.org>
235 Martin Quinson (mquinson#debian.org)
236perl v5.16.3 2014-06-10 Locale::Po4a::Po(3)