--- name: "Locale::PO" section: "3pm" platform: "linux" package: "perl-locale-po" version: "0.27-13" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Locale::PO" --- # Locale::PO(3pm) Perl module for manipulating .po entries from GNU gettext ## 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(,[encoding]); $href = Locale::PO->load_file_ashash(,[encoding]); Locale::PO->save_file_fromarray(,$aref,[encoding]); Locale::PO->save_file_fromhash(,$href,[encoding]); ``` ## 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, 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 \\n" . "Language-Team: LANGUAGE \\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. ## 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)](/xgettext/1.md).