Locale::PO - Perl module for manipulating .po entries from GNU gettext
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>,[encoding]);
$href = Locale::PO->load_file_ashash(<filename>,[encoding]);
Locale::PO->save_file_fromarray(<filename>,$aref,[encoding]);
Locale::PO->save_file_fromhash(<filename>,$href,[encoding]);
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.
- 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, msgid_plural, msgstr, msgctxt, comment, automatic,
reference, fuzzy_msgctxt, fuzzy_msgid, fuzzy_msgid_plural,
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.
- fuzzy_msgid
-
Set or get the outdated untranslated string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
- fuzzy_msgid_plural
-
Set or get the outdated untranslated plural string from the object.
This method expects the new string in unquoted form but returns the current string in quoted form.
- fuzzy_msgctxt
-
Set or get the outdated 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
``\n''. 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
``\n''. 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. Accepts an optional encoding parameter (e.g.
``utf8'') which defines how the po-file's input stream will be configured.
- 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. Accepts an optional encoding parameter (e.g.
``utf8'') which defines how the po-file's input stream will be configured.
- 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. Accepts an optional
encoding parameter (e.g. ``utf8'') which defines how the po-file's output
stream will be configured.
- 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. Accepts an optional
encoding parameter (e.g. ``utf8'') which defines how the po-file's output
stream will be configured.
Maintainer: Ken Prows, perl@xev.net
Original version by: Alan Schwartz, alansz@pennmush.org
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.
xgettext(1).
|