Locale::Po4a::Po - PO file manipulation module
# Read PO file
# Add an entry
$pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
'flags' => "wrap", 'reference'=>'file.c:46');
# Extract a translation
$pofile->gettext("Hello"); # returns 'bonjour'
# Write back to a file
Locale::Po4a::Po is a module that allows you to manipulate message catalogs. You
can load and write from/to a file (which extension is often po
can build new entries on the fly or request for the translation of a string.
For a more complete description of message catalogs in the PO format and their
use, please refer to the info documentation of the gettext program (node
This module is part of the po4a project, which objective is to use PO files
(designed at origin to ease the translation of program messages) to translate
everything, including documentation (man page, info manual), package
description, debconf templates, and everything which may benefit from this.
- Specify the reference format. Argument type can be
one of never to not produce any reference, file to only
specify the file without the line number, counter to replace line
number by an increasing counter, and full to include complete
references (default: full).
Argument can be followed by a comma and either wrap or nowrap
keyword. References are written by default on a single line. The
wrap option wraps references on several lines, to mimic
gettext tools ( xgettext and msgmerge). This option
will become the default in a future release, because it is more sensible.
The nowrap option is available so that users who want to keep the
old behavior can do so.
- --msgid-bugs-address email@address
- Set the report address for msgid bugs. By default, the
created POT files have no Report-Msgid-Bugs-To fields.
- --copyright-holder string
- Set the copyright holder in the POT header. The default
value is "Free Software Foundation, Inc."
- --package-name string
- Set the package name for the POT header. The default is
- --package-version string
- Set the package version for the POT header. The default is
- Creates a new message catalog. If an argument is provided,
it's the name of a PO file we should load.
- Reads a PO file (which name is given as argument).
Previously existing entries in self are not removed, the new ones are
added to the end of the catalog.
- Writes the current catalog to the given file.
- Like write, but if the PO or POT file already exists, the
object will be written in a temporary file which will be compared with the
existing file to check if the update is needed (this avoids to change a
POT just to update a line reference or the POT-Creation-Date field).
- This function produces one translated message catalog from
two catalogs, an original and a translation. This process is described in
po4a(7), section Gettextization: how does it work?.
- This function extracts a catalog from an existing one. Only
the entries having a reference in the given file will be placed in the
This function parses its argument, converts it to a Perl function
definition, evals this definition and filters the fields for which this
function returns true.
I love Perl sometimes ;)
- Recodes to UTF-8 the PO's msgstrs. Does nothing if the
charset is not specified in the PO file ("CHARSET" value), or if
it's already UTF-8 or ASCII.
- Request the translation of the string given as argument in
the current catalog. The function returns the original (untranslated)
string if the string was not found.
After the string to translate, you can pass a hash of extra arguments. Here
are the valid entries:
- boolean indicating whether we can consider that whitespaces
in string are not important. If yes, the function canonizes the string
before looking for a translation, and wraps the result.
- the column at which we should wrap (default: 76).
- Returns statistics about the hit ratio of gettext since the
last time that stats_clear() was called. Please note that it's not
the same statistics than the one printed by msgfmt --statistic. Here, it's
statistics about recent usage of the PO file, while msgfmt reports the
status of the file. Example of use:
[some use of the PO file to translate stuff]
($percent,$hit,$queries) = $pofile->stats_get();
print "So far, we found translations for $percent\% ($hit of $queries) of strings.\n";
- Clears the statistics about gettext hits.
- Push a new entry at the end of the current catalog. The
arguments should form a hash table. The valid keys are:
- the string in original language.
- the translation.
- an indication of where this string was found. Example:
file.c:46 (meaning in 'file.c' at line 46). It can be a space-separated
list in case of multiple occurrences.
- a comment added here manually (by the translators). The
format here is free.
- a comment which was automatically added by the string
extraction program. See the --add-comments option of the
xgettext program for more information.
- space-separated list of all defined flags for this entry.
Valid flags are: c-text, python-text, lisp-text,
elisp-text, librep-text, smalltalk-text,
java-text, awk-text, object-pascal-text,
ycp-text, tcl-text, wrap, no-wrap and
See the gettext documentation for their meaning.
- this is mostly an internal argument: it is used while
gettextizing documents. The idea here is to parse both the original and
the translation into a PO object, and merge them, using one's msgid as
msgid and the other's msgid as msgstr. To make sure that things get ok,
each msgid in PO objects are given a type, based on their structure (like
"chapt", "sect1", "p" and so on in DocBook).
If the types of strings are not the same, that means that both files do
not share the same structure, and the process reports an error.
This information is written as automatic comment in the PO file since this
gives to translators some context about the strings to translate.
- boolean indicating whether whitespaces can be mangled in
cosmetic reformattings. If true, the string is canonized before use.
This information is written to the PO file using the wrap or
- the column at which we should wrap (default: 76).
This information is not written to the PO file.
- Returns the number of entries in the catalog (without the
- Returns the number of entries in document. If a string
appears multiple times in the document, it will be counted multiple
- Returns ($uptodate, $diagnostic) with $uptodate indicating
whether all msgid of the current po file are also present in the one
passed as parameter (all other fields are ignored in the file comparison).
Informally, if $uptodate returns false, then the po files would be changed
when going through po4a-updatepo.
If $uptodate is false, then $diagnostic contains a diagnostic of why this is
- Returns the msgid of the given number.
- Returns the msgid with the given position in the
- Returns the character set specified in the PO header. If it
hasn't been set, it will return "CHARSET".
- This sets the character set of the PO header to the value
specified in its first argument. If you never call this function (and no
file with a specified character set is read), the default value is left to
"CHARSET". This value doesn't change the behavior of this
module, it's just used to fill that field in the header, and to return it
Denis Barbier <email@example.com>
Martin Quinson (mquinson#debian.org)