/ 
Locale-Country-Multilingual-0.09
River stage one • 5 direct dependents • 6 total dependents
/ Locale::Country::Multilingual

NAME

Locale::Country::Multilingual - mapping ISO codes to localized country names

SYNOPSIS

use Locale::Country::Multilingual;

my $lcm = Locale::Country::Multilingual->new();
$country = $lcm->code2country('jp');        # $country gets 'Japan'
$country = $lcm->code2country('chn');       # $country gets 'China'
$country = $lcm->code2country('250');       # $country gets 'France'
$code    = $lcm->country2code('Norway');    # $code gets 'no'

$lcm->set_lang('zh_CN'); # set default language to Chinese
$country = $lcm->code2country('cn');        # $country gets '中国'
$code    = $lcm->country2code('日本');      # $code gets 'jp'

@codes   = $lcm->all_country_codes();
@names   = $lcm->all_country_names();

# more heavy call
my $lang = 'en';
$country = $lcm->code2country('cn', $lang);        # $country gets 'China'
$lang = 'zh_CN';
$country = $lcm->code2country('cn', $lang);        # $country gets '中国'

my $CODE = 'LOCALE_CODE_ALPHA_2'; # by default
$code    = $lcm->country2code('Norway', $CODE);    # $code gets 'no'
$CODE = 'LOCALE_CODE_ALPHA_3';
$code    = $lcm->country2code('Norway', $CODE);    # $code gets 'nor'
$CODE = 'LOCALE_CODE_NUMERIC';
$code    = $lcm->country2code('Norway', $CODE);    # $code gets '578'
$code    = $lcm->country2code('挪威', $CODE, 'zh_CN');    # with lang=zh_CN

$CODE = 'LOCALE_CODE_ALPHA_3';
$lang = 'zh_CN';
@codes   = $lcm->all_country_codes($CODE);         # return codes with 3alpha
@names   = $lcm->all_country_names($lang);         # get all Chinese Countries Names

DESCRIPTION

Locale::Country::Multilingual is nearly a drop-in replacement for Locale::Country, but supports country names in several languages.

A language is selected by a two-letter language code as described by ISO 639-1 http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. This code can be amended by a two-letter region code, that is described by ISO 3166-1 http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. This combination of language and region is also described in RFC 4646 http://www.ietf.org/rfc/rfc4646.txt and RFC 4647 http://www.ietf.org/rfc/rfc4647.txt, and is commonly used for HTTP 1.1 http://www.ietf.org/rfc/rfc2616.txt and the POSIX setlocale(3) function. Codes can be given in small or capital letters and be divided by an arbitrary string of none-letter ASCII bytes (but "-" or "_" is recommended).

METHODS

import

use Locale::Country::Multilingual 'en', 'fr', {use_io_layer => 1};

The import class method is called when a module is use'd. Language files can be pre-loaded at compile time, by specifying their language codes. This can be useful when several processes are forked from the main application, e.g. in an Apache mod_perl environment - language data that is loaded before forking, is shared by all processes.

The last argument can be a reference to a hash of options.

The only option ATM is use_io_layer. See Locale::Country::Multilingual::Unicode for more information.

new

$lcm = Locale::Country::Multilingual->new;
$lcm = Locale::Country::Multilingual->new(
  lang => 'es',
  use_io_layer => 1,
);

Constructor method. Accepts optional list of named arguments:

lang

The language to use. See "AVAILABLE LANGAUGES" for what codes are accepted.

use_io_layer

Set this true if you need correct encoding behavior. See Locale::Country::Multilingual::Unicode for more information.

set_lang

$lcm->set_lang('de');

Set the current language. Only argument is a language code as described in the "DESCRIPTION" above.

See "AVAILABLE LANGAUGES" for what codes are accepted.

This method does not actually load the language data. Use "assert_lang" if you really need to know for sure if a language is supported.

assert_lang

$lang = $lcm->assert_lang('es', 'it', 'fr');

Tries to load any of the given languages. Returns the language code for the first language that was successfully loaded. Returns undef if none of the given languages could be loaded. Actually loads the language data, but does not set the language, so you probably want to use it this way:

$lang = $lcm->assert_lang(qw/es it fr en/)
  and $lcm->set_lang($lang)
  or die "unable to load any language\n";

code2country

$country = $lcm->code2country('gb');
$country = $lcm->code2country('gb', 'zh_CN');

Turns an ISO 3166-1 code into a country name in the current language. The default language is "en".

Accepts either two-letter or a three-letter code or a 3 digit numerical code.

A language might be given as second argument to set the output language only for this call - it does not change the current language, that was set with "set_lang".

Returns the country name.

This method croaks if the language is not available.

country2code

$code = $lcm->country2code(
  'République tchèque', 'LOCALE_CODE_ALPHA_2', 'fr'
);

Take a country name and return the two-letter code when available. Aside from being case-insensitive the country must be written exactly the way how "code2country" returns it.

The second argument is optional and can be one of "LOCALE_CODE_ALPHA_2", "LOCALE_CODE_ALPHA_3" and "LOCALE_CODE_NUMERIC". The default is "LOCALE_CODE_ALPHA2".

The third argument is the language to use for the country name and is optional too.

Returns an ISO-3166 code or undef if search fails.

This method croaks if the language is not available.

all_country_codes

all_country_names

@countrynames = $lcm->all_country_names;
@countrynames = $lcm->all_country_names('fr');

Returns an array of all lowercased country names in the current or given locale.

AVAILABLE LANGAUGES

en English
zh (zh-cn) Chinese Simp.
zh-tw Chinese Trad.
it Italian
es Spanish
pt Portuguese
de German
fr French
ja Japanese
no Norwegian

other languages are welcome to send by email.

Deprecated languages

Previous releases of this module offered languages "cn" and "tw". Those were replaced by "zh" and "zh-tw" to comply with the ISO 639 standard and RFC 2616. "cn" and "tw" will be removed in a future release of this package.

SUPPORTS

subversion trunk

http://code.google.com/p/perl-locale-country-multilingual/

SEE ALSO

Locale::Country, ISO 639 http://en.wikipedia.org/wiki/ISO_639, ISO 3166 http://en.wikipedia.org/wiki/ISO_3166, RFC 2616 http://www.ietf.org/rfc/rfc2616.txt RFC 4646 http://www.ietf.org/rfc/rfc4646.txt, RFC 4647 http://www.ietf.org/rfc/rfc4647.txt

ACKNOWLEDGEMENTS

Thanks to michele ongaro for Italian/Spanish/Portuguese/German/French/Japanese dat files.

Thanks to Andreas Marienborg for Norwegian dat file.

AUTHOR

Fayland Lam <fayland at gmail.com>

Bernhard Graf <graf at cpan.org>

COPYRIGHT & LICENSE

Copyright 2007-2008 *AUTHOR* all rights reserved.

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