# NAME I18N::Handle - A common i18n handler for web frameworks and applications. # DESCRIPTION __***THIS MODULE IS STILL IN DEVELOPMENT***__ [I18N::Handle](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?App::I18N). # SYNOPSIS Ideas are welcome. just drop me a line. option `import` takes the same arguments as [Locale::Maketext::Lexicon](http://search.cpan.org/perldoc?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' ], jp => [ Gettext => 'po/jp.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', jp => [ 'po/jp.po' , 'po2/jp.po' ], })->accept( qw(en fr) )->speak( 'en' ); print _('Hello world'); $hl->speak( 'fr' ); $hl->speak( 'jp' ); $hl->speaking; # return 'jp' my @langs = $hl->can_speak(); # return 'en', 'fr', 'jp' # 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', jp => [ 'po/jp.po' , 'po2/jp.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](http://search.cpan.org/perldoc?Locale::Maketext::Lexicon) # OPTIONAL OPTIONS - `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](http://search.cpan.org/perldoc?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](http://search.cpan.org/perldoc?Text::Xslate) templates: <: _('Hello') :> # PUBLIC METHODS ## new ## singleton( _options_ ) If you need a singleton [I18N::Handle](http://search.cpan.org/perldoc?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 # SEE ALSO [App::I18N](http://search.cpan.org/perldoc?App::I18N) # LICENSE This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.