PO(3pm) User Contributed Perl Documentation PO(3pm)
NAME
Locale::PO - Perl module for manipulating .po entries from GNU gettext
SYNOPSIS
use Locale::PO;
$po = new Locale::PO([-option=>value,...])
[$string =] $po->msgid([new string]);
[$string =] $po->msgstr([new string]);
[$string =] $po->comment([new string]);
[$string =] $po->automatic([new string]);
[$string =] $po->reference([new string]);
[$value =] $po->fuzzy([value]);
[$value =] $po->add_flag('c-format');
print $po->dump;
$quoted_string = $po->quote($string);
$string = $po->dequote($quoted_string);
$aref = Locale::PO->load_file_asarray(<filename>);
$href = Locale::PO->load_file_ashash(<filename>);
Locale::PO->save_file_fromarray(<filename>,$aref);
Locale::PO->save_file_fromhash(<filename>,$href);
DESCRIPTION
This module simplifies management of GNU gettext .po files and is an alternative to using emacs po-mode. It provides an object-oriented
interface in which each entry in a .po file is a Locale::PO object.
METHODS
new
my Locale::PO $po = new Locale::PO;
my Locale::PO $po = new Locale::PO(%options);
Create a new Locale::PO object to represent a po entry. You can optionally set the attributes of the entry by passing a list/hash of
the form:
-option=>value, -option=>value, etc.
Where options are msgid, msgstr, msgctxt, comment, automatic, reference, fuzzy, and c-format. See accessor methods below.
To generate a po file header, add an entry with an empty msgid, like this:
$po = new Locale::PO(-msgid=>'', -msgstr=>
"Project-Id-Version: PACKAGE VERSION\n" .
"PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE\n" .
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" .
"Language-Team: LANGUAGE <LL@li.org>\n" .
"MIME-Version: 1.0\n" .
"Content-Type: text/plain; charset=CHARSET\n" .
"Content-Transfer-Encoding: ENCODING\n");
msgid
Set or get the untranslated string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
msgid_plural
Set or get the untranslated plural string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
msgstr
Set or get the translated string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
msgstr_n
Get or set the translations if there are purals involved. Takes and returns a hashref where the keys are the 'N' case and the values
are the strings. eg:
$po->msgstr_n(
{
0 => 'found %d plural translations',
1 => 'found %d singular translation',
}
);
This method expects the new strings in unquoted form but returns the current strings in quoted form.
msgctxt
Set or get the translation context string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
obsolete
Returns 1 if the entry is obsolete. Obsolete entries have their msgid, msgid_plural, msgstr, msgstr_n and msgctxt lines commented out
with "#~"
When using load_file_ashash, non-obsolete entries will always replace obsolete entries with the same msgid.
comment
Set or get translator comments from the object.
If there are no such comments, then the value is undef. Otherwise, the value is a string that contains the comment lines delimited
with "
". The string includes neither the "# " at the beginning of each comment line nor the newline at the end of the last comment
line.
automatic
Set or get automatic comments from the object (inserted by emacs po-mode or xgettext).
If there are no such comments, then the value is undef. Otherwise, the value is a string that contains the comment lines delimited
with "
". The string includes neither the "#. " at the beginning of each comment line nor the newline at the end of the last comment
line.
reference
Set or get reference marking comments from the object (inserted by emacs po-mode or gettext).
fuzzy
Set or get the fuzzy flag on the object ("check this translation"). When setting, use 1 to turn on fuzzy, and 0 to turn it off.
c_format
Set or get the c-format or no-c-format flag on the object.
This can take 3 values: 1 implies c-format, 0 implies no-c-format, and undefined implies neither.
php_format
Set or get the php-format or no-php-format flag on the object.
This can take 3 values: 1 implies php-format, 0 implies no-php-format, and undefined implies neither.
has_flag
if ($po->has_flag('perl-format')) {
...
}
Returns true if the flag exists in the entry's #~ comment
add_flag
$po->add_flag('perl-format');
Adds the flag to the #~ comment
remove_flag
$po->remove_flag('perl-format');
Removes the flag from the #~ comment
loaded_line_number
When using one of the load_file_as* methods, this will return the line number that the entry started at in the file.
dump
Returns the entry as a string, suitable for output to a po file.
quote
Applies po quotation rules to a string, and returns the quoted string. The quoted string will have all existing double-quote characters
escaped by backslashes, and will be enclosed in double quotes.
dequote
Returns a quoted po string to its natural form.
load_file_asarray
Given the filename of a po-file, reads the file and returns a reference to a list of Locale::PO objects corresponding to the contents
of the file, in the same order.
load_file_ashash
Given the filename of a po-file, reads the file and returns a reference to a hash of Locale::PO objects corresponding to the contents
of the file. The hash keys are the untranslated strings, so this is a cheap way to remove duplicates. The method will prefer to keep
entries that have been translated.
save_file_fromarray
Given a filename and a reference to a list of Locale::PO objects, saves those objects to the file, creating a po-file.
save_file_fromhash
Given a filename and a reference to a hash of Locale::PO objects, saves those objects to the file, creating a po-file. The entries are
sorted alphabetically by untranslated string.
AUTHOR
Maintainer: Ken Prows, perl@xev.net
Original version by: Alan Schwartz, alansz@pennmush.org
BUGS
If you load_file_as* then save_file_from*, the output file may have slight cosmetic differences from the input file (an extra blank line
here or there).
msgid, msgid_plural, msgstr, msgstr_n and msgctxt expect a non-quoted string as input, but return quoted strings. I'm hesitant to change
this in fear of breaking the modules/scripts of people already using Locale::PO.
Locale::PO requires blank lines between entries, but Uniforum style PO files don't have any.
Please submit all bug requests using CPAN's ticketing system.
SEE ALSO
xgettext(1).
perl v5.10.0 2008-05-19 PO(3pm)