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 filter($)
103 This function extracts a catalog from an existing one. Only the
104 entries having a reference in the given file will be placed in the
105 resulting catalog.
106 This function parses its argument, converts it to a Perl function
108 definition, evals this definition and filters the fields for which
109 this function returns true.
110 I love Perl sometimes ;)
112 to_utf8()
114 Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is
115 not specified in the PO file ("CHARSET" value), or if it's already
116 UTF-8 or ASCII.
117
119 gettext($%)
120 Request the translation of the string given as argument in the
121 current catalog. The function returns the original (untranslated)
122 string if the string was not found.
123 After the string to translate, you can pass a hash of extra
125 arguments. Here are the valid entries:
126 wrap
128 boolean indicating whether we can consider that whitespaces in
129 string are not important. If yes, the function canonizes the
130 string before looking for a translation, and wraps the result.
131 wrapcol
133 the column at which we should wrap (default: 76).
134 stats_get()
136 Returns statistics about the hit ratio of gettext since the last
137 time that stats_clear() was called. Please note that it's not the
138 same statistics than the one printed by msgfmt --statistic. Here,
139 it's statistics about recent usage of the PO file, while msgfmt
140 reports the status of the file. Example of use:
141 [some use of the PO file to translate stuff]
143 ($percent,$hit,$queries) = $pofile->stats_get();
145 print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
146 stats_clear()
148 Clears the statistics about gettext hits.
149
151 push(%)
152 Push a new entry at the end of the current catalog. The arguments
153 should form a hash table. The valid keys are:
154 msgid
156 the string in original language.
157 msgstr
159 the translation.
160 reference
162 an indication of where this string was found. Example:
163 file.c:46 (meaning in 'file.c' at line 46). It can be a space-
164 separated list in case of multiple occurrences.
165 comment
167 a comment added here manually (by the translators). The format
168 here is free.
169 automatic
171 a comment which was automatically added by the string
172 extraction program. See the --add-comments option of the
173 xgettext program for more information.
174 flags
176 space-separated list of all defined flags for this entry.
177 Valid flags are: c-text, python-text, lisp-text, elisp-text,
179 librep-text, smalltalk-text, java-text, awk-text, object-
180 pascal-text, ycp-text, tcl-text, wrap, no-wrap and fuzzy.
181 See the gettext documentation for their meaning.
183 type
185 this is mostly an internal argument: it is used while
186 gettextizing documents. The idea here is to parse both the
187 original and the translation into a PO object, and merge them,
188 using one's msgid as msgid and the other's msgid as msgstr. To
189 make sure that things get ok, each msgid in PO objects are
190 given a type, based on their structure (like "chapt", "sect1",
191 "p" and so on in DocBook). If the types of strings are not the
192 same, that means that both files do not share the same
193 structure, and the process reports an error.
194 This information is written as automatic comment in the PO file
196 since this gives to translators some context about the strings
197 to translate.
198 wrap
200 boolean indicating whether whitespaces can be mangled in
201 cosmetic reformattings. If true, the string is canonized before
202 use.
203 This information is written to the PO file using the wrap or
205 no-wrap flag.
206 wrapcol
208 the column at which we should wrap (default: 76).
209 This information is not written to the PO file.
211
213 count_entries()
214 Returns the number of entries in the catalog (without the header).
215 count_entries_doc()
217 Returns the number of entries in document. If a string appears
218 multiple times in the document, it will be counted multiple times.
219 msgid($)
221 Returns the msgid of the given number.
222 msgid_doc($)
224 Returns the msgid with the given position in the document.
225 type_doc($)
227 Returns the type of the msgid with the given position in the
228 document. This is probably only useful to gettextization, and it's
229 stored separately from {$msgid}{'type'} because the later location
230 may be overwritten by another type when the $msgid is duplicated in
231 the master document.
232 get_charset()
234 Returns the character set specified in the PO header. If it hasn't
235 been set, it will return "UTF-8".
236 set_charset($)
238 This sets the character set of the PO header to the value specified
239 in its first argument. If you never call this function (and no file
240 with a specified character set is read), the default value is left
241 to "UTF-8". This value doesn't change the behavior of this module,
242 it's just used to fill that field in the header, and to return it
243 in get_charset().
244
246 Denis Barbier <barbier@linuxfr.org>
247 Martin Quinson (mquinson#debian.org)
248Po4a Tools 2023-01-23 Locale::Po4a::Po(3pm)