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 cat‐
27 alogs. You can load and write from/to a file (which extension is often
28 po), you can build new entries on the fly or request for the transla‐
29 tion 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 pro‐
33 gram.
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 man‐
38 ual), package description, debconf templates, and everything which may
39 benefit from this.
40
42 porefs
43 This specifies the reference format. It can be one of 'none' to not
44 produce any reference, 'noline' to not specify the line number, and
45 'full' to include complete references.
46
48 new()
49 Creates a new message catalog. If an argument is provided, it's the
50 name of a po file we should load.
51 read($)
53 Reads a po file (which name is given as argument). Previously
54 existing entries in self are not removed, the new ones are added to
55 the end of the catalog.
56 write($)
58 Writes the current catalog to the given file.
59 write_if_needed($$)
61 Like write, but if the PO or POT file already exists, the object
62 will be written in a temporary file which will be compared with the
63 existing file to check that the update is needed (this avoids to
64 change a POT just to update a line reference or the POT-Creation-
65 Date field).
66 gettextize($$)
68 This function produces one translated message catalog from two cat‐
69 alogs, an original and a translation. This process is described in
70 po4a(7), section Gettextization: how does it work?.
71 filter($)
73 This function extracts a catalog from an existing one. Only the
74 entries having a reference in the given file will be placed in the
75 resulting catalog.
76 This function parses its argument, converts it to a perl function
78 definition, eval this definition and filter the fields for which
79 this function returns true.
80 I love perl sometimes ;)
82 to_utf8()
84 Recodes to utf-8 the po's msgstrs. Does nothing if the charset is
85 not specified in the po file ("CHARSET" value), or if it's already
86 utf-8 or ascii.
87
89 gettext($%)
90 Request the translation of the string given as argument in the cur‐
91 rent catalog. The function returns the original (untranslated)
92 string if the string was not found.
93 After the string to translate, you can pass a hash of extra argu‐
95 ments. Here are the valid entries:
96 wrap
98 boolean indicating whether we can consider that whitespaces in
99 string are not important. If yes, the function canonizes the
100 string before looking for a translation, and wraps the result.
101 wrapcol
103 The column at which we should wrap (default: 76).
104 stats_get()
106 Returns statistics about the hit ratio of gettext since the last
107 time that stats_clear() was called. Please note that it's not the
108 same statistics than the one printed by msgfmt --statistic. Here,
109 it's statistics about recent usage of the po file, while msgfmt
110 reports the status of the file. Example of use:
111 [some use of the po file to translate stuff]
113 ($percent,$hit,$queries) = $pofile->stats_get();
115 print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
116 stats_clear()
118 Clears the statistics about gettext hits.
119
121 push(%)
122 Push a new entry at the end of the current catalog. The arguments
123 should form a hash table. The valid keys are:
124 msgid
126 the string in original language.
127 msgstr
129 the translation.
130 reference
132 an indication of where this string was found. Example:
133 file.c:46 (meaning in 'file.c' at line 46). It can be a space-
134 separated list in case of multiple occurrences.
135 comment
137 a comment added here manually (by the translators). The format
138 here is free.
139 automatic
141 a comment which was automatically added by the string extrac‐
142 tion program. See the --add-comments option of the xgettext
143 program for more information.
144 flags
146 space-separated list of all defined flags for this entry.
147 Valid flags are: c-text, python-text, lisp-text, elisp-text,
149 librep-text, smalltalk-text, java-text, awk-text, object-pas‐
150 cal-text, ycp-text, tcl-text, wrap, no-wrap and fuzzy.
151 See the gettext documentation for their meaning.
153 type
155 This is mostly an internal argument: it is used while gettex‐
156 tizing documents. The idea here is to parse both the original
157 and the translation into a po object, and merge them, using
158 one's msgid as msgid and the other's msgid as msgstr. To make
159 sure that things get ok, each msgid in po objects are given a
160 type, based on their structure (like "chapt", "sect1", "p" and
161 so on in docbook). If the types of strings are not the same,
162 that means that both files do not share the same structure, and
163 the process reports an error.
164 This information is written as automatic comment in the po file
166 since this gives to translators some context about the strings
167 to translate.
168 wrap
170 boolean indicating whether whitespaces can be mangled in cos‐
171 metic reformattings. If true, the string is canonized before
172 use.
173 This information is written to the po file using the 'wrap' or
175 'no-wrap' flag.
176 wrapcol
178 The column at which we should wrap (default: 76).
179 This information is not written to the po file.
181
183 count_entries()
184 Returns the number of entries in the catalog (without the header).
185 count_entries_doc()
187 Returns the number of entries in document. If a string appears mul‐
188 tiple times in the document, it will be counted multiple times
189 msgid($)
191 Returns the msgid of the given number.
192 msgid_doc($)
194 Returns the msgid with the given position in the document.
195 get_charset()
197 Returns the character set specified in the po header. If it hasn't
198 been set, it will return "CHARSET".
199 set_charset($)
201 This sets the character set of the po header to the value specified
202 in its first argument. If you never call this function (and no file
203 with a specified character set is read), the default value is left
204 to "CHARSET". This value doesn't change the behavior of this mod‐
205 ule, it's just used to fill that field in the header, and to return
206 it in get_charset().
207
209 Denis Barbier <barbier@linuxfr.org>
210 Martin Quinson (mquinson#debian.org)
211perl v5.8.8 2008-06-01 Locale::Po4a::Po(3)