NAME

Locale::PO::Utils - Utils to build/extract the PO header and anything else

$Id: Utils.pm 541 2010-08-14 07:19:43Z steffenw $

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

VERSION

0.07

SYNOPSIS

For possible constructor attributes read the chapters at SUBROUTINES/METHODS.

use Locale::PO::Utils;

$obj = Locale::PO::Utils->new();

DESCRIPTION

Utils to build or extract the PO header, calculate the plural forms, manage the different writing of placeholders and expand the placeholders.

The header of a PO file is quite complex. This module helps to build the header and extract.

In this header, an entry is called "Plural-Forms". How many plural forms the language has, is described there. The second Information in "Plural-Forms" describes as a code, how to choose the correct plural form.

Some phrases contain placeholders. Here are the methods to replace these.

SUBROUTINES/METHODS

Build or extract the PO header

All attributes are optional. The attribute values are the defaults to show them.

$obj = Locale::PO::Utils->new(
    charset   => 'UTF-8',
    eol       => "\n",
    separator => "\n",
);

The attribute setter are named set_charset, set_eol and set_separator. The attribute getter are named get_charset, get_eol and get_separator.

method get_all_header_keys

This sub returns all header keys, you can set or get.

$array_ref = $obj->get_all_header_keys();

or as class method

$array_ref => Locale::PO::Utils->get_all_header_keys();

The $array_ref is:

[ qw(
    Content-Transfer-Encoding
    Content-Type
    Language-Team-Mail
    Language-Team-Name
    Last-Translator-Mail
    Last-Translator-Name
    MIME-Version
    PO-Revision-Date
    POT-Creation-Date
    Plural-Forms
    Project-Id-Version
    Report-Msgid-Bugs-To-Mail
    Report-Msgid-Bugs-To-Name
    charset
    extended
) ]

method build_header_msgstr

There are more ways to do this.

minimal header

$obj->build_header_msgstr();

The result is:

MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

maximal header

$obj->build_header_msgstr({
    'Project-Id-Version'        => 'Testproject',
    'Report-Msgid-Bugs-To-Name' => 'Bug Reporter',
    'Report-Msgid-Bugs-To-Mail' => 'bug@example.org',
    'POT-Creation-Date'         => 'no POT creation date',
    'PO-Revision-Date'          => 'no PO revision date',
    'Last-Translator-Name'      => 'Steffen Winkler',
    'Last-Translator-Mail'      => 'steffenw@example.org',
    'Language-Team-Name'        => 'MyTeam',
    'Language-Team-Mail'        => 'cpan@example.org',
    'MIME-Version'              => '1.0',
    'Content-Type'              => 'text/plain',
    'charset'                   => 'utf-8',
    'Content-Transfer-Encoding' => '8bit',
    'extended'                  => [
        'X-Poedit-Language'      => 'German',
        'X-Poedit-Country'       => 'GERMANY',
        'X-Poedit-SourceCharset' => 'utf-8',
    ],
});

The result is:

Project-Id-Version: Testproject
Report-Msgid-Bugs-To: Bug Reporter <bug@example.org>
POT-Creation-Date: no POT creation date
PO-Revision-Date: no PO revision date
Last-Translator: Steffen Winkler <steffenw@example.org>
Language-Team: MyTeam <cpan@example.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Poedit-Language: German
X-Poedit-Country: GERMANY
X-Poedit-SourceCharset: utf-8

method split_header_msgstr (for internal use only)

This method is internal used at method get_header_msgstr_data.

$array_ref = $obj->split_header_msgstr($msgstr);

method get_header_msgstr_data

This method extracts the values using the given keys.

single mode

$string = $obj->get_header_msgstr_data($msgstr, 'Project-Id-Version');

$string is now "Testproject".

multiple mode

$data = $obj->get_header_msgstr_data(
    $msgstr,
    [qw(Project-Id-Version Report-Msgid-Bugs-To-Mail extended)],
),

$data is now:

[
    'Testproject',
    'bug@example.org',
    [
        'X-Poedit-Language',
        'German',
        'X-Poedit-Country',
        'GERMANY',
        'X-Poedit-SourceCharset',
        'utf-8',
    ],
]

Calculate the plural forms

All attributes are optional. The attribute values are the defaults to show them.

$obj = Locale::PO::Utils->new(
    plural_forms => 'nplurals=1; plural=0',
);

The defaults for nplural and plural_code is:

$obj->get_nplurals()    # returns: 1
$obj->get_plural_code() # returns: sub { return 0 } }

The attribute setter is named set_plural_forms. There is no public setter for attributes nplurals and plural_code and it is not possible to set them in the constructor. Call method set_plural_forms or set attribute plural_forms in the constructor. After that nplurals and plual_code will be calculated automaticly in a safe way.

