NAME

SYNOPSIS

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Read PO file
    $pofile->read('file.po');

    # 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
    $pofile->write('otherfile.po');

DESCRIPTION

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 "`PO Files"').

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.

OPTIONS ACCEPTED BY THIS MODULE

--porefs type

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).

--wrap-po no|newlines|number (default: 76)

Specify how the po file should be wrapped. This gives the choice between either files that are nicely wrapped but could lead to git conflicts, or files that are easier to handle automatically, but harder to read for humans.

Historically, the gettext suite has reformatted the po files at the 77th column for cosmetics. This option specifies the behavior of po4a. If set to a numerical value, po4a will wrap the po file after this column and after newlines in the content. If set to newlines, po4a will only split the msgid and msgstr after newlines in the content. If set to no, po4a will not wrap the po file at all. The reference comments are always wrapped by the gettext tools that we use internally.

Note that this option has no impact on how the msgid and msgstr are wrapped, ie on how newlines are added to the content of these strings.

--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".

--package-version string

Set the package version for the POT header. The default is "VERSION".

Functions concerning entire message catalogs

new()

Creates a new message catalog. If an argument is provided, it's the name of a PO file we should load.

read($)

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.

write($)

Writes the current catalog to the given file.

write_if_needed($$)

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).

gettextize($$)

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?.

filter($)

This function extracts a catalog from an existing one. Only the entries having a reference in the given file will be placed in the resulting catalog.

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 ;)

to_utf8()

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.

Functions to use a message catalog for translations

gettext($%)

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:

stats_get()

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";
    

stats_clear()

Clears the statistics about gettext hits.

Functions to build a message catalog

push(%)

Push a new entry at the end of the current catalog. The arguments should form a hash table. The valid keys are:

Miscellaneous functions

count_entries()

Returns the number of entries in the catalog (without the header).

count_entries_doc()

Returns the number of entries in document. If a string appears multiple times in the document, it will be counted multiple times.

equals_msgid(po)

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 so.

msgid($)

Returns the msgid of the given number.

msgid_doc($)

Returns the msgid with the given position in the document.

get_charset()

Returns the character set specified in the PO header. If it hasn't been set, it will return "UTF-8".

set_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 "UTF-8". 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 in get_charset().

AUTHORS

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)