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
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
69 catalogs, an original and a translation. This process is described
70 in 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
91 current 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
95 arguments. 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
142 extraction program. See the --add-comments option of the
143 xgettext 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-
150 pascal-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
156 gettextizing documents. The idea here is to parse both the
157 original and the translation into a PO object, and merge them,
158 using one's msgid as msgid and the other's msgid as msgstr. To
159 make sure that things get ok, each msgid in PO objects are
160 given a type, based on their structure (like "chapt", "sect1",
161 "p" and so on in DocBook). If the types of strings are not the
162 same, that means that both files do not share the same
163 structure, and 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
171 cosmetic 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
188 multiple 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
205 module, it's just used to fill that field in the header, and to
206 return it in get_charset().
207
209 Denis Barbier <barbier@linuxfr.org>
210 Martin Quinson (mquinson#debian.org)
211perl v5.12.2 2010-12-01 Locale::Po4a::Po(3)