Skip to content
Localized number formatters using the Unicode CLDR
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
t implement minimum_grouping_digits [#36] Sep 23, 2015
.gitignore add .gitignore Mar 31, 2014
Build.PL require Class::Method::Modifiers Apr 5, 2016
MANIFEST prepare v0.19 Apr 6, 2016


Build status Coverage status CPAN version


CLDR::Number - Localized number formatters using the Unicode CLDR


This document describes CLDR::Number v0.19, built with Unicode CLDR v29.


use CLDR::Number;

# new object with 'es' (Spanish) locale
$cldr = CLDR::Number->new(locale => 'es');

# decimals
$decf = $cldr->decimal_formatter;

# when locale is 'es' (Spanish)
say $decf->format(1234.5);  # '1234,5'

# when locale is 'es-MX' (Mexican Spanish)
say $decf->format(1234.5);  # '1,234.5'

# when locale is 'ar' (Arabic)
say $decf->format(1234.5);  # '١٬٢٣٤٫٥'

# percents
$perf = $cldr->percent_formatter;

# when locale is 'tr' (Turkish)
say $perf->format(0.05);  # '%5'

# currencies
$curf = $cldr->currency_formatter(currency_code => 'USD');

# when locale is 'en' (English) and currency is USD (US dollars)
say $curf->format(9.99);  # '$9.99'

# when locale is 'en-CA' (Canadian English) and currency is USD
say $curf->format(9.99);  # 'US$9.99'

# when locale is 'fr-CA' (Canadian French) and currency is USD
say $curf->format(9.99);  # '9,99 $ US'


Using the locale method as a setter is deprecated. In the future the object’s locale will become immutable. Please see issue #38 for details and to submit comments or concerns.


Software localization includes much more than just translations. Numbers, prices, and even percents should all be localized based on the user’s language, script, and region. Fortunately, the Unicode Common Locale Data Repository (CLDR) provides locale data and specifications for formatting numeric data to use with many of the world’s locales.

This class provides common attributes shared among the supported formatter classes as well as methods to instantiate decimal, percent, and currency formatter objects. The value for any attribute (such as locale or decimal_sign) will be passed to the formatter objects on instantiation but can be overwritten by manually passing another value for the attribute or calling a setter method on the formatter object.


  • decimal_formatter

    Returns a decimal formatter, which is a CLDR::Number::Format::Decimal object instantiated with all of the attributes from your CLDR::Number object as well as any attributes passed to this method.

  • percent_formatter

    Returns a percent formatter, which is a CLDR::Number::Format::Percent object instantiated with all of the attributes from your CLDR::Number object as well as any attributes passed to this method.

  • currency_formatter

    Returns a currency formatter, which is a CLDR::Number::Format::Currency object instantiated with all of the attributes from your CLDR::Number object as well as any attributes passed to this method.

Common Attributes

These are common attributes among this class and all formatter classes. All attributes other than locale, default_locale, and cldr_version have defaults that change depending on the current locale. All string attributes are expected to be character strings, not byte strings.

  • locale

    Default: value of default_locale attribute if it exists, otherwise root

    Valid: Unicode locale identifiers

    Examples: es (Spanish), es-ES (European Spanish), es-419 (Latin American Spanish), zh-Hant (Traditional Chinese), zh-Hans (Simplified Chinese), chr (Cherokee)

    The locale is case-insensitive and can use either - (hyphen-minus) or _ (low line) as a separator.

  • default_locale

    Default: none

    Valid: Unicode locale identifiers

    Use this if you want a locale other than the generic root if the locale attribute is not set or not valid.

  • numbering_system

    Valid: currently only decimal numbering systems are supported

    Examples: latn (Western Digits), arab (Arabic-Indic Digits), hanidec (Chinese Decimal Numerals), fullwide (Full Width Digits)

    In the future, algorithmic numbering systems like hant (Traditional Chinese Numerals), hebr (Hebrew Numerals), and roman (Roman Numerals) will be supported.

    The numbering system may alternately be provided as a Unicode locale extension subtag. For example, locale ja-u-nu-fullwide for the Japanese language (ja) with the numbering system (nu) set to Full Width Digits (fullwide).

  • decimal_sign

    Examples: . (full stop) for root, en; , (comma) for de, fr

  • group_sign

    Examples: , (comma) for root, en; . (full stop) for de;   (no-break space) for fr

  • plus_sign

    Examples: + (plus sign) for root, en, and most locales

  • minus_sign

    Examples: - (hyphen-minus) for root, en, and most locales

  • infinity

    Examples: (infinity) for root, en, and almost all locales

  • nan

    Examples: NaN for root, en, and most locales; many other variations for individual locales like не число for ru and 非數值 for zh-Hant

  • cldr_version

    Value: 29

    This is a read-only attribute that will always reflect the currently supported Unicode CLDR version.


The Unicode private-use characters U+F8F0 through U+F8F4 are used internally and are therefore not supported in custom patterns and signs.



Nova Patch <>

This project is brought to you by Shutterstock. Additional open source projects from Shutterstock can be found at


© 2013–2016 Shutterstock, Inc.

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

Unicode is a registered trademark of Unicode, Inc., in the United States and other countries.

You can’t perform that action at this time.