phpman > perldoc > Locale::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>,[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
    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 <EMAIL@ADDRESS>\\n" .
                    "Language-Team: LANGUAGE <LL AT 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.

AUTHOR
    Maintainer: Ken Prows, perl AT xev.net

    Original version by: Alan Schwartz, alansz AT 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).