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->c_format([value]);
  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

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

msgid_plural

Set or get the untranslated plural string from the object.

msgstr

Set or get the translated string from the object.

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',
        }
    );

comment

Set or get translator comments from the object.

automatic

Set or get automatic comments from the object (inserted by emacs po-mode or xgettext).

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 blank or undefined implies neither.

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

Alan Schwartz, alansz@pennmush.org

BUGS

If you load_file then save_file, the output file may have slight cosmetic differences from the input file (an extra blank line here or there).

SEE ALSO

xgettext(1).