/ 
I18N-Handle-0.051
River stage zero No dependents
/ I18N::Handle

NAME

I18N::Handle - A common i18n handler for web frameworks and applications.

DESCRIPTION

***THIS MODULE IS STILL IN DEVELOPMENT***

I18N::Handle is a common handler for web frameworks and applications.

I18N::Handle also provides exporting a global loc function to make localization, the default loc function name is "_". To change the exporting loc function name , please use loc option.

The difference between I18N::Handle and Locale::Maketext is that I18N::Handle automatically does most things for you, and it provides simple API like speak, can_speak instead of get_handle, languages.

To generate po/mo files, App::I18N is an utility for this, App::I18N is a command-line tool for parsing, exporting, managing, editing, translating i18n messages. See also App::I18N.

SYNOPSIS

Ideas are welcome. just drop me a line.

option import takes the same arguments as Locale::Maketext::Lexicon takes. it's language => [ format => source ].

use I18N::Handle;
my $hl = I18N::Handle->new( 
            import => {
                    en => [ Gettext => 'po/en.po' ],
                    fr => [ Gettext => 'po/fr.po' ],
                    ja => [ Gettext => 'po/ja.po' ],
            })->accept( qw(en fr) )->speak( 'en' );

Or a simple way to import gettext po files: This will transform the args to the args that import option takes:

use I18N::Handle;
my $hl = I18N::Handle->new( 
            Gettext => {
                    en => 'po/en.po',
                    fr => 'po/fr.po',
                    ja => [ 'po/ja.po' , 'po2/ja.po' ],
            })->accept( qw(en fr) )->speak( 'en' );


print _('Hello world');

$hl->speak( 'fr' );
$hl->speak( 'ja' );
$hl->speaking;  # return 'ja'

my @langs = $hl->can_speak();  # return 'en', 'fr', 'ja'

OPTIONS

format => { language => source , ... }

Format could be Gettext | Msgcat | Slurp | Tie.

use I18N::Handle;
my $hl = I18N::Handle->new( 
            Gettext => {
                    en => 'po/en.po',
                    fr => 'po/fr.po',
                    ja => [ 'po/ja.po' , 'po2/ja.po' ],
            });
$hl->speak( 'en' );
po => 'path' | [ path1 , path2 ]

Suppose you have these files:

po/en.po
po/zh_TW.po

When using:

I18N::Handle->new( po => 'po' );

will be found. can you can get these langauges:

[ en , zh-tw ]
locale => 'path' | [ path1 , path2 ]
import => Arguments to Locale::Maketext::Lexicon

OPTIONAL OPTIONS

no_global_loc => bool

Do not install global locale method "_".

style => style ... (Optional)

The style could be gettext.

loc => global loc function name (Optional)

The default global loc function name is _.

loc => 'loc'
loc_func => CodeRef (Optional)

Use a custom global localization function instead of default localization function.

loc_func => sub {
        my ($self,$lang_handle) = @_;

        ...

        return $text;
}

USE CASES

Handling po files

$hl = I18N::Handle->new( 
        po => 'path/to/po',
        style => 'gettext'          # use gettext style format (default)
            )->speak( 'en' );

print _('Hello world');

Handling locale

If you need to bind the locale directory structure like this:

path/to/locale/en/LC_MESSAGES/app.po
path/to/locale/en/LC_MESSAGES/app.mo
path/to/locale/zh_tw/LC_MESSAGES/app.po
path/to/locale/zh_tw/LC_MESSAGES/app.mo

You can just pass the locale option:

$hl = I18N::Handle->new(
        locale => 'path/to/locale'
        )->speak( 'en_US' );

or just use import:

$hl = I18N::Handle->new( 
        import => { '*' => 'locale/*/LC_MESSAGES/hello.mo'  } );

Handling json files

not implemented yet

Ensure you have json files:

json/en.json
json/fr.json
json/ja.json

Then specify the json option:

$hl = I18N::Handle->new( json => 'json' );

Singleton

If you need a singleton I18N::Handle, this is a helper function to return the singleton object:

$hl = I18N::Handle->singleton( locale => 'path/to/locale' );

In your applications, might be like this:

sub get_i18n {
    my $class = shift;
    return I18N::Handle->singleton( ... options ... )
}

Connect to a remote i18n server

not implemented yet

Connect to a translation server:

$handle = I18N::Handle->new( 
        server => 'translate.me' )->speak( 'en_US' );

Binding with database

not implemented yet

Connect to a database:

$handle = I18N::Handle->new(
        dsn => 'DBI:mysql:database=$database;host=$hostname;port=$port;'
        );

Binding with Google translation service

not implemented yet

Connect to google translation:

$handle = I18N::Handle->new( google => "" );

Exporting loc function to Text::Xslate

my $tx = Text::Xslate->new( 
    path => ['templates'], 
    cache_dir => ".xslate_cache", 
    cache => 1,
    function => { "_" => \&_ } );

Then you can use _ function inside your Text::Xslate templates:

<: _('Hello') :>

PUBLIC METHODS

new

singleton( options )

If you need a singleton I18N::Handle, this is a helper function to return the singleton object.

speak( language )

setup current language. language, can be en, fr and so on..

speaking()

get current speaking language name.

can_speak()

return a list that currently supported.

accept( language name list )

setup accept languages.

$hl->accpet( qw(en fr) );

fallback( language )

setup fallback language. when speak() fails , fallback to this language.

$hl->fallback( 'en' );

PRIVATE METHODS

_unify_langtag

_scan_po_files

_scan_locale_files

AUTHOR

Yoan Lin <cornelius.howl {at} gmail.com>

SEE ALSO

App::I18N

LICENSE

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