The attribute getter are named get_plural_forms, get_nplurals and get_plural_code.

method set_plural_forms

Plural forms are defined like this for English:

$obj->set_plural_forms('nplurals=2; plural=(n != 1)');

After that this method calculates and set nplurals and the plural_code in a safe way.

method get_nplurals

This method get back the calculated count of plural forms. The default value before any calculation is 1.

$nplurals = $obj->get_nplurals();

method get_plural_code

This method get back the calculated code for the calculaded plural form to choose the correct plural. The default value before any calculation sub {return 0}.

For the example 'nplurals=2; plural=(n != 1)':

$plural = $obj->get_plural_code()->(0), # $plural is 1
$plural = $obj->get_plural_code()->(1), # $plural is 0
$plural = $obj->get_plural_code()->(2), # $plural is 1
$plural = $obj->get_plural_code()->(3), # $plural is 1
...

Manage the different writing of placeholders

$obj = Locale::PO::Utils->new();

method maketext_to_gettext

Maps maketext strings with

[_1]
[quant,_2,singular]
[quant,_3,singular,plural]
[quant,_4,singular,plural,zero]
[*,_5,singular]
[*,_6,singular,plural]
[*,_7,singular,plural,zero]

inside to

%1
%quant(%2,singluar)
%quant(%3,singluar,plural)
%quant(%4,singluar,plural,zero)
%*(%5,singluar)
%*(%6,singluar,plural)
%*(%7,singluar,plural,zero)

inside.

$gettext_string = $obj->maketext_to_gettext($maketext_string);

@gettext_strings = $obj->maketext_to_gettext(@maketext_strings);

This method can called as class method too.

$gettext_string = Locale::PO::Utils->maketext_to_gettext($maketext_string);

@gettext_strings = Locale::PO::Utils->maketext_to_gettext(@maketext_strings);

Expand the placeholders

All attributes are optional. The attribute values are the defaults to show them.

$obj = Locale::PO::Utils->new(
    is_gettext_style => undef, # as boolean false
);

The attribute setter is named set_is_gettext_style. The attribute getter is named is_gettext_style.

method set_numeric_code, clear_numeric_code

If it is needed to localize the numerics than describe this in a code reference.

my $coderef = sub {
    my $value = shift;

    ...

    return $value;
};

$obj->set_numeric_code($coderef); # set

Than method expand_maketext or expand_gettext will run this code before the substitution of numerics placeholders.

To switch off this code - clear them.

$obj->clear_numeric_code();

method expand_maketext

Expands strings containing maketext placeholders. To use gettext style set is_gettext_style to a true value. Otherwise maketext style is expected.

maketext style:

[_1]
[quant,_1,singular]
[quant,_1,singular,plural]
[quant,_1,singular,plural,zero]
[*,_1,singular]
[*,_1,singular,plural]
[*,_1,singular,plural,zero]

gettext style:

%1
%quant(%1,singular)
%quant(%1,singular,plural)
%quant(%1,singular,plural,zero)
%*(%1,singular)
%*(%1,singular,plural)
%*(%1,singular,plural,zero)

   $obj->set_is_gettext_style(0);
   $expanded = $obj->expand_maketext($maketext_text, @args);

   $obj->set_is_gettext_style(1);
   $expanded = $obj->expand_maketext($gettext_text, @args);

method expand_gettext

Expands strings containing gettext placeholders like {name}.

$expanded = $obj->expand_gettext($text, %args);

EXAMPLE

Inside of this distribution is a directory named example. Run the *.pl files.

DIAGNOSTICS

none

CONFIGURATION AND ENVIRONMENT

none

DEPENDENCIES

Moose

MooseX::StrictConstructor

MooseX::FollowPBP

English

Carp

Clone

Params::Validate

Safe

Scalar::Util

INCOMPATIBILITIES

not known

BUGS AND LIMITATIONS

not known

AUTHOR

Steffen Winkler

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 Locale::PO::Utils, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Locale::PO::Utils

CPAN shell

perl -MCPAN -e shell
install Locale::PO::Utils

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

Build or extract the PO header

method get_all_header_keys

method build_header_msgstr

minimal header

maximal header

method split_header_msgstr (for internal use only)

method get_header_msgstr_data

single mode

multiple mode

Calculate the plural forms

method set_plural_forms

method get_nplurals

method get_plural_code

Manage the different writing of placeholders

method maketext_to_gettext

Expand the placeholders

method set_numeric_code, clear_numeric_code

method expand_maketext

method expand_gettext

EXAMPLE

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions