NAME

DBD::PO::Locale::PO - Perl module for manipulating .po entries from GNU gettext

$Id: PO.pm 412 2009-08-29 08:58:24Z steffenw $

$HeadURL: https://dbd-po.svn.sourceforge.net/svnroot/dbd-po/trunk/DBD-PO/lib/DBD/PO/Locale/PO.pm $

VERSION

v0.21.5

SYNOPSIS

require DBD::PO::Locale::PO;

$po = DBD::PO::Locale::PO->new([eol => $eol, ['-option' => 'value', ...]])
[$string =] $po->comment(['new string']);
[$string =] $po->automatic(['new string']);
[$string =] $po->reference(['new string']);
[$string =] $po->msgctxt(['new string']);
[$string =] $po->previous_msgctxt(['new string']);
[$string =] $po->msgid(['new string']);
[$string =] $po->previous_msgid(['new string']);
[$string =] $po->msgid_plural(['new string']);
[$string =] $po->previous_msgid_plural(['new string']);
[$string =] $po->msgstr(['new string']);
[$string =] $po->msgstr_n([{0 => 'new string', 1 => ...}]);
[$boolean =] $po->obsolete([$boolean]);
[$value =] $po->fuzzy([value]);
[$value =] $po->add_flag('c-format');
[$value =] $po->add_flag('...-format');
print $po->dump();

$quoted_string = $po->quote($string);
$string = $po->dequote($quoted_string);
$string = DBD::PO::Locale::PO->dequote($quoted_string, $eol);

$aref = DBD::PO::Locale::PO->load_file_asarray(<filename>);
$href = DBD::PO::Locale::PO->load_file_ashash(<filename>);
DBD::PO::Locale::PO->save_file_fromarray(<filename>, $aref);
DBD::PO::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 DBD::PO::Locale::PO object.

SUBROUTINES/METHODS

method new

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

Specify an eol or accept the default "\n".

eol => "\r\n"

Create a new DBD::PO::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, msgstr_n, msgctxt, comment, automatic, reference, obsolete, fuzzy. See accessor methods below.

To generate a po file header, add an entry with an empty msgid, like this:

$po = DBD::PO::Locale::PO->new(
    '-msgid'  => q{},
    '-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",
);

method eol

Set or get the eol string from the object.

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

method previous_msgid

Like before but the previous one.

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

method previous_msgid_plural

Like before but the previous one.

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

method 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 singular translation',
        1 => 'found %d plural translation case 1',
        2 => 'found %d plural translation case 2',
        3 => 'found %d plural translation case 3',
        4 => 'found %d plural translation case 4',
        5 => 'found %d plural translation case 5',
    }
);

This method expects the new strings in unquoted form but returns the current strings in quoted form.

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

method previous_msgctxt

Like before but the previous one.

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

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

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

method reference

Set or get reference marking comments from the object (inserted by emacs po-mode or gettext).

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

method format_flag

The format name at this example is perl.

Set or get the perl-format or no-perl-format flag on the object.

This can take 3 values: 1 implies perl-format, 0 implies no-perl-format, and undefined implies neither.

Allowed names are: c-format, objc-format, sh-format, python-format, lisp-format, elisp-format, librep-format, scheme-format, smalltalk-format, java-format, csharp-format, awk-format, object-pascal-format, ycp-format, tcl-format, perl-format, perl-brace-format, php-format, gcc-internal-format, qt-format, kde-format, boost-format.

method has_flag

if ($po->has_flag('perl-format')) {
    ...
}

Returns true if the flag exists in the entry's #, comment

method add_flag

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

Adds the flag to the #, comment

method remove_flag

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

Removes the flag from the #, comment

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

method dump

Returns the entry as a string, suitable for output to a po file.

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

method dequote

Returns a quoted po string to its natural form.

method load_file_asarray

Given the filename of a po-file, reads the file and returns a reference to a list of DBD::PO::Locale::PO objects corresponding to the contents of the file, in the same order.

method load_file_ashash

Given the filename of a po-file, reads the file and returns a reference to a hash of DBD::PO::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.

method save_file_fromarray

Given a filename and a reference to a list of DBD::PO::Locale::PO objects, saves those objects to the file, creating a po-file.

method save_file_fromhash

Given a filename and a reference to a hash of DBD::PO::Locale::PO objects, saves those objects to the file, creating a po-file. The entries are sorted alphabetically by untranslated string.

method load_entry

Method was added to read entry by entry.

use Carp qw(croak);
use English qw(-no_match_vars $OS_ERROR);
use Socket qw($CRLF);
use DBD::PO::Locale::PO;

open my $file_handle, '<', $file_name
    or croak $OS_ERROR;
$eol = $CRLF;
my $line_number = 0;
while (
    my $po = DBD::PO::Locale::PO->load_entry(
        $file_name,
        $file_handle,
        \$line_number,
        $eol, # optional, default "\n"
    )
) {
    do_something_with($po);
}

DIAGNOSTICS

none

CONFIGURATION AND ENVIRONMENT

none

DEPENDENCIES

Carp

English

INCOMPATIBILITIES

not known

BUGS AND LIMITATIONS

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). (And the quoting of binary values can be changed, but all this is not a Bug.)

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

Locale::PO requires blank lines between entries, but Uniforum style PO files don't have any. (Fixed)

AUTHOR

Steffen Winkler <steffenw at cpan.org>

This module is a bugfixed, changed and extended copy of Module Locale::PO, version '0.21'.

LICENSE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install DBD::PO, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBD::PO

CPAN shell

perl -MCPAN -e shell
install DBD::PO

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SUBROUTINES/METHODS

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions