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
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 --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 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 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 --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 --copyright-holder string
72 Set the copyright holder in the POT header. The default value is
73 "Free Software Foundation, Inc."
74 --package-name string
76 Set the package name for the POT header. The default is "PACKAGE".
77 --package-version string
79 Set the package version for the POT header. The default is
80 "VERSION".
81
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 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 write($)
93 Writes the current catalog to the given file.
94 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 gettextize($$)
103 This function produces one translated message catalog from two
104 catalogs, an original and a translation. This process is described
105 in po4a(7), section Gettextization: how does it work?.
106 filter($)
108 This function extracts a catalog from an existing one. Only the
109 entries having a reference in the given file will be placed in the
110 resulting catalog.
111 This function parses its argument, converts it to a Perl function
113 definition, evals this definition and filters the fields for which
114 this function returns true.
115 I love Perl sometimes ;)
117 to_utf8()
119 Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is
120 not specified in the PO file ("CHARSET" value), or if it's already
121 UTF-8 or ASCII.
122
124 gettext($%)
125 Request the translation of the string given as argument in the
126 current catalog. The function returns the original (untranslated)
127 string if the string was not found.
128 After the string to translate, you can pass a hash of extra
130 arguments. Here are the valid entries:
131 wrap
133 boolean indicating whether we can consider that whitespaces in
134 string are not important. If yes, the function canonizes the
135 string before looking for a translation, and wraps the result.
136 wrapcol
138 the column at which we should wrap (default: 76).
139 stats_get()
141 Returns statistics about the hit ratio of gettext since the last
142 time that stats_clear() was called. Please note that it's not the
143 same statistics than the one printed by msgfmt --statistic. Here,
144 it's statistics about recent usage of the PO file, while msgfmt
145 reports the status of the file. Example of use:
146 [some use of the PO file to translate stuff]
148 ($percent,$hit,$queries) = $pofile->stats_get();
150 print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
151 stats_clear()
153 Clears the statistics about gettext hits.
154
156 push(%)
157 Push a new entry at the end of the current catalog. The arguments
158 should form a hash table. The valid keys are:
159 msgid
161 the string in original language.
162 msgstr
164 the translation.
165 reference
167 an indication of where this string was found. Example:
168 file.c:46 (meaning in 'file.c' at line 46). It can be a space-
169 separated list in case of multiple occurrences.
170 comment
172 a comment added here manually (by the translators). The format
173 here is free.
174 automatic
176 a comment which was automatically added by the string
177 extraction program. See the --add-comments option of the
178 xgettext program for more information.
179 flags
181 space-separated list of all defined flags for this entry.
182 Valid flags are: c-text, python-text, lisp-text, elisp-text,
184 librep-text, smalltalk-text, java-text, awk-text, object-
185 pascal-text, ycp-text, tcl-text, wrap, no-wrap and fuzzy.
186 See the gettext documentation for their meaning.
188 type
190 this is mostly an internal argument: it is used while
191 gettextizing documents. The idea here is to parse both the
192 original and the translation into a PO object, and merge them,
193 using one's msgid as msgid and the other's msgid as msgstr. To
194 make sure that things get ok, each msgid in PO objects are
195 given a type, based on their structure (like "chapt", "sect1",
196 "p" and so on in DocBook). If the types of strings are not the
197 same, that means that both files do not share the same
198 structure, and the process reports an error.
199 This information is written as automatic comment in the PO file
201 since this gives to translators some context about the strings
202 to translate.
203 wrap
205 boolean indicating whether whitespaces can be mangled in
206 cosmetic reformattings. If true, the string is canonized before
207 use.
208 This information is written to the PO file using the wrap or
210 no-wrap flag.
211 wrapcol
213 the column at which we should wrap (default: 76).
214 This information is not written to the PO file.
216
218 count_entries()
219 Returns the number of entries in the catalog (without the header).
220 count_entries_doc()
222 Returns the number of entries in document. If a string appears
223 multiple times in the document, it will be counted multiple times.
224 equals_msgid(po)
226 Returns ($uptodate, $diagnostic) with $uptodate indicating whether
227 all msgid of the current po file are also present in the one passed
228 as parameter (all other fields are ignored in the file comparison).
229 Informally, if $uptodate returns false, then the po files would be
230 changed when going through po4a-updatepo.
231 If $uptodate is false, then $diagnostic contains a diagnostic of
233 why this is so.
234 msgid($)
236 Returns the msgid of the given number.
237 msgid_doc($)
239 Returns the msgid with the given position in the document.
240 get_charset()
242 Returns the character set specified in the PO header. If it hasn't
243 been set, it will return "UTF-8".
244 set_charset($)
246 This sets the character set of the PO header to the value specified
247 in its first argument. If you never call this function (and no file
248 with a specified character set is read), the default value is left
249 to "UTF-8". This value doesn't change the behavior of this module,
250 it's just used to fill that field in the header, and to return it
251 in get_charset().
252
254 Denis Barbier <barbier@linuxfr.org>
255 Martin Quinson (mquinson#debian.org)
256Po4a Tools 2021-02-23 Locale::Po4a::Po(3pm)