new()
Takes one argument, the locale tag whose CLDR data you want to use.
No argument defaults to 'en'.
It is an argument based singleton so you can call it more than once with out it having to rebuild the
object every time.
It returns false if a locale given is not available. $@ should have been set at that point by eval.
my $en = Locales->new('en') or die $@;
ObjectmethodsMiscmethodsget_cldr_version()
Takes no arguments.
Returns the version of the CLDR any data it uses comes from. Can also be called as a class method or
function.
get_locale()
Takes no arguments.
Returns the normalized locale of the object, this is the same as the argument to new()get_language()
Takes no arguments.
Returns the language portion of the object’s locale.
get_territory()
Takes no arguments.
Returns the territory portion of the object’s locale if any (e.g. 'en_au'), undef if there is none
(e.g. 'it').
get_soft_locale_fallback()
Takes no arguments.
Returns the locale that the object is based on in the case that the given locale (i.e.
"get_locale()") is a soft locale.
Note: If you do not want to have soft locale objects you should simply not call new() if it is soft:
- my $loc = Locales->new($tag) || die $@;
+ my $loc = (Locales::tag_is_soft_locale($tag) ? undef : Locales->new($tag)) || die $@;
This could be added to the constructor but for now I don't want to make it more complicated only to
support something that seems odd. If you have a use case submit an rt w/ details. Thanks!
numf()
Note: As of v0.17 you probably want "get_formatted_decimal()" instead of numf().
Takes one optional boolean argument.
Returns 1 if the object’ss locale’s number format is comma for thousand separator, period for
decimal.
Returns 2 if the object’s locale’s number format is period for thousand separator, comma for
decimal.
Otherwise it returns a reference to a 3 element array containing this CLDR data: number format,
separator character, decimal character.
The boolean argument, when true will do it’s best to determine and return a 1 or a 2.
Territorymethodsget_territory_codes()
Take no arguments.
Returns an unsorted list of known territory codes.
get_territory_names()
Take no arguments.
Returns an unsorted list of the display names for each known territory code.
get_territory_lookup()
Take no arguments.
Returns a copy of the lookup hash of the display names for each known territory code.
get_territory_from_code()
Takes one argument, the locale code whose territory name you want to find. Defaults to the territory
of the of object’s locale, if any.
Returns the name of the given tag’s territory or, if not found, the territory portion (if any),
returns false otherwise.
An optional second argument, when true, will force it to return the normalized tag if nothing else
can be figured out.
get_code_from_territory()
Takes one argument, the territory name whose locale you want to find.
Returns the locale tag if found, false otherwise.
code2territory()
Alias for get_territory_from_code()territory2code()
Alias for get_code_from_territory()LanguageMethodsget_language_codes()
Take no arguments.
Returns an unsorted list of known language codes.
get_language_names()
Take no arguments.
Returns an unsorted list of the display names for each known language code.
get_language_lookup()
Take no arguments.
Returns a copy of the lookup hash of the display names for each known language code.
get_language_from_code()
Takes one argument, the locale code whose language name you want to find. Defaults to the object’s
locale.
Returns the name of the given tag’s language, returns false otherwise.
An optional second argument, when true, will force it to return a properly formatted CLDR format
display based on if we know the language and/or territory if nothing else can be figured out.
get_code_from_language()
Takes one argument, the language name whose locale you want to find.
Returns the locale tag if found, false otherwise.
get_native_language_from_code()
Like get_language_from_code() except it returns the name in the given locale’s native language.
get_character_orientation_from_code()
Like get_language_from_code() except it returns the character orientation identifier for the given
locale. (defaulting to the locale of the object if non is given)
Typically it will be the string “left-to-right” or “right-to-left”.
See <http://unicode.org/repos/cldr-tmp/trunk/diff/by_type/misc.layout.html> for more information.
get_character_orientation_from_code_fast()
Same as get_character_orientation_from_code() except it should use less-overhead. Can be called as a
function also so you can use it without creating an object.
get_locale_display_pattern_from_code()
Like get_character_orientation_from_code() except it returns the locale display pattern for the given
locale. (defaulting to the locale of the object if non is given)
Typically it will be something like '{0} ({1})'
See <http://unicode.org/repos/cldr-tmp/trunk/diff/by_type/names.localeDisplayPattern.html> for more
information.
get_locale_display_pattern_from_code_fast()
Same as get_locale_display_pattern_from_code() except it should use less-overhead. Can be called as a
function also so you can use it without creating an object.
get_cldr_number_symbol_decimal()
Returns the decimal point symbol for the object’s locale. Takes no arguments.
For formatting numbers use get_formatted_decimal().
get_cldr_number_symbol_group()
Returns the integer grouping symbol for the object’s locale. Takes no arguments.
For formatting numbers use get_formatted_decimal().
get_fallback_list()
Returns a fallback list of locales in the order they apply based on the object’s locale.
The basic list will be: object’s locale, object’s super if any, the object’s CLDR fallback if any,
“special lookup” if any, 'en'
my @list = $fr_ca->get_fallback_list();
# fr_ca fr en
"special lookup" is a code ref that can be passed in as the first optional arg.
It is given the object’s locale when called and should return a list of locale tags (they will be
normalized).
my @list = $fr_ca->get_fallback_list(sub { return $_[0] =~ m/fr/ ? qw(i_yoda i_love_rhi) : () } );
# fr_ca fr i_yoda i_love_rhi en
get_plural_form()
Takes a number and returns the plural category that the number fits under for the object’s locale.
You can also add an array of items to return instead of the category name. For the details on what
arguments a given local needs see Locales::DB::Docs::PluralForms.
The array should be the same length of the list of plural form categories for the locale. See
get_plural_form_categories().
The exception to that is when you specify the optional "“Special Zero” Argument" in
Locales::DB::Docs::PluralForms.
For example, 'en' has the plural categories “one” and “other”, so it'd work like this:
my $cat = $en->get_plural_form(0); # 'other'
my $str = $en->get_plural_form(0,'I am 1','I am other'); # I am other
my $str = $en->get_plural_form(0,'I am 1','I am other','I am nothing'); # I am nothing
my $cat = $en->get_plural_form(1); # 'one'
my $str = $en->get_plural_form(1,'I am 1','I am other'); # I am 1
my $str = $en->get_plural_form(1,'I am 1','I am other','I am nothing'); #I am 1
my $cat = $en->get_plural_form(2); # 'other'
my $str = $en->get_plural_form(2,'I am 1','I am other'); # I am other
my $str = $en->get_plural_form(2,'I am 1','I am other','I am nothing'); # I am other
In array context the second value is a boolean for if the return value is the "“Special Zero”
Argument" in Locales::DB::Docs::PluralForms or not.
This boolean value only has meaning when called with the additional array of items to return instead
of the category name.
This method can carp() a few things:
"Could not determine plural logic."
The locale does not have plural logic data.
"The number of given values (%d) does not match the number of categories (%d)."
You passed too many or too few values after the initial numeric argument.
You'll only see this if $locales_object->{'verbose'} is set to true.
"The category (%s) is not used by this locale."
The locale’s plural rules come up with a category that is not applicable to the locale. Default
to “other” at this point.
get_plural_form_categories()
Returns an array of the CLDR plural rule category names that this locale uses.
Their order corresponds to the position of the corresponding value that get_plural_form() uses.
supports_special_zeroth()
Takes no arguments, returns a boolean.
It is true if the locale uses the "“Special Zero” Argument" in Locales::DB::Docs::PluralForms.
False if it does not.
plural_category_count()
Takes no arguments.
Returns the number of plural categories applicable to the object’s locale.
Does not factor in support (or not) of the special zeroth category.
get_list_and()
Stringify an "and" list of items as defined in the CLDR for the object’s locale.
Note: get_list_or() will be done once CLDR defines the OR-list data
<http://unicode.org/cldr/trac/ticket/4051>.
$en->get_list_and() # nothing
$en->get_list_and(1) # 1
$en->get_list_and(1,2) # 1 and 2
$en->get_list_and(1,2,3) # 1, 2, and 3
$en->get_list_and(1,2,3,4) # 1, 2, 3, and 3
$es->get_list_and() # nothing
$es->get_list_and(1) # 1
$es->get_list_and(1,2) # 1 y 2
$es->get_list_and(1,2,3) # 1, 2 y 3
$es->get_list_and(1,2,3,4) # 1, 2, 3 y 3
To help disambiguate ambiguous arguments (none, undef, “”, all space/non-break-space) you can use
$loc->{'misc'}{'list_quote_mode'}.
The default value is “none”.
Possible values:
“all”
quote() all values.
“some”
quote() only ambiguous values (none (as if it was “”), undef, “”, all space/non-break-space).
“none”
do not quote() any values
If another value is given or the entry does not exist you'll get “none” behavior. If it is set to an
unknown value you'll get a carp() of “$self->{misc}{list_quote_mode} is set to an unknown value”.
get_list_or()
Stringify an "or" list of items as defined in the CLDR for the object’s locale.
This is a stub until CLDR defines the OR-list data <http://unicode.org/cldr/trac/ticket/4051>.
Until then it is essentially the same as "get_list_and()"except it uses English rules/grammer for or
lists.
Uses $loc->{'misc'}{'list_quote_mode'} the same way get_list_and() does.
get_formatted_ellipsis_initial()
Formats the given string per the initial ellipsis pattern.
Truncating for length is the caller’s responsibility since knowing how to do that correctly depends
on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text,
HTML might have a broken or unclosed tag, ANSI might be unclosed or truncated, etc) so it is outside
of the scope of the CLDR.
…foo
get_formatted_ellipsis_medial()
Formats the given string per the medial ellipsis pattern.
Truncating for length is the caller’s responsibility since knowing how to do that correctly depends
on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text,
HTML might have a broken or unclosed tag, ANSI might be unclosed or truncated, etc) so it is outside
of the scope of the CLDR.
foo…bar
get_formatted_ellipsis_final()
Formats the given string per the medial ellipsis pattern.
Truncating for length is the caller’s responsibility since knowing how to do that correctly depends
on what the string is (e.g. plain text needs to factor in the encoding or we might corrupt the text,
HTML might have a broken or includes tag, ANSI might be unclosed or truncated, etc) so it is outside
of the scope of the CLDR.
foo…
quote()
Quotes the argument with the CLDR delimiters quotation_start and quotation_end.
quote_alt()
Quotes the argument with the CLDR delimiters alternate_quotation_start and alternate_quotation_end.
get_formatted_decimal()
Return the given number as a string formatted per the locale’s CLDR decimal format pattern.
An optional second argument defines a maximum length of decimal places (default is 6 perl %f, max is
14, if you have a need for a larger max please open an rt w/ context and we may make the max settable
in the object)
$fr->get_formatted_decimal("1234567890.12345"); # 1 234 567 890,12345
$fr->get_formatted_decimal("1234567890.12345",4); # 1 234 567 890,123
$fr->get_formatted_decimal("1234567890.12345",3); # 1 234 567 890,1235
Perl number stringification caveats:
You can avoid most stringification of large integers issues by passing strings.
$l->get_formatted_decimal(99999999999999999983222787.1234); # returns 1e+26 since that is how it comes into the function
$l->get_formatted_decimal("99999999999999999983222787.1234"); # 99,999,999,999,999,999,983,222,787.1234
You can avoid most formatting of large decimal parts issues by passing strings.
$l->get_formatted_decimal(10000000001.12345678911234,12); # 10,000,000,001.1235 since it is already truncated when it comes into the function
$l->get_formatted_decimal("10000000001.12345678911234",12); # 10,000,000,001.123456789112
If the abs integer is > 10_000_000_000 and the decimal part alone stringify into an exponential
number the rounding is not done.
That is OK though, since this isn't intended to be used in math and you are already aware of how
large integers and decimals act oddly on computers right?
In general very large integers and/or very large decimal places get wonky when you want to turn them
into a string like [0-9]+.[0-9]+
This is why we have a hard limit of 14 decimal places, to enforce some sense of sanity. You might
consider only using the max decimal places argument to make it less than 6 digits long.
This method can carp() a few (hopefully self explanatory) things regarding CLDR number format syntax
errors:
"Format had more than 2 pos/neg sections. Using default pattern."
"Format should have one decimal section. Using default pattern."
"Format is empty. Using default pattern."
code2language()
Alias for get_language_from_code()language2code()
Alias for get_code_from_language()Utilityfunctions
These are some functions used internally that you might find useful.
Locales::normalize_tag()
Takes a single argument, the locale tag to normalize.
Returns the normalized tag.
print Locales::normalize_tag(" en-GB\n "); # 'en_gb'
Locales::normalize_tag_for_datetime_locale()
Like normalize_tag() except the return value should be suitable for DateTime::Locale
print Locales::normalize_tag_for_datetime_locale(" en-GB\n "); # 'en_GB'
Locales::normalize_tag_for_ietf()
Like normalize_tag() except the return value should be suitable for IETF.
This is not a comprehensive IETF formatter, it is intended (for now at least) for the subset of tags
Locales.pm uses.
print Locales::normalize_tag_for_ietf(" en_gb\n "); # 'en-GB'
Locales::split_tag()
Takes a single argument, the locale tag to split into language and territory parts.
Returns the resulting array of 1 or 2 normalized (but not validated) items.
my ($language, $territory) = Locales::split_tag(" en-GB\n "); # ('en','gb')
my ($language, $territory) = Locales::split_tag('fr'); # ('fr');
my ($language, $territory) = Locales::split_tag('sr_Cyrl_YU'); # ('sr','cyrl_yu'), yes 'cyrl_yu' is invalid here since Locales doesn't work with the Script variants, good catch
Locales::get_i_tag_for_string()
Takes a single argument, the locale tag string to transform into "i" notation.
Returns the resulting normalized locale tag.
The standard tag for strings/tags without a standard is an "i" notation tag.
For example, the language "Yoda Speak" does not have an ISO code. You'd have to use i_yoda_speak.
# assuming $string = "Yoda Speak"; you'd get into the if(), assuming it was 'Spanish' or 'es'
if (!$en->get_language_from_code($string) && !$en->get_code_from_language($string) ) {
# it is not a code or a language (at least in the language of $en) so lets create a tag for it:
_create_locale_files( Locales::get_i_tag_for_string($string) ); # i_yoda_speak
}
else {
# if it is a language name then we fetch the code otherwise, at this point, we know it is a code, so return a normailized version
_create_locale_files( $en->get_code_from_language($yoda) || Locales::normalize_tag($yoda) );
}
Locales::tag_is_soft_locale()
Takes a single argument, the locale tag you want to check to see if it is <soft locale|/Soft Locales>
or not.
If it is it returns the super portion that an object would be based on. If it is not it returns
false.
Locales::tag_is_loadable()
Returns true if the given tag can be loaded as a Locales object via new(). False otherwise.
Locales::territory_code_is_known()
Returns true if the given tag is a known territory. False otherwise.
Locales::get_loadable_language_codes()
Takes no arguments. Returns an unsorted list of codes that can be loaded as a Locales object via
new().
Locales::non_locale_list()
Takes no arguments. Returns a list of locale tags that are not actually locales. e.g. 'mul' means
“Multiple Languages”.
Locales::is_non_locale()
Takes a locale tag as the argument and returns true if it is a non-locale code (See
"Locales::non_locale_list()"), false otherwise.
Locales::typical_en_alias_list
Takes no arguments. Returns a list of locale tags that are typically aliases of 'en'.
Locales::is_typical_en_alias
Takes a locale tag as the argument and returns true if it is typically an alias of 'en' (See
"Locales::typical_en_alias_list()"), false otherwise.
Locales::normalize_for_key_lookup()
Takes a single argument, the phrase string normalize in the same way the names are stored in each
locale’s lookup hash.
Returns the resulting normalized string.
This is used internally to normalize a given name in the same manner the name-to-code hash keys are
normalized.
If said normalization is ever improved then using this function will ensure everything is normalized
consistently.
That allows $en->get_code_from_language($name) to map to 'afa' if given these various variations of
$arg:
"Afro-Asiatic Language"
"afroasiatic\tLanguage"
"AFRO-Asiatic Language"
" Afro_Asiatic Language"
"afro.Asiatic Language\n"
Locales::get_cldr_plural_category_list()
Returns a list of plural categories that CLDR uses.
With no argument, the order is what is appropriate for some noun quantifying localization methods.
With a true argument, the order is the order it makes sense to check their corresponding rules in.
Locales::plural_rule_string_to_code()
This is used under the hood to facilitate get_plural_form(). That being the case there probably isn't
much use for it to be used directly.
This takes the plural rule string as found in the CLDR XML and returns an eval()able perl code
version of it.
It will carp "Unknown plural rule syntax" and return; if it does not understand what you sent.
A second, optional, argument is the value to return if the rule matches.
If you eval the returned string you'll have a code reference that returns true (or whatever you give
it) if the rule matched the given number or not:
my $perly = Locales::plural_rule_string_to_code("n is 42 or n mod 42 is not 7");
my $check = eval $perly;
my $plural_category = $check->(42);
Locales::plural_rule_hashref_to_code()
This is used under the hood to facilitate get_plural_form(). That being the case there probably isn't
much use for it to be used directly.
This takes a hashref that contains rules, puts them in the hash, and returns an overall code ref. Its
pretty internal so if you really need the details have a gander at the source.
Locales::plural_rule_string_to_javascript_code
Same as Locales::plural_rule_string_to_code() except it returns javascript code instead of perl code.
Used internally when building this distribution’s share/misc_info contents.
Install Now
PNG Icons
Emojis
SVG Icons