[Unicode]  Technical Reports
 

Unicode Technical Standard #35

Unicode Locale Data Markup Language (LDML)
Part 3: Numbers

Version 46.1
Editors Shane F. Carr (shane@unicode.org) and other CLDR committee members

For the full header, summary, and status, see Part 1: Core.

Summary

This document describes parts of an XML format (vocabulary) for the exchange of structured locale data. This format is used in the Unicode Common Locale Data Repository.

This is a partial document, describing only those parts of the LDML that are relevant for number and currency formatting. For the other parts of the LDML see the main LDML document and the links above.

Status

This document has been reviewed by Unicode members and other interested parties, and has been approved for publication by the Unicode Consortium. This is a stable document and may be used as reference material or cited as a normative reference by other specifications.

A Unicode Technical Standard (UTS) is an independent specification. Conformance to the Unicode Standard does not imply conformance to any UTS.

Please submit corrigenda and other comments with the CLDR bug reporting form [Bugs]. Related information that is useful in understanding this document is found in the References. For the latest version of the Unicode Standard see [Unicode]. For more information see About Unicode Technical Reports and the Specifications FAQ. Unicode Technical Reports are governed by the Unicode Terms of Use.

Parts

The LDML specification is divided into the following parts:

Contents of Part 3, Numbers

Numbering Systems

<!ELEMENT numberingSystems ( numberingSystem* ) >
<!ELEMENT numberingSystem EMPTY >
<!ATTLIST numberingSystem id NMTOKEN #REQUIRED >
<!ATTLIST numberingSystem type ( numeric | algorithmic ) #REQUIRED >
<!ATTLIST numberingSystem radix NMTOKEN #IMPLIED >
<!ATTLIST numberingSystem digits CDATA #IMPLIED >
<!ATTLIST numberingSystem rules CDATA #IMPLIED >

Numbering systems information is used to define different representations for numeric values to an end user. Numbering systems are defined in CLDR as one of two different types: algorithmic and numeric. Numeric systems are simply a decimal based system that uses a predefined set of digits to represent numbers. Examples are Western digits (ASCII digits), Thai digits, Devanagari digits. Algorithmic systems are more complex in nature, since the proper formatting and presentation of a numeric quantity is based on some algorithm or set of rules. Examples are Chinese numerals, Hebrew numerals, or Roman numerals. In CLDR, the rules for presentation of numbers in an algorithmic system are defined using the RBNF syntax described in Section 6: Rule-Based Number Formatting.

Attributes for the <numberingSystem> element are as follows:

Examples:

<!-- ASCII digits - A numeric system -->
<numberingSystem id="latn" type="numeric" digits="0123456789"/>

<!-- A numeric system using Thai digits -->
<numberingSystem id="thai" type="numeric" digits="๐๑๒๓๔๕๖๗๘๙"/>

<!-- An algorithmic system - Georgian numerals, rules found in NumberingSystemRules -->
<numberingSystem id="geor" type="algorithmic" rules="georgian"/>

<!-- An algorithmic system. Traditional Chinese numerals -->
<numberingSystem id="hant" type="algorithmic" rules="zh_Hant/SpelloutRules/spellout-cardinal"/>

For general information about the numbering system data, including the BCP47 identifiers, see the main document Section Q.1.1 Numbering System Data.

Number Elements

<!ELEMENT numbers ( alias | ( defaultNumberingSystem*, otherNumberingSystems*, minimumGroupingDigits*, symbols*, decimalFormats*, scientificFormats*, percentFormats*, currencyFormats*, currencies?, miscPatterns*, minimalPairs*, special* ) ) >

The numbers element supplies information for formatting and parsing numbers and currencies. It has the following sub-elements: <defaultNumberingSystem>, <otherNumberingSystems>, <symbols>, <decimalFormats>, <scientificFormats>, <percentFormats>, <currencyFormats>, and <currencies>. The currency IDs are from [ISO4217] (plus some additional common-use codes). For more information, including the pattern structure, see Section 3: Number Format Patterns.

Default Numbering System

