The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Locale-PO-Utils-0.08
++
/ Locale::PO::Utils

NAME

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

$Id: Utils.pm 546 2010-08-22 19:44:42Z steffenw $

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

VERSION

0.08

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 are 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 and safe.

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

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 is 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);

or

    @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);

or

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

method gettext_to_maketext

It is the same like method maktetext_to_gettext only the other direction.

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

or

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

This method can called as class method too.

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

or

    @maketext_strings = Locale::PO::Utils->gettext_to_maketext(@gettext_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

SEE ALSO

Locale::Maketext

Locele::TextDomain

http://en.wikipedia.org/wiki/Gettext

http://translate.sourceforge.net/wiki/l10n/pluralforms

AUTHOR

Steffen Winkler

LICENSE AND COPYRIGHT

Copyright (c) 2010, Steffen Winkler <steffenw at cpan.org>. All rights reserved.

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