Locale::PO(3pm)

NAME ✨

Locale::PO — it's a Perl module (yes bestie, a 3pm one) for manipulating .po entries from GNU gettext. Translation files but make it object-oriented. 💅

---

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>,[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]);

---

DESCRIPTION 💖

Okay so, this module simplifies management of GNU gettext .po files, and honestly? It's a whole alternative to using emacs po-mode (no shade to po-mode, but like… no). It gives you an object-oriented interface where every single entry in a .po file is its own Locale::PO object. One entry, one icon, one little main character. 👑

---

METHODS 🦋

new

my Locale::PO $po = new Locale::PO;
my Locale::PO $po = new Locale::PO(%options);

Create a brand new Locale::PO object to represent a po entry. You can optionally set the entry's attributes right away by passing a list/hash shaped like:

-option=>value, -option=>value, etc.

Where the options are msgid, msgid_plural, msgstr, msgctxt, comment, automatic, reference, fuzzy_msgctxt, fuzzy_msgid, fuzzy_msgid_plural, fuzzy, and c-format. See the accessor methods below, they spill all the tea. 🫖

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.

Heads up though: this method expects the new string in unquoted form, but it returns the current string in quoted form. Yes, it's giving bilingual. 😭

msgid_plural

Set or get the untranslated plural string from the object.

Same energy as above: new string comes in unquoted, current string comes back quoted.

msgstr

Set or get the translated string from the object.

Again: expects the new string unquoted, returns the current string quoted. It's a pattern, bestie.

msgstr_n

Get or set the translations when plurals are involved. It 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.

Expects the new string unquoted, returns the current string quoted. ✨

fuzzy_msgid

Set or get the outdated untranslated string from the object.

Expects the new string unquoted, returns the current string quoted.

fuzzy_msgid_plural

Set or get the outdated untranslated plural string from the object.

Expects the new string unquoted, returns the current string quoted.

fuzzy_msgctxt

Set or get the outdated translation context string from the object.

Expects the new string unquoted, returns the current string quoted.

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. So the glow-up always wins. 💅

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. Sneaky little trimming situation. 🙈

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. It's a vibe check for translations fr fr. 🔥

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. Iconic. 👑

remove_flag

$po->remove_flag('perl-format');

Removes the flag from the #~ comment. Not every flag deserves to stay. 💀

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. So you can always find your way back home. 🎀

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. Un-glow-up, but make it correct. 🦋

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.

---

AUTHOR 💜

Maintainer: Ken Prows, perl@xev.net

Original version by: Alan Schwartz, alansz@pennmush.org

Shoutout to the OGs. 🫶

---

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). It's not broken, it's just got a slightly different outfit on. 💅

msgid, msgid_plural, msgstr, msgstr_n and msgctxt expect a non-quoted string as input, but return quoted strings. The author is hesitant to change this in fear of breaking the modules/scripts of people already using Locale::PO. (Respect the legacy, bestie. 😭)

Locale::PO requires blank lines between entries, but Uniforum style PO files don't have any. So like… that's a whole thing.

Please submit all bug requests using CPAN's ticketing system. Fr fr, that's the way. 🎀

---

SEE ALSO 👑

xgettext(1).

---

And that's the whole page, bestie — this one's from perl v5.26.2, dated 2018-08-27, and it's the Locale::PO(3pm) manual. Now go forth and translate. Slay. ✨💖🦋