<!ELEMENT defaultNumberingSystem ( #PCDATA )>

This element indicates which numbering system should be used for presentation of numeric quantities in the given locale.

Other Numbering Systems

<!ELEMENT otherNumberingSystems ( alias | ( native*, traditional*, finance*)) >

This element defines general categories of numbering systems that are sometimes used in the given locale for formatting numeric quantities. These additional numbering systems are often used in very specific contexts, such as in calendars or for financial purposes. There are currently three defined categories, as follows:

native

Defines the numbering system used for the native digits, usually defined as a part of the script used to write the language. The native numbering system can only be a numeric positional decimal-digit numbering system, using digits with General_Category=Decimal_Number. Note: In locales where the native numbering system is the default, it is assumed that the numbering system "latn" (Western digits 0-9) is always acceptable, and can be selected using the -nu keyword as part of a Unicode locale identifier.

traditional

Defines the traditional numerals for a locale. This numbering system may be numeric or algorithmic. If the traditional numbering system is not defined, applications should use the native numbering system as a fallback.

finance

Defines the numbering system used for financial quantities. This numbering system may be numeric or algorithmic. This is often used for ideographic languages such as Chinese, where it would be easy to alter an amount represented in the default numbering system simply by adding additional strokes. If the financial numbering system is not specified, applications should use the default numbering system as a fallback.

The categories defined for other numbering systems can be used in a Unicode locale identifier to select the proper numbering system without having to know the specific numbering system by name. For example:

For more information on numbering systems and their definitions, see Section 1: Numbering Systems.

Number Symbols

<!ELEMENT symbols (alias | (decimal*, group*, list*, percentSign*, nativeZeroDigit*, patternDigit*, plusSign*, minusSign*, approximatelySign*, exponential*, superscriptingExponent*, perMille*, infinity*, nan*, currencyDecimal*, currencyGroup*, timeSeparator*, special*)) >

Number symbols define the localized symbols that are commonly used when formatting numbers in a given locale. These symbols can be referenced using a number formatting pattern as defined in Section 3: Number Format Patterns.

The available number symbols are as follows:

decimal

separates the integer and fractional part of the number.

group

separates clusters of integer digits to make large numbers more legible; commonly used for thousands (grouping size 3, e.g. "100,000,000") or in some locales, ten-thousands (grouping size 4, e.g. "1,0000,0000"). There may be two different grouping sizes: The primary grouping size used for the least significant integer group, and the secondary grouping size used for more significant groups; these are not the same in all locales (e.g. "12,34,56,789"). If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".

list

symbol used to separate numbers in a list intended to represent structured data such as an array; must be different from the decimal value. This list separator is for “non-linguistic” usage as opposed to the listPatterns for “linguistic” lists (e.g. “Bob, Carol, and Ted”) described in Part 2, List Patterns.

percentSign

symbol used to indicate a percentage (1/100th) amount. (If present, the value is also multiplied by 100 before formatting. That way 1.23 → 123%)

nativeZeroDigit

Deprecated - do not use.

patternDigit

Deprecated. This was formerly used to provide the localized pattern character corresponding to '#', but localization of the pattern characters themselves has been deprecated for some time (determining the locale-specific replacements for pattern characters is of course not deprecated and is part of normal number formatting).

minusSign

Symbol used to denote negative value.

plusSign

Symbol used to denote positive value. It can be used to produce modified patterns, so that 3.12 is formatted as "+3.12", for example. The standard number patterns (except for type="accounting") will contain the minusSign, explicitly or implicitly. In the explicit pattern, the value of the plusSign can be substituted for the value of the minusSign to produce a pattern that has an explicit plus sign.

approximatelySign

Symbol used to denote a value that is approximate but not exact. The symbol is substituted in place of the minusSign using the same semantics as plusSign substitution.

exponential

Symbol separating the mantissa and exponent values.

superscriptingExponent

(Programmers are used to the fallback exponent style “1.23E4”, but that should not be shown to end-users. Instead, the exponential notation superscriptingExponent should be used to show a format like “1.23 × 104”. ) The superscripting can use markup, such as <sup>4</sup> in HTML, or for the special case of Latin digits, use the superscript characters: U+207B ( ⁻ ), U+2070 ( ⁰ ), U+00B9 ( ¹ ), U+00B2 ( ² ), U+00B3 ( ³ ), U+2074 ( ⁴ ) .. U+2079 ( ⁹ ).

perMille

symbol used to indicate a per-mille (1/1000th) amount. (If present, the value is also multiplied by 1000 before formatting. That way 1.23 → 1230 [1/000])

infinity

The infinity sign. Corresponds to the IEEE infinity bit pattern.

nan - Not a number

The NaN sign. Corresponds to the IEEE NaN bit pattern.

currencyDecimal

Optional. If specified, then for currency formatting/parsing this is used as the decimal separator instead of using the regular decimal separator; otherwise, the regular decimal separator is used.

currencyGroup

Optional. If specified, then for currency formatting/parsing this is used as the group separator instead of using the regular group separator; otherwise, the regular group separator is used.

timeSeparator

This replaces any use of the timeSeparator pattern character in a date-time format pattern (no timeSeparator pattern character is currently defined, see note below). This allows the same time format to be used for multiple number systems when the time separator depends on the number system. For example, the time format for Arabic should be COLON when using the Latin numbering system (0, 1, 2, …), but when the Arabic numbering system is used (٠‎ - ١‎ - ٢‎ …), the traditional time separator in older print styles was often ARABIC COMMA.

Note: In CLDR 26 the timeSeparator pattern character was specified to be COLON. This was withdrawn in CLDR 28 due to backward compatibility issues, and no timeSeparator pattern character is currently defined. No CLDR locales are known to have a need to specify timeSeparator symbols that depend on number system; if this changes in the future a different timeSeparator pattern character will be defined. In the meantime, since CLDR data consumers can still request the timeSeparator symbol, it should match the symbol actually used in the timeFormats and availableFormats items.

Example:

<symbols>
    <decimal>.</decimal>
    <group>,</group>
    <list>;</list>
    <percentSign>%</percentSign>
    <patternDigit>#</patternDigit>
    <plusSign>+</plusSign>
    <minusSign>-</minusSign>
    <approximatelySign>~</approximatelySign>
    <exponential>E</exponential>
    <superscriptingExponent>×</superscriptingExponent>
    <perMille>‰</perMille>
    <infinity>∞</infinity>
    <nan>☹</nan>
    <timeSeparator>:</timeSeparator>
</symbols>

<!ATTLIST symbols numberSystem CDATA #IMPLIED >

The numberSystem attribute is used to specify that the given number symbols are to be used when the given numbering system is active. Number symbols can only be defined for numbering systems of the "numeric" type, since any special symbols required for an algorithmic numbering system should be specified by the RBNF formatting rules used for that numbering system. By default, number symbols without a specific numberSystem attribute are assumed to be used for the "latn" numbering system, which is western (ASCII) digits. Locales that specify a numbering system other than "latn" as the default should also specify number formatting symbols that are appropriate for use within the context of the given numbering system. For example, a locale that uses the Arabic-Indic digits as its default would likely use an Arabic comma for the grouping separator rather than the ASCII comma. For more information on numbering systems and their definitions, see Section 1: Numbering Systems.

Number Formats

<!ELEMENT decimalFormats (alias | (default*, decimalFormatLength*, special*)) >
<!ELEMENT decimalFormatLength (alias | (default*, decimalFormat*, special*)) >
<!ATTLIST decimalFormatLength type ( full | long | medium | short ) #IMPLIED >
<!ELEMENT decimalFormat (alias | (pattern*, special*)) >

(scientificFormats, percentFormats have the same structure)

Number formats are used to define the rules for formatting numeric quantities using the pattern syntax described in Section 3: Number Format Patterns.

Different formats are provided for different contexts, as follows:

decimalFormats

The normal locale specific way to write a base 10 number. Variations of the decimalFormat pattern are provided that allow compact number formatting.

percentFormats

Pattern for use with percentage formatting

scientificFormats

Pattern for use with scientific (exponent) formatting.

Example:

<decimalFormats>
  <decimalFormatLength type="long">
    <decimalFormat>
      <pattern>#,##0.###</pattern>
    </decimalFormat>
  </decimalFormatLength>
</decimalFormats>

<scientificFormats>
  <default type="long"/>
  <scientificFormatLength type="long">
    <scientificFormat>
      <pattern>0.000###E+00</pattern>
    </scientificFormat>
  </scientificFormatLength>
  <scientificFormatLength type="medium">
    <scientificFormat>
      <pattern>0.00##E+00</pattern>
    </scientificFormat>
  </scientificFormatLength>
</scientificFormats>

<percentFormats>
  <percentFormatLength type="long">
    <percentFormat>
      <pattern>#,##0%</pattern>
    </percentFormat>
  </percentFormatLength>
</percentFormats>

<!ATTLIST symbols numberSystem CDATA #IMPLIED >

The numberSystem attribute is used to specify that the given number formatting pattern(s) are to be used when the given numbering system is active. By default, number formatting patterns without a specific numberSystem attribute are assumed to be used for the "latn" numbering system, which is western (ASCII) digits. Locales that specify a numbering system other than "latn" as the default should also specify number formatting patterns that are appropriate for use within the context of the given numbering system. For more information on numbering systems and their definitions, see Section 1: Numbering Systems.

Compact Number Formats

A pattern type attribute is used for compact number formats, such as the following:

<decimalFormatLength type="long">
    <decimalFormat>
        <pattern type="1000" count="one">0 millier</pattern>
        <pattern type="1000" count="other">0 milliers</pattern>
        <pattern type="10000" count="one">00 mille</pattern>
        <pattern type="10000" count="other">00 mille</pattern>
        <pattern type="100000" count="one">000 mille</pattern>
        <pattern type="100000" count="other">000 mille</pattern>
        <pattern type="1000000" count="one">0 million</pattern>
        <pattern type="1000000" count="other">0 millions</pattern>
        …
    </decimalFormat>
</decimalFormatLength>
<decimalFormatLength type="short">
    <decimalFormat>
        <pattern type="1000" count="one">0 K</pattern>
        <pattern type="1000" count="other">0 K</pattern>
        <pattern type="10000" count="one">00 K</pattern>
        <pattern type="10000" count="other">00 K</pattern>
        <pattern type="100000" count="one">000 K</pattern>
        <pattern type="100000" count="other">000 K</pattern>
        <pattern type="1000000" count="one">0 M</pattern>
        <pattern type="1000000" count="other">0 M</pattern>
        …
    </decimalFormat>
…
<currencyFormatLength type="short">
    <currencyFormat type="standard">
        <pattern type="1000" count="one">0 K ¤</pattern>
        <pattern type="1000" count="other">0 K ¤</pattern>
        <pattern type="10000" count="one">00 K ¤</pattern>
        <pattern type="10000" count="other">00 K ¤</pattern>
        <pattern type="100000" count="one">000 K ¤</pattern>
        <pattern type="100000" count="other">000 K ¤</pattern>
        <pattern type="1000000" count="one">0 M ¤</pattern>
        <pattern type="1000000" count="other">0 M ¤</pattern>

Formats can be supplied for numbers (as above) or for currencies or other units. They can also be used with ranges of numbers, resulting in formatting strings like “$10K” or “$3–7M”.

To format a number N, the greatest type less than or equal to N is used, with the appropriate plural category. N is divided by the type, after removing the number of zeros in the pattern, less 1. APIs supporting this format should provide control over the number of significant or fraction digits.

The default pattern for any type that is not supplied is the special value “0”, as in the following. The value “0” must be used when a child locale overrides a parent locale to drop the compact pattern for that type and use the default pattern.

<pattern type="1" count="one">0</pattern>

If the value is precisely “0”, either explicit or defaulted, then the normal number format pattern for that sort of object is supplied — either <decimalFormat> or <currencyFormat type="standard"> — with the normal formatting for the locale (such as the grouping separators). However, for the “0” case by default the significant digits are adjusted for consistency, typically to 2 or 3 digits, and the maximum fractional digits are set to 0 (for both currencies and plain decimal). Thus the output would be $12, not $12.01. APIs may, however, allow these default behaviors to be overridden.

With the data above, N=12345 matches <pattern type="10000" count="other">00 K</pattern>. N is divided by 1000 (obtained from 10000 after removing "00" and restoring one "0"). The result is formatted according to the normal decimal pattern. With no fractional digits, that yields "12 K".

Formatting 1200 in USD would result in “1.2 K $”, while 990 implicitly maps to the special value “0”, which maps to <currencyFormat type="standard"><pattern>#,##0.00 ¤</pattern>, and would result in simply “990 $”.

The short format is designed for UI environments where space is at a premium, and should ideally result in a formatted string no more than about 6 em wide (with no fractional digits).

Currency Formats

Patterns for use with currency formatting:

<!ELEMENT currencyFormats (alias | (default*, currencySpacing*, currencyFormatLength*, currencyPatternAppendISO*, unitPattern*, special*)) >
<!ELEMENT currencyFormatLength (alias | (default*, currencyFormat*, special*)) >
<!ATTLIST currencyFormatLength type ( full | long | medium | short ) #IMPLIED >
<!ELEMENT currencyFormat (alias | (pattern*, special*)) >
<!ATTLIST currencyFormat type NMTOKEN "standard" >
    <!--@MATCH:literal/accounting, standard-->
<!ELEMENT currencyPatternAppendISO ( #PCDATA ) >

The following additional elements were intended to allow proper placement of the currency symbol relative to the numeric quantity. These are specified in the root locale and typically not overridden in any other locale. However, as of CLDR 42, the preferred approach to controlling placement of the currency symbol is use of the alt="alphaNextToNumber" variant for currencyFormat patterns. See below and - Currencies for additional information on the use of these options.

<!ELEMENT currencySpacing (alias | (beforeCurrency*, afterCurrency*, special*)) >
<!ELEMENT beforeCurrency (alias | (currencyMatch*, surroundingMatch*, insertBetween*)) >
<!ELEMENT afterCurrency (alias | (currencyMatch*, surroundingMatch*, insertBetween*)) >
<!ELEMENT currencyMatch ( #PCDATA ) >
<!ELEMENT surroundingMatch ( #PCDATA )) >
<!ELEMENT insertBetween ( #PCDATA ) >

In addition to a standard currency format, in which negative currency amounts might typically be displayed as something like “-$3.27”, locales may provide an "accounting" form, in which for "en_US" the same example would appear as “($3.27)”. The locale keyword "cf" can be used to select the standard or accounting form, see Unicode Currency Format Identifier.

<currencyFormats>
    <currencyFormatLength>
        <currencyFormat type="standard">
            <pattern>¤#,##0.00</pattern>
            <pattern alt="alphaNextToNumber">¤ #,##0.00</pattern>
            <pattern alt="noCurrency">#,##0.00</pattern>
        </currencyFormat>
        <currencyFormat type="accounting">
            <pattern>¤#,##0.00;(¤#,##0.00)</pattern>
            <pattern alt="alphaNextToNumber">¤ #,##0.00;(¤ #,##0.00)</pattern>
            <pattern alt="noCurrency">#,##0.00;(#,##0.00)</pattern>
        </currencyFormat>
    </currencyFormatLength>
    <currencyFormatLength type="short">
        <currencyFormat type="standard">
            <pattern type="1000" count="one">¤0K</pattern>
            <pattern type="1000" count="one" alt="alphaNextToNumber">¤ 0K</pattern>
            <pattern type="1000" count="other">¤0K</pattern>
            <pattern type="1000" count="other" alt="alphaNextToNumber">¤ 0K</pattern>
            ...
            <pattern type="100000000000000" count="other">¤000T</pattern>
            <pattern type="100000000000000" count="other" alt="alphaNextToNumber">¤ 000T</pattern>
        </currencyFormat>
    </currencyFormatLength>
</currencyFormats>

The alt="alphaNextToNumber" pattern, if available, should be used instead of the standard pattern when the currency symbol character closest to the numeric value has Unicode General Category L (letter). The alt="alphaNextToNumber" pattern is typically provided when the standard currency pattern does not have a space between currency symbol and numeric value; the alphaNextToNumber variant adds a non-breaking space if appropriate for the locale.

The alt="noCurrency" pattern can be used when a currency-style format is desired but without the currency symbol. This sort of display may be used when formatting a large column of values all in the same currency, for example. For compact currency formats (<currencyFormatLength type="short">), the compact decimal format (<decimalFormatLength type="short">) should be used if no alt="noCurrency" pattern is present (so the alt="noCurrency" pattern is typically not needed for compact currency formats).

<currencyPatternAppendISO>{0} ¤¤</currencyPatternAppendISO>

The currencyPatternAppendISO element provides a pattern that can be used to combine currency format that uses a currency symbol (¤ or ¤¤¤¤¤) with the ISO 4217 3-letter code for the same currency (¤¤), to produce a result such as “$1,432.00 USD”. Using such a format is only recommended to resolve ambiguity when:

Miscellaneous Patterns

<!ELEMENT miscPatterns (alias | (default*, pattern*, special*)) >
<!ATTLIST miscPatterns numberSystem CDATA #IMPLIED >

The miscPatterns supply additional patterns for special purposes. The currently defined values are:

approximately

indicates an approximate number, such as: “~99”. This pattern is not currently in use; see ICU-20163.

atMost

indicates a number or lower, such as: “≤99” to indicate that there are 99 items or fewer.

atLeast

indicates a number or higher, such as: “99+” to indicate that there are 99 items or more.

range

indicates a range of numbers, such as: “99–103” to indicate that there are from 99 to 103 items.

For example:

<miscPatterns numberSystem="…">
  <pattern type="approximately">~{0}</pattern>
  <pattern type="atLeast">≥{0}</pattern>
  <pattern type="atMost">≤{0}</pattern>
  <pattern type="range">{0}–{1}</pattern>
</miscPatterns>

Minimal Pairs

<!ELEMENT minimalPairs ( alias | ( pluralMinimalPairs*, ordinalMinimalPairs*, caseMinimalPairs*, genderMinimalPairs*, special* ) ) >

<!ELEMENT pluralMinimalPairs ( #PCDATA ) >
<!ATTLIST pluralMinimalPairs count NMTOKEN #IMPLIED >

<!ELEMENT ordinalMinimalPairs ( #PCDATA ) >
<!ATTLIST ordinalMinimalPairs ordinal NMTOKEN #IMPLIED >

<!ELEMENT caseMinimalPairs ( #PCDATA ) >
<!ATTLIST caseMinimalPairs case NMTOKEN #REQUIRED >

<!ELEMENT genderMinimalPairs ( #PCDATA ) >
<!ATTLIST genderMinimalPairs gender NMTOKEN #REQUIRED >

Minimal pairs provide examples that justify why multiple plural or ordinal categories exist, and for providing contextual examples for verifying consistency of translations. The allowable values for the count, ordinal, case, and gender attributes are found in the dtd file.

Examples

<minimalPairs>
    <pluralMinimalPairs count="one">{0} Tag</pluralMinimalPairs>
    <pluralMinimalPairs count="other">{0} Tage</pluralMinimalPairs>

    <ordinalMinimalPairs ordinal="other">{0}. Abzweigung nach rechts nehmen</ordinalMinimalPairs>

    <caseMinimalPairs case="accusative">… für {0} …</caseMinimalPairs>
    <caseMinimalPairs case="dative">… mit {0} …</caseMinimalPairs>
    <caseMinimalPairs case="genitive">Anstatt {0} …</caseMinimalPairs>
    <caseMinimalPairs case="nominative">{0} kostet (kosten) € 3,50.</caseMinimalPairs>

    <genderMinimalPairs gender="feminine">Die {0} ist …</genderMinimalPairs>
    <genderMinimalPairs gender="masculine">Der {0} ist …</genderMinimalPairs>
    <genderMinimalPairs gender="neuter">Das {0} ist …</genderMinimalPairs>
</minimalPairs>

For more information, see Plural Rules and Grammatical Inflection.

Number Format Patterns

Number Patterns

Number patterns affect how numbers are interpreted in a localized context. Here are some examples, based on the French locale. The "." shows where the decimal point should go. The "," shows where the thousands separator should go. A "0" indicates zero-padding: if the number is too short, a zero (in the locale's numeric set) will go there. A "#" indicates no padding: if the number is too short, nothing goes there. A "¤" shows where the currency sign will go. The following illustrates the effects of different patterns for the French locale, with the number "1234.567". Notice how the pattern characters ',' and '.' are replaced by the characters appropriate for the locale.

Table: Number Pattern Examples
Pattern Currency Text
#,##0.## n/a 1 234,57
#,##0.### n/a 1 234,567
###0.##### n/a 1234,567
###0.0000# n/a 1234,5670
00000.0000 n/a 01234,5670
#,##0.00 ¤ EUR 1 234,57 €
JPY 1 235 ¥JP

The number of # placeholder characters before the decimal does not matter, since no limit is placed on the maximum number of digits. There should, however, be at least one zero someplace in the pattern. In currency formats, the number of digits after the decimal also does not matter, since the information in the supplemental data (see Supplemental Currency Data) is used to override the number of decimal places — and the rounding — according to the currency that is being formatted. That can be seen in the above chart, with the difference between Yen and Euro formatting.

To ensure correct layout, especially in currency patterns in which a variety of symbols may be used, number patterns may contain (invisible) bidirectional text format characters such as LRM, RLM, and ALM.

When parsing using a pattern, a lenient parse should be used; see Lenient Parsing. As noted there, lenient parsing should ignore bidi format characters.

Special Pattern Characters

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit for the chosen numberSystem. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.

To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below. The Localized Replacement column shows the replacement from Number Symbols or the numberSystem's digits: italic indicates a special function.

Invalid sequences of special characters (such as “¤¤¤¤¤¤” in current CLDR) should be handled for formatting and parsing as described in Handling Invalid Patterns.

Table: Number Pattern Character Definitions
Symbol Location Localized Replacement Meaning
0 Number digit Digit
1-9 Number digit '1' through '9' indicate rounding.
@ Number digit Significant digit
# Number digit, nothing Digit, omitting leading/trailing zeros
. Number decimal, currencyDecimal Decimal separator or monetary decimal separator
- Number minusSign, plusSign, approximatelySign Minus sign. Warning: the pattern '-'0.0 is not the same as the pattern -0.0. In the former case, the minus sign is a literal. In the latter case, it is a special symbol, which is replaced by the minusSymbol, and can also be replaced by the plusSymbol for a format like +12% as in Explicit Plus Signs.
, Number group, currencyGroup Grouping separator. May occur in both the integer part and the fractional part. The position determines the grouping.
E Number exponential, superscriptingExponent Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
+ Exponent or Number (for explicit plus) plusSign Prefix positive exponents with localized plus sign. Used for explicit plus for numbers as well, as described in Explicit Plus Signs. Need not be quoted in prefix or suffix.
% Prefix or suffix percentSign Multiply by 100 and show as percentage
‰ (U+2030) Prefix or suffix perMille Multiply by 1000 and show as per mille (aka “basis points”)
; Subpattern boundary syntax Separates positive and negative subpatterns. When there is no explicit negative subpattern, an implicit negative subpattern is formed from the positive pattern with a prefixed - (ASCII U+002D HYPHEN-MINUS).
¤ (U+00A4) Prefix or suffix currency symbol/name from currency specified in API Any sequence is replaced by the localized currency symbol for the currency being formatted, as in the table below. If present in a pattern, the monetary decimal separator and grouping separators (if available) are used instead of the numeric ones. If data is unavailable for a given sequence in a given locale, the display may fall back to ¤ or ¤¤. See also the formatting for currency display names, steps 2 and 4 in Currencies.
No.Replacement / Example
¤Standard currency symbol
C$12.00
¤¤ISO currency symbol (constant)
CAD 12.00
¤¤¤Appropriate currency display name for the currency, based on the plural rules in effect for the locale
5.00 Canadian dollars
¤¤¤¤¤Narrow currency symbol. The same symbols may be used for multiple currencies. Thus the symbol may be ambiguous, and should only be where the context is clear.
$12.00
othersInvalid in current CLDR. Reserved for future specification
* Prefix or suffix boundary padding character specified in API Pad escape, precedes pad character
' Prefix or suffix syntax-only Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

A pattern contains a positive subpattern and may contain a negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a suffix. If there is no explicit negative subpattern, the implicit negative subpattern is the ASCII minus sign (-) prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". (The data in CLDR is normalized to remove an explicit negative subpattern where it would be identical to the implicit form.)

Note that if a negative subpattern is used as-is: a minus sign is not added, eg "0.00;0.00" ≠ "0.00;-0.00". Trailing semicolons are ignored, eg "0.00;" = "0.00". Whitespace is not ignored, including those around semicolons, so "0.00 ; -0.00" ≠ "0.00;-0.00".

If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. That means that "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)". However in the CLDR data, the format is normalized so that the other characteristics are preserved, just for readability.

Note: The thousands separator and decimal separator in patterns are always ASCII ',' and '.'. They are substituted by the code with the correct local values according to other fields in CLDR. The same is true of the - (ASCII minus sign) and other special characters listed above.

A currency decimal pattern normally contains a currency symbol placeholder (¤, ¤¤, ¤¤¤, or ¤¤¤¤¤). The currency symbol placeholder may occur before the first digit, after the last digit symbol, or where the decimal symbol would otherwise be placed (for formats such as "12€50", as in "12€50 pour une omelette").

Placement Examples
Before "¤#,##0.00" "¤ #,##0.00" "¤-#,##0.00" "¤ -#,##0.00" "-¤#,##0.00" "-¤ #,##0.00" …
After "#,##0.00¤" "#,##0.00 ¤" "#,##0.00-¤" "#,##0.00- ¤" "#,##0.00¤-" "#,##0.00 ¤-" …
Decimal "#,##0¤00"

Below is a sample of patterns, special characters, and results:

Table: Sample Patterns and Results
explicit pattern:0.00;-0.000.00;0.00-0.00+;0.00-
decimalSign:,,,
minusSign:∸∸∸
plusSign:∔∔∔
number:3.1415-3.14153.1415-3.14153.1415-3.1415
formatted:3,14∸3,143,143,14∸3,14∔3,14∸

In the above table, ∸ = U+2238 DOT MINUS and ∔ = U+2214 DOT PLUS are used for illustration.

The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, and so on may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict, or parsing will be unreliable. For example, either the positive and negative prefixes or the suffixes must be distinct for any parser using this data to be able to distinguish positive from negative values. Another example is that the decimal separator and thousands separator should be distinct characters, or parsing will be impossible.

The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It is commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000". There are actually two different grouping sizes: One used for the least significant integer digits, the primary grouping size, and one used for all others, the secondary grouping size. In most locales these are the same, but sometimes they are different. For example, if the primary grouping interval is 3, and the secondary is 2, then this corresponds to the pattern "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".

The grouping separator may also occur in the fractional part, such as in “#,##0.###,#”. This is most commonly done where the grouping separator character is a thin, non-breaking space (U+202F), such as “1.618 033 988 75”. See physics.nist.gov/cuu/Units/checklist.html.

For consistency in the CLDR data, the following conventions are observed:

Explicit Plus Signs

An explicit "plus" format can be formed, so as to show a visible + sign when formatting a non-negative number. The displayed plus sign can be an ASCII plus or another character, such as ＋ U+FF0B FULLWIDTH PLUS SIGN or ➕ U+2795 HEAVY PLUS SIGN; it is taken from whatever is set for plusSign in Number Symbols.

  1. Get the negative subpattern (explicit or implicit).
  2. Replace any unquoted ASCII minus sign by an ASCII plus sign.
  3. If there are any replacements, use that for the positive subpattern.

For an example, see Sample Patterns and Results.

Formatting

Formatting is guided by several parameters, all of which can be specified either using a pattern or using an external API designed for number formatting. The following description applies to formats that do not use scientific notation or significant digits.

Special Values

NaN is represented as a single character, typically (U+FFFD) . This character is determined by the localized number symbols. This is the only value for which the prefixes and suffixes are not used.

Infinity is represented as a single character, typically ∞ (U+221E) , with the positive or negative prefixes and suffixes applied. The infinity character is determined by the localized number symbols.

Scientific Notation

Numbers in scientific notation are expressed as the product of a mantissa and a power of ten, for example, 1234 can be expressed as 1.234 x 103. The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), but it need not be. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3".

Significant Digits

There are two ways of controlling how many digits are shown: (a) significant digits counts, or (b) integer and fraction digit counts. Integer and fraction digit counts are described above. When a formatter is using significant digits counts, it uses however many integer and fraction digits are required to display the specified number of significant digits. It may ignore min/max integer/fraction digits, or it may use them to the extent possible.

Table: Significant Digits Examples
Pattern Minimum significant digits Maximum significant digits Number Output
@@@ 3 3 12345 12300
@@@ 3 3 0.12345 0.123
@@## 2 4 3.14159 3.142
@@## 2 4 1.23004 1.23

Padding

Patterns support padding the result to a specific width. In a pattern the pad escape character, followed by a single pad character, causes padding to be parsed and formatted. The pad escape character is '*'. For example, "$*x#,##0.00" formats 123 to "$xx123.00" , and 1234 to "$1,234.00" .

Rounding

Patterns support rounding to a specific increment. For example, 1230 rounded to the nearest 50 is 1250. Mathematically, rounding to specific increments is performed by dividing by the increment, rounding to an integer, then multiplying by the increment. To take a more bizarre example, 1.234 rounded to the nearest 0.65 is 1.3, as follows:

Original:1.234
Divide by increment (0.65):1.89846…
Round:2
Multiply by increment (0.65):1.3

To specify a rounding increment in a pattern, include the increment in the pattern itself. "#,#50" specifies a rounding increment of 50. "#,##0.05" specifies a rounding increment of 0.05.

Quoting Rules

Single quotes (') enclose bits of the pattern that should be treated literally. Inside a quoted string, two single quotes ('') are replaced with a single one ('). For example: 'X '#' Q ' -> X 1939 Q (Literal strings shaded.)

Currencies

<!ELEMENT currencies (alias | (default?, currency*, special*)) >
<!ELEMENT currency (alias | (((pattern+, displayName*, symbol*) | (displayName+, symbol*, pattern*) | (symbol+, pattern*))?, decimal*, group*, special*)) >
<!ELEMENT symbol ( #PCDATA ) >
<!ATTLIST symbol choice ( true | false ) #IMPLIED > <!-- deprecated -->

Note: The term "pattern" appears twice in the above. The first is for consistency with all other cases of pattern + displayName; the second is for backwards compatibility.

<currencies>
    <currency type="USD">
        <displayName>Dollar</displayName>
        <symbol>$</symbol>
    </currency>
    <currency type ="JPY">
        <displayName>Yen</displayName>
        <symbol>¥</symbol>
    </currency>
    <currency type="PTE">
        <displayName>Escudo</displayName>
        <symbol>$</symbol>
    </currency>
</currencies>

In formatting currencies, the currency number format is used with the appropriate symbol from <currencies>, according to the currency code. The <currencies> list can contain codes that are no longer in current use, such as PTE. The choice attribute has been deprecated.

The count attribute distinguishes the different plural forms, such as in the following:

<currencyFormats>
    <unitPattern count="other">{0} {1}</unitPattern>
    …
<currencies>

<currency type="ZWD">
    <displayName>Zimbabwe Dollar</displayName>
    <displayName count="one">Zimbabwe dollar</displayName>
    <displayName count="other">Zimbabwe dollars</displayName>
    <symbol>Z$</symbol>
</currency>

Note on displayNames:

To format a particular currency value "ZWD" for a particular numeric value n using the (long) display name:

  1. If the numeric value is exactly 0 or 1, first see if there is a count with a matching explicit number (0 or 1). If so, use that string (see Explicit 0 and 1 rules).
  2. Otherwise, determine the count value that corresponds to n using the rules in - Language Plural Rules
  3. Next, get the currency unitPattern.
    1. Look for a unitPattern element that matches the count value, starting in the current locale and then following the locale fallback chain up to, but not including root.
    2. If no matching unitPattern element was found in the previous step, then look for a unitPattern element that matches count="other", starting in the current locale and then following the locale fallback chain up to root (which has a unitPattern element with count="other" for every unit type).
    3. The resulting unitPattern element indicates the appropriate positioning of the numeric value and the currency display name.
  4. Next, get the displayName element for the currency.
    1. Look for a displayName element that matches the count value, starting in the current locale and then following the locale fallback chain up to, but not including root.
    2. If no matching displayName element was found in the previous step, then look for a displayName element that matches count="other", starting in the current locale and then following the locale fallback chain up to, but not including root.
    3. If no matching displayName element was found in the previous step, then look for a displayName element with no count, starting in the current locale and then following the locale fallback chain up to root.
    4. If there is no displayName element, use the currency code itself (for example, "ZWD").
  5. Format the numeric value according to the locale. Use the locale’s <decimalFormats …> pattern, not the <currencyFormats> pattern that is used with the symbol (eg, Z$). As when formatting symbol currency values, reset the number of decimals according to the supplemental <currencyData> and use the currencyDecimal symbol if different from the decimal symbol.
    1. The number of decimals should be overridable in an API, so that clients can choose between “2 US dollars” and “2.00 US dollars”.
  6. Substitute the formatted numeric value for the {0} in the unitPattern, and the currency display name for the {1}.

While for English this may seem overly complex, for some other languages different plural forms are used for different unit types; the plural forms for certain unit types may not use all of the plural-form tags defined for the language.

For example, if the currency is ZWD and the number is 1234, then the latter maps to count="other" for English. The unit pattern for that is "{0} {1}", and the display name is "Zimbabwe dollars". The final formatted number is then "1,234 Zimbabwe dollars".

When a currency symbol is substitited into a pattern, some spacing adjustments or other adjustments may be necessary depending on the nature of the symbol. In CLDR 42 and later, the preferred way to handle this is via the alt="alphaNextToNumber" variant of the currencyFormat pattern, as described in Section 2.4.2: Currency Formats. In earlier versions of CLDR this was handled via the currencySpacing element as described below. This element is still present in CLDR 42 and its use is described below for implementations that may not yet support the alt="alphaNextToNumber" variant of the currencyFormat pattern.

<currencySpacing>
  <beforeCurrency>
    <currencyMatch>[:^S:]</currencyMatch>
    <surroundingMatch>[:digit:]</surroundingMatch>
    <insertBetween> </insertBetween>
  </beforeCurrency>
  <afterCurrency>
    <currencyMatch>[:^S:]</currencyMatch>
    <surroundingMatch>[:digit:]</surroundingMatch>
    <insertBetween> </insertBetween>
  </afterCurrency>
</currencySpacing>

This element controls whether additional characters are inserted on the boundary between the symbol and the pattern. For example, with the above currencySpacing, inserting the symbol "US$" into the pattern "#,##0.00¤" would result in an extra no-break space inserted before the symbol, for example, "#,##0.00 US$". The beforeCurrency element governs this case, since we are looking before the "¤" symbol. The currencyMatch is positive, since the "U" in "US$" is at the start of the currency symbol being substituted. The surroundingMatch is positive, since the character just before the "¤" will be a digit. Because these two conditions are true, the insertion is made.

Conversely, look at the pattern "¤#,##0.00" with the symbol "US$". In this case, there is no insertion; the result is simply "US$#,##0.00". The afterCurrency element governs this case, since we are looking after the "¤" symbol. The surroundingMatch is positive, since the character just after the "¤" will be a digit. However, the currencyMatch is not positive, since the "$" in "US$" is at the end of the currency symbol being substituted. So the insertion is not made.

For more information on the matching used in the currencyMatch and surroundingMatch elements, see the main document Appendix E: Unicode Sets.

Currencies can also contain optional grouping, decimal data, and pattern elements. This data is inherited from the <symbols> in the same locale data (if not present in the chain up to root), so only the differing data will be present. See the main document Multiple Inheritance.

Note: Currency values should never be interchanged without a known currency code. You never want the number 3.5 interpreted as $3.50 by one user and €3.50 by another. Locale data contains localization information for currencies, not a currency value for a country. A currency amount logically consists of a numeric value, plus an accompanying currency code (or equivalent). The currency code may be implicit in a protocol, such as where USD is implicit. But if the raw numeric value is transmitted without any context, then it has no definitive interpretation.

Notice that the currency code is completely independent of the end-user's language or locale. For example, BGN is the code for Bulgarian Lev. A currency amount of <BGN, 1.23456×10³> would be localized for a Bulgarian user into "1 234,56 лв." (using Cyrillic letters). For an English user it would be localized into the string "BGN 1,234.56". The end-user's language is needed for doing this last localization step; but that language is completely orthogonal to the currency code needed in the data. After all, the same English user could be working with dozens of currencies. Notice also that the currency code is also independent of whether currency values are inter-converted, which requires more interesting financial processing: the rate of conversion may depend on a variety of factors.

Thus logically speaking, once a currency amount is entered into a system, it should be logically accompanied by a currency code in all processing. This currency code is independent of whatever the user's original locale was. Only in badly-designed software is the currency code (or equivalent) not present, so that the software has to "guess" at the currency code based on the user's locale.

Note: The number of decimal places and the rounding for each currency is not locale-specific data, and is not contained in the Locale Data Markup Language format. Those values override whatever is given in the currency numberFormat. For more information, see Supplemental Currency Data.

For background information on currency names, see [CurrencyInfo].

Supplemental Currency Data

<!ELEMENT currencyData ( fractions*, region+ ) >
<!ELEMENT fractions ( info+ ) >

<!ELEMENT info EMPTY >
<!ATTLIST info iso4217 NMTOKEN #REQUIRED >
<!ATTLIST info digits NMTOKEN #IMPLIED >
<!ATTLIST info rounding NMTOKEN #IMPLIED >
<!ATTLIST info cashDigits NMTOKEN #IMPLIED >
<!ATTLIST info cashRounding NMTOKEN #IMPLIED >

<!ELEMENT region ( currency* ) >
<!ATTLIST region iso3166 NMTOKEN #REQUIRED >

<!ELEMENT currency ( alternate* ) >
<!ATTLIST currency iso4217 NMTOKEN #REQUIRED >
<!ATTLIST currency from NMTOKEN #IMPLIED >
<!ATTLIST currency to NMTOKEN #IMPLIED >
<!ATTLIST currency tz CDATA #IMPLIED >
<!ATTLIST currency to-tz CDATA #IMPLIED >
<!ATTLIST currency tender ( true | false ) #IMPLIED >

Each currencyData element contains one fractions element followed by one or more region elements. Here is an example for illustration.

<supplementalData>
    <currencyData>
        <fractions>
        …
        <info iso4217="CHF" digits="2" rounding="5"/>
        …
        <info iso4217="ITL" digits="0"/>
        …
        </fractions>
        …
        <region iso3166="IT">
            <currency iso4217="EUR" from="1999-01-01"/>
            <currency iso4217="ITL" from="1862-8-24" to="2002-02-28"/>
        </region>
        …
        <region iso3166="CS">
            <currency iso4217="EUR" from="2003-02-04"/>
            <currency iso4217="CSD" from="2002-05-15"/>
            <currency iso4217="YUM" from="1994-01-24" to="2002-05-15"/>
        </region>
        …
    </currencyData>
    …
</supplementalData>

The fractions element contains any number of info elements, with the following attributes:

For example, the following line

<info iso4217="CZK" digits="2" rounding="0"/>

should cause the value 2.006 to be displayed as “2.01”, not “2.00”.

Each region element contains one attribute:

And can have any number of currency elements, with the ordered subelements.

<region iso3166="HR"> <!-- Croatia -->
    <currency iso4217="EUR" from="2023-01-01" tz="Europe/Zagreb"/>
    <currency iso4217="HRK" from="1994-05-30" to="2023-01-14" to-tz="Europe/Zagreb"/>
    <currency iso4217="HRD" from="1991-12-23" to="1995-01-01"/>
    <currency iso4217="YUN" from="1990-01-01" to="1991-12-23"/>
    <currency iso4217="YUD" from="1966-01-01" to="1990-01-01"/>
</region>

Note on converting transition datetimes for implementation use: The fact that CLDR stores the timezone separately from the transition datetime is for ease of CLDR maintenance. Implementations that use CLDR data may want to convert the combination into something like a single UTC timestamp for internal use.

That is, each currency element will list an interval in which it was valid. The ordering of the elements in the list tells us which was the primary currency during any period in time. Here is an example of such an overlap:

<currency iso4217="CSD" to="2002-05-15"/>
<currency iso4217="YUD" from="1994-01-24" to="2002-05-15"/>
<currency iso4217="YUN" from="1994-01-01" to="1994-07-22"/>

The from element is limited by the fact that ISO 4217 does not go very far back in time, so there may be no ISO code for the previous currency.

Currencies change relatively frequently. There are different types of changes:

  1. YU=>CS (name change)
  2. CS=>RS+ME (split, different names)
  3. SD=>SD+SS (split, same name for one // South Sudan splits from Sudan)
  4. DE+DD=>DE (Union, reuses one name // East Germany unifies with Germany)

The UN Information is used to determine dates due to country changes.

When a code is no longer in use, it is terminated (see #1, #2, #4, #5)

Example:

When codes split, each of the new codes inherits (see #2, #3) the previous data. However, some modifications can be made if it is clear that currencies were only in use in one of the parts.

When codes merge, the data is copied from the most populous part.

Example. When CS split into RS and ME:

Language Plural Rules

<!ELEMENT plurals (pluralRules*, pluralRanges*) >
<!ATTLIST plurals type ( ordinal | cardinal ) #IMPLIED > <!-- default is cardinal -->

<!ELEMENT pluralRules (pluralRule*) >
<!ATTLIST pluralRules locales NMTOKENS #REQUIRED >

<!ELEMENT pluralRule ( #PCDATA ) >
<!ATTLIST pluralRule count (zero | one | two | few | many | other) #REQUIRED >

The plural categories are used to format messages with numeric placeholders, expressed as decimal numbers. The fundamental rule for determining plural categories is the existence of minimal pairs: whenever two different numbers may require different versions of the same message, then the numbers have different plural categories.

This happens even if nouns are invariant; even if all English nouns were invariant (like “sheep”), English would still require 2 plural categories because of subject-verb agreement, and pronoun agreement. For example:

  1. 1 sheep is here. Do you want to buy it?
  2. 2 sheep are here. Do you want to buy them?

For more information, see Determining-Plural-Categories.

English does not have a separate plural category for “zero”, because it does not require a different message for “0”. For example, the same message can be used below, with just the numeric placeholder changing.

  1. You have 3 friends online.
  2. You have 0 friends online.

However, across many languages it is commonly more natural to express "0" messages with a negative (“None of your friends are online.”) and "1" messages also with an alternate form “You have a friend online.”. Thus pluralized message APIs should also offer the ability to specify at least the 0 and 1 cases explicitly; developers can use that ability whenever these values might occur in a placeholder.

The CLDR plural rules are not expected to cover all cases. For example, strictly speaking, there could be more plural and ordinal forms for English. Formally, we have a different plural form where a change in digits forces a change in the rest of the sentence. There is an edge case in English because of the behavior of "a/an".

For example, in changing from 3 to 8:

So numbers of the following forms could have a special plural category and special ordinal category: 8(X), 11(X), 18(X), 8x(X), where x is 0..9 and the optional X is 00, 000, 00000, and so on.

On the other hand, the above constructions are relatively rare in messages constructed using numeric placeholders, so the disruption for implementations currently using CLDR plural categories wouldn't be worth the small gain.

This section defines the types of plural forms that exist in a language—namely, the cardinal and ordinal plural forms. Cardinal plural forms express units such as time, currency or distance, used in conjunction with a number expressed in decimal digits (i.e. "2", not "two", and not an indefinite number such as "some" or "many"). Ordinal plural forms denote the order of items in a set and are always integers. For example, English has two forms for cardinals:

and four forms for ordinals:

Other languages may have additional forms or only one form for each type of plural. CLDR provides the following tags for designating the various plural forms of a language; for a given language, only the tags necessary for that language are defined, along with the specific numeric ranges covered by each tag (for example, the plural form "few" may be used for the numeric range 2–4 in one language and 3–9 in another):

In addition, an "other" tag is always implicitly defined to cover the forms not explicitly designated by the tags defined for a language. This "other" tag is also used for languages that only have a single form (in which case no plural-form tags are explicitly defined for the language). For a more complex example, consider the cardinal rules for Russian and certain other languages:

<pluralRules locales="hr ru sr uk">
    <pluralRules count="one">n mod 10 is 1 and n mod 100 is not 11</pluralRule>
    <pluralRules count="few">n mod 10 in 2..4 and n mod 100 not in 12..14</pluralRule>
</pluralRules>

These rules specify that Russian has a "one" form (for 1, 21, 31, 41, 51, …), a "few" form (for 2–4, 22–24, 32–34, …), and implicitly an "other" form (for everything else: 0, 5–20, 25–30, 35–40, …, decimals). Russian does not need additional separate forms for zero, two, or many, so these are not defined.

A source number represents the visual appearance of the digits of the result. In text, it can be represented by the EBNF for sampleValue. Note that the same double number can be represented by multiple source numbers. For example, "1.0" and "1.00" are different source numbers, but there is only one double number that they correspond to: 1.0d == 1.00d. As another example, 1e3d == 1000d, but the source numbers "1e3" and "1000" are different, and can have different plural categories. So the input to the plural rules carries more information than a computer double. The plural category for negative numbers is calculated according to the absolute value of the source number, and leading integer digits don't have any effect on the plural category calculation. (This may change in the future, if we find languages that have different behavior.)

Plural categories may also differ according to the visible decimals. For example, here are some of the behaviors exhibited by different languages:

Behavior Description Example
Base The fractions are ignored; the category is the same as the category of the integer. 1.13 has the same plural category as 1.
Separate All fractions by value are in one category (typically ‘other’ = ‘plural’). 1.01 gets the same class as 9;
1.00 gets the same category as 1.
Visible All visible fractions are in one category (typically ‘other’ = ‘plural’). 1.00, 1.01, 3.5 all get the same category.
Digits The visible fraction determines the category. 1.13 gets the same class as 13.

There are also variants of the above: for example, short fractions may have the Digits behavior, but longer fractions may just look at the final digit of the fraction.

Currently there are no locale keywords that affect plural rule selection; they are selected using the base locale ID, ignoring any -u- extension keywords.

Explicit 0 and 1 rules

Some types of CLDR data (such as unitPatterns and currency displayNames) allow specification of plural rules for explicit cases “0” and “1”, in addition to the language-specific plural cases specified above: “zero”, “one”, “two” ... “other”. For the language-specific plural rules:

By contrast, for the explicit cases “0” and “1”:

Usage example: In English (which only defines language-specific rules for “one” and “other”) this can be used to have special behavior for 0:

Plural rules syntax

The xml value for each pluralRule is a condition with a boolean result. That value specifies whether that rule (i.e. that plural form) applies to a given source number N in sampleValue syntax, where N can be expressed as a decimal fraction or with compact decimal formatting. The compact decimal formatting is denoted by a special notation in the syntax, e.g., “1.2c6” for “1.2M”. Clients of CLDR may express all the rules for a locale using the following syntax:

rules         = rule (';' rule)*
rule          = keyword ':' condition samples
              | 'other' ':' samples
keyword       = [a-z]+
keyword       = [a-z]+

In CLDR, the keyword is the attribute value of 'count'. Those values in CLDR are currently limited to just what is in the DTD, but clients may support other values.

The conditions themselves have the following syntax.

condition       = and_condition ('or' and_condition)*
samples         = ('@integer' sampleList)?
                  ('@decimal' sampleList)?
and_condition   = relation ('and' relation)*
relation        = is_relation | in_relation | within_relation
is_relation     = expr 'is' ('not')? value
in_relation     = expr (('not')? 'in' | '=' | '!=') range_list
within_relation = expr ('not')? 'within' range_list
expr            = operand (('mod' | '%') value)?
operand         = 'n' | 'i' | 'f' | 't' | 'v' | 'w' | 'c' | 'e'
range_list      = (range | value) (',' range_list)*
range           = value'..'value
value           = digit+
sampleList      = sampleRange (',' sampleRange)* (',' ('…'|'...'))?
sampleRange     = sampleValue ('~' sampleValue)?
sampleValue     = sign? value ('.' digit+)? ([ce] digitPos digit+)?
sign            = '+' | '-'
digit           = [0-9]
digitPos        = [1-9]

Operands

The operands are numeric values corresponding to features of the source number N, and have the following meanings given in the table below. Note that, contrary to source numbers, operands are treated numerically. Although some of them are used to describe insignificant 0s in the source number, any insignificant 0s in the operands themselves are ignored, e.g., f=03 is equivalent to f=3.

Table: Plural Operand Meanings
Symbol Value
n the absolute value of N.*
i the integer digits of N.*
v the number of visible fraction digits in N, with trailing zeros.*
w the number of visible fraction digits in N, without trailing zeros.*
f the visible fraction digits in N, with trailing zeros, expressed as an integer.*
t the visible fraction digits in N, without trailing zeros, expressed as an integer.*
c compact decimal exponent value: exponent of the power of 10 used in compact decimal formatting.
e a deprecated synonym for ‘c’. Note: it may be redefined in the future.

* If there is a compact decimal exponent value (‘c’), then the n, i, f, t, v, and w values are computed after shifting the decimal point in the original by the ‘c’ value. So for 1.2c3, the n, i, f, t, v, and w values are the same as those of 1200: i=1200 and f=0. Similarly, 1.2005c3 has i=1200 and f=5 (corresponding to 1200.5).

Table: Plural Operand Examples
source n i v w f t e
1 1 1 0 0 0 0 0
1.0 1 1 1 0 0 0 0
1.00 1 1 2 0 0 0 0
1.3 1.3 1 1 1 3 3 0
1.30 1.3 1 2 1 30 3 0
1.03 1.03 1 2 2 3 3 0
1.230 1.23 1 3 2 230 23 0
1200000 1200000 1200000 0 0 0 0 0
1.2c6 1200000 1200000 0 0 0 0 6
123c6 123000000 123000000 0 0 0 0 6
123c5 12300000 12300000 0 0 0 0 5
1200.50 1200.5 1200 2 1 50 5 0
1.20050c3 1200.5 1200 2 1 50 5 3

Relations

The positive relations are of the format x = y and x = y mod z. The y value can be a comma-separated list, such as n = 3, 5, 7..15, and is treated as if each relation were expanded into an OR statement. The range value a..b is equivalent to listing all the integers between a and b, inclusive. When != is used, it means the entire relation is negated.

Table: Relations Examples
Expression Meaning
x = 2..4, 15 x = 2 OR x = 3 OR x = 4 OR x = 15
x != 2..4, 15 NOT (x = 2 OR x = 3 OR x = 4 OR x = 15)
Expression Value
3.5 = 2..4, 15 false
3.5 != 2..4, 15 true
3 = 2..4, 15 true
3 != 2..4, 15 false

The old keywords 'mod', 'in', 'is', and 'within' are present only for backwards compatibility. The preferred form is to use '%' for modulo, and '=' or '!=' for the relations, with the operand 'i' instead of within. (The difference between in and within is that in only includes integers in the specified range, while within includes all values.)

The modulus (% or mod) is a remainder operation as defined in Java; for example, where n = 4.3 the result of n mod 3 is 1.3.

The values of relations are defined according to the operand as follows. Importantly, the results may depend on the visible decimals in the source, including trailing zeros, and the compact decimal exponent.

  1. Let the base value BV be computed from absolute value of the original source number according to the operand.
  2. Let R be false when the comparison contains ‘not’.
  3. Let R be !R if the comparison contains ‘within’ and the source number is not an integer.
  4. If there is a module value MV, let BV be BV - floor(BV/MV).
  5. Let CR be the list of comparison ranges, normalized that overlapping ranges are merged. Single values in the rule are represented by a range with identical <starti, endi> values.
  6. Iterate through CR:
    • if starti ≤ BV ≤ endi then return R.
  7. Otherwise return !R.
Table: Plural Rules Examples
Rules Comments
one: n = 1
few: n = 2..4		 This defines two rules, for 'one' and 'few'. The condition for 'one' is "n = 1" which means that the number must be equal to 1 for this condition to pass. The condition for 'few' is "n = 2..4" which means that the number must be between 2 and 4 inclusive for this condition to pass. All other numbers are assigned the keyword 'other' by the default rule.
zero: n = 0 or n != 1 and n mod 100 = 1..19
one: n = 1		 Each rule must not overlap with other rules. Also note that a modulus is applied to n in the last rule, thus its condition holds for 119, 219, 319, …
one: n = 1
few: n mod 10 = 2..4 and n mod 100 != 12..14		 This illustrates conjunction and negation. The condition for 'few' has two parts, both of which must be met: "n mod 10 = 2..4" and "n mod 100 != 12..14". The first part applies a modulus to n before the test as in the previous example. The second part applies a different modulus and also uses negation, thus it matches all numbers not in 12, 13, 14, 112, 113, 114, 212, 213, 214, …

Samples

Samples are provided if sample indicator (@integer or @decimal) is present on any rule. (CLDR always provides samples.)

Where samples are provided, the absence of one of the sample indicators indicates that no numeric values can satisfy that rule. For example, the rule "i = 1 and v = 0" can only have integer samples, so @decimal must not occur. The @integer samples have no visible fraction digits, while @decimal samples have visible fraction digits; both can have compact decimal exponent values (if the 'e' operand occurs).

The sampleRanges have a special notation: start~end. The start and end values must have the same number of decimal digits, and the same compact decimal exponent values (or neither have compact decimal exponent values). The range encompasses all and only those values v where start ≤ v ≤ end, and where v has the same number of decimal places as start and end, and the same compact decimal exponent values.

Samples must indicate whether they are infinite or not. The '…' marker must be present if and only if infinitely many values (integer or decimal) can satisfy the rule. If a set is not infinite, it must list all the possible values.

Table: Plural Samples Examples
Rules Comments
@integer 1, 3~5 1, 3, 4, 5.
@integer 3~5, 103~105, … Infinite set: 3, 4, 5, 103, 104, 105, …
@decimal 1.3~1.5, 1.03~1.05, … Infinite set: 1.3, 1.4, 1.5, 1.03, 1.04, 1.05, …

In determining whether a set of samples is infinite, leading zero integer digits and trailing zero decimals are not significant. Thus "i = 1000 and f = 0" is satisfied by 01000, 1000, 1000.0, 1000.00, 1000.000, 01c3 etc. but is still considered finite.

Using Cardinals

Elements such as <currencyFormats>, <currency> and <unit> provide selection among subelements designating various localized cardinal plural forms by tagging each of the relevant subelements with a different count value, or with no count value in some cases. Note that the plural forms for a specific currencyFormat, unit type, or currency type may not use all of the different plural-form tags defined for the language. To format a currency or unit type for a particular numeric value, determine the count value according to the plural rules for the language, then select the appropriate display form for the currency format, currency type or unit type using the rules in those sections:

Plural Ranges

<!ELEMENT pluralRanges (pluralRange*) >
<!ATTLIST pluralRanges locales NMTOKENS #REQUIRED >

<!ELEMENT pluralRange ( #PCDATA ) >
<!ATTLIST pluralRange start (zero|one|two|few|many|other) #IMPLIED >
<!ATTLIST pluralRange end (zero|one|two|few|many|other) #IMPLIED >
<!ATTLIST pluralRange result (zero|one|two|few|many|other) #REQUIRED >

Often ranges of numbers are presented to users, such as in “Length: 3.2–4.5 centimeters”. This means any length from 3.2 cm to 4.5 cm, inclusive. However, different languages have different conventions for the pluralization given to a range: should it be “0–1 centimeter” or “0–1 centimeters”? This becomes much more complicated for languages that have many different plural forms, such as Russian or Arabic.

The pluralRanges element provides information allowing an implementation to derive the plural category of a range from the plural categories of the start and end values. If there is no value for a <start,end> pair, the default result is end. However, where that result has been verified for a given language, it is included in the CLDR data.

The data has been gathered presuming that in any usage, the start value is strictly less than the end value, and that no values are negative. Results for any cases that do not meet these criteria are undefined.

For the formatting of number ranges, see Number Range Formatting.

Rule-Based Number Formatting

<!ELEMENT rbnf ( alias | rulesetGrouping*) >

<!ELEMENT rulesetGrouping ( alias | ruleset*) >
<!ATTLIST rulesetGrouping type NMTOKEN #REQUIRED>

<!ELEMENT ruleset ( alias | rbnfrule*) >
<!ATTLIST ruleset type NMTOKEN #REQUIRED>
<!ATTLIST ruleset access ( public | private ) #IMPLIED >

<!ELEMENT rbnfrule ( #PCDATA ) >
<!ATTLIST rbnfrule value CDATA #REQUIRED >
<!ATTLIST rbnfrule radix CDATA #IMPLIED >
<!ATTLIST rbnfrule decexp CDATA #IMPLIED >

The rule-based number format (RBNF) encapsulates a set of rules for mapping binary numbers to and from a readable representation. They are typically used for spelling out numbers, but can also be used for other number systems like roman numerals, Chinese numerals, or for ordinal numbers (1st, 2nd, 3rd, …).

Where, however, the CLDR plurals or ordinals can be used, their usage is recommended in preference to the RBNF data. First, the RBNF data is not completely fleshed out over all languages that otherwise have modern coverage. Secondly, the alternate forms are neither complete, nor useful without additional information. For example, for German there is spellout-cardinal-masculine, and spellout-cardinal-feminine. But a complete solution would have all genders (masculine/feminine/neuter), all cases (nominative, accusative, dative, genitive), plus context (with strong or weak determiner or none). Moreover, even for the alternate forms that do exist, CLDR does not supply any data for when to use one vs another (eg, when to use spellout-cardinal-masculine vs spellout-cardinal-feminine). So these data are inappropriate for general purpose software.

There are 4 common spellout rules. Some languages may provide more than these 4 types:

In addition to the spellout rules, there are also numbering system rules. Even though they may be derived from a specific culture, they are typically not translated and the rules are in root. An example of these rules are the Roman numerals where the value 8 comes out as VIII.

With regards to the number range supported for all these number types, the largest possible number range tries to be supported, but some languages may not have words for large numbers. For example, the old Roman numbering system can't support the value 5000 and beyond. For those unsupported cases, the default number format from CLDR is used.

Any rules marked as private should never be referenced externally. Frequently they only support a subrange of numbers that are used in the public rules.

The syntax used in the CLDR representation of rules is intended to be simply a transcription of ICU based RBNF rules into an XML compatible syntax. The rules are fairly sophisticated; for details see Rule-Based Number Formatter [RBNF].

<ruleSetGrouping>

Used to group rules into functional sets for use with ICU. Currently, the valid types of rule set groupings are "SpelloutRules", "OrdinalRules", and "NumberingSystemRules".

<ruleset>

This element denotes a specific rule set to the number formatter. The ruleset is assumed to be a public ruleset unless the attribute type="private" is specified.

<rule>

Contains the actual formatting rule for a particular number or sequence of numbers. The value attribute is used to indicate the starting number to which the rule applies. The actual text of the rule is identical to the ICU syntax, with the exception that Unicode left and right arrow characters are used to replace < and > in the rule text, since < and > are reserved characters in XML. The radix attribute is used to indicate an alternate radix to be used in calculating the prefix and postfix values for number formatting. Alternate radix values are typically used for formatting year numbers in formal documents, such as "nineteen hundred seventy-six" instead of "one thousand nine hundred seventy-six".

Parsing Numbers

The following elements are relevant to determining the value of a parsed number:

Other characters should either be ignored, or indicate the end of input, depending on the application. The key point is to disambiguate the sets of characters that might serve in more than one position, based on context. For example, a period might be either the decimal separator, or part of a currency symbol (for example, "NA f."). Similarly, an "E" could be an exponent indicator, or a currency symbol (the Swaziland Lilangeni uses "E" in the "en" locale). An apostrophe might be the decimal separator, or might be the grouping separator.

Here is a set of heuristic rules that may be helpful:

Number Range Formatting

Often ranges of numbers are presented to users, such as in “Length: 3.2–4.5 centimeters”. This means any length from 3.2 cm to 4.5 cm, inclusive.

To format a number range, the following steps are taken:

  1. Format the lower bound and the upper bound independently following the steps in Number Format Patterns, preserving semantic annotations*.
  2. If the resulting values are identical, stop evaluating these steps and, instead, perform the steps in Approximate Number Formatting.
    1. Note: This behavior may be customized in order to, for example, print the range despite the endpoints being identical. However, a spec-compliant implementation must support approximate number formatting.
  3. Perform the steps in Collapsing Number Ranges, obtaining modified lower and upper values.
  4. Obtain a number range pattern by following the steps in Range Pattern Processing.
  5. Substitute lower as {0} and upper as {1} into the range pattern from the previous step.

* Semantic annotations are discussed in Collapsing Number Ranges.

For plural rule selection of number ranges, see Plural Ranges.

Approximate Number Formatting

Approximate number formatting refers to a specific format of numbers in which the value is understood to not be exact; for example, "~5 minutes".

To format an approximate number, follow the normal number formatting procedure in Number Format Patterns, but substitute the approximatelySign from Number Symbols in for the minus sign placeholder.

If the number is negative, or if the formatting options request the sign to be displayed, prepend the approximatelySign to the plus or minus sign before substituting it into the pattern. For example, "~-5" means "approximately negative five". This procedure may change in the future.

Collapsing Number Ranges

Collapsing a number range refers to the process of removing duplicated information in the lower and upper values. For example, if the lower string is "3.2 centimeters" and the upper string is "4.5 centimeters", it is desirable to remove the extra "centimeters" token.

This operation requires semantic annotations on the formatted value. The exact form of the semantic annotations is implementation-dependent. However, implementations may consider the following broad categories of tokens:

  1. Numerical value, including decimal and grouping separators
  2. Sign symbol
  3. Scientific or compact notation
  4. Unit of measurement

For example, consider the string -5.3M US dollars. It may be annotated as follows:

Two tokens are semantically equivalent if they have the same semantic annotations, even if they are not the exact same string. For example:

  1. "centimeter" is semantically equivalent to "centimeters".
  2. "K" (the thousands symbol in compact decimals) is NOT semantically equivalent to "K" (the measurement unit Kelvin).

The above description describes the expected output. Internally, the implementation may determine the equivalent units of measurement by passing the codes back from the number formatters, allowing for a precise determination of "semantically equivalent".

Two semantically equivalent tokens can be collapsed if they appear at the start of both values or the end of both values. However, the implementation may choose different levels of aggressiveness with regard to collapsing tokens. An API for displaying ranges should permit control over whether the tokens are collapsed or not, and the levels of aggressiveness. The currently recommended heuristic is:

  1. Never collapse scientific or compact notation. This is to avoid producing ambiguous strings such as "3–5M" (could represent 3–5,000,000 or 3,000,000–5,000,000).
  2. Only collapse if the tokens are more than one code point in length. This is to increase clarity of strings such as "$3–$5".
  3. To perform the collapse, remove the token that is closest to the range separator. That is, for a prefix element, remove from the end value of the range, and for a suffix element remove it from the start value of the range:
    • USD 2 – USD 5 ⇒ USD 2 – 5
    • 2M EUR – 5M EUR ⇒ 2M – 5M EUR
    • 2 km – 5 km ⇒ 2 – 5 km
    • 2M ft – 5M ft ⇒ 2M – 5M ft
  4. When the tokens can have distinct plural forms, modify the remaining token so that it has the correct plural form. That is, use Plural Ranges to calculate the correct plural category for the range, and pick the variant of that the remaining token corresponding to that plural form.

In bidi contexts, the data is built so that rule #3 works visually. For example, if a range from 2 km to 5 km would be presented visually as "mk 5 – mk 2", the collapsed form would be "mk 5 – 2". (The mk is a stand-in for the native representation.) This requires consistent visualy reordering among the elements: the range, the prefixes and the suffixes. Thus a prefix value will be reordered to be visually a suffix value, and the order of the range will be visually reversed.

Range Pattern Processing

To obtain a number range pattern, the following steps are taken:

  1. Load the range pattern found in Miscellaneous Patterns.
  2. Optionally add spacing to the range pattern.

To determine whether to add spacing, the currently recommended heuristic is:

  1. If the lower string ends with a character other than a digit, or if the upper string begins with a character other than a digit.
  2. If the range pattern does not contain a character having the White_Space binary Unicode property after the {0} or before the {1} placeholders.

These heuristics may be refined in the future.

To add spacing, insert a non-breaking space (U+00A0) at the positions in item 2 above.

© 2024–2024 Unicode, Inc. This publication is protected by copyright, and permission must be obtained from Unicode, Inc. prior to any reproduction, modification, or other use not permitted by the Terms of Use. Specifically, you may make copies of this publication and may annotate and translate it solely for personal or internal business purposes and not for public distribution, provided that any such permitted copies and modifications fully reproduce all copyright and other legal notices contained in the original. You may not make copies of or modifications to this publication for public distribution, or incorporate it in whole or in part into any product or publication without the express written permission of Unicode.

Use of all Unicode Products, including this publication, is governed by the Unicode Terms of Use. The authors, contributors, and publishers have taken care in the preparation of this publication, but make no express or implied representation or warranty of any kind and assume no responsibility or liability for errors or omissions or for consequential or incidental damages that may arise therefrom. This publication is provided “AS-IS” without charge as a convenience to users.

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other countries.