Intl.PluralRules
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2019.
The Intl.PluralRules
object enables plural-sensitive formatting and plural-related language rules.
Description
Languages use different patterns for expressing both plural numbers of items (cardinal numbers) and for expressing the order of items (ordinal numbers). English has two forms for expressing cardinal numbers: one for the singular "item" (1 hour, 1 dog, 1 fish) and the other for zero or any other number of "items" (0 hours, 2 lemmings, 100000.5 fish), while Chinese has only one form, and Arabic has six! Similarly, English has four forms for expressing ordinal numbers: "th", "st", "nd", "rd", giving the sequence: 0th, 1st, 2nd, 3rd, 4th, 5th, ..., 21st, 22nd, 23rd, 24th, 25th, and so on, while both Chinese and Arabic only have one form for ordinal numbers.
Given a particular language and set of formatting options, the methods Intl.PluralRules.prototype.select()
and Intl.PluralRules.prototype.selectRange()
return a tag that represents the plural form of a single or a range of numbers, cardinal or ordinal.
Code can use the returned tags to represent numbers appropriately for the given language.
The full set of tags that might be returned are: zero
, one
, two
, few
, many
, and other
(the "general" plural form, also used if the language only has one form).
As English only has two forms for cardinal numbers, the select()
method returns only two tags: "one"
for the singular case, and "other"
for all other cardinal numbers.
This allows construction of sentences that make sense in English for each case, such as: "1 dog is happy; do you want to play with it?" and "10 dogs are happy; do you want to play with them?".
Creating appropriate sentences for each form depends on the language, and even in English may not be as simple as just adding "s" to a noun to make the plural form. Using the example above, we see that the form may affect:
- Nouns: 1 dogs/2 dogs (but not "fish" or "sheep", which have the same singular and plural form).
- Verbs: 1 dog is happy, 2 dogs are happy
- Pronouns (and other referents): Do you want to play with it / them.
Other languages have more forms, and choosing appropriate sentences can be even more complex.
select()
can return any of four tags for ordinal numbers in English, representing each of the allowed forms: one
for "st" numbers (1, 21, 31, ...), two
for "nd" numbers (2, 22, 32, ...), few
for "rd" numbers (3, 33, 43, ...), and other
for "th" numbers (0, 4-20, etc.).
Again, the returned tags allow appropriate formatting of strings describing an ordinal number.
For more information about the rules and how they are used, see Plural Rules. For a list of the rules and how they apply for different languages, see the LDML Language Plural Rules.
Constructor
Intl.PluralRules()
-
Creates a new
Intl.PluralRules
object.
Static methods
Intl.PluralRules.supportedLocalesOf()
-
Returns an array containing those of the provided locales that are supported without having to fall back to the runtime's default locale.
Instance properties
These properties are defined on Intl.PluralRules.prototype
and shared by all Intl.PluralRules
instances.
Intl.PluralRules.prototype.constructor
-
The constructor function that created the instance object. For
Intl.PluralRules
instances, the initial value is theIntl.PluralRules
constructor. Intl.PluralRules.prototype[Symbol.toStringTag]
-
The initial value of the
[Symbol.toStringTag]
property is the string"Intl.PluralRules"
. This property is used inObject.prototype.toString()
.
Instance methods
Intl.PluralRules.prototype.resolvedOptions()
-
Returns a new object with properties reflecting the locale and collation options computed during initialization of the object.
Intl.PluralRules.prototype.select()
-
Returns a string indicating which plural rule to use for locale-aware formatting.
Intl.PluralRules.prototype.selectRange()
-
This method receives two values and returns a string indicating which plural rule to use for locale-aware formatting.
Examples
Using locales
This example shows some of the variations in localized plural rules for cardinal numbers.
In order to get the format for the language used in the user interface of your application, make sure to specify that language (and possibly some fallback languages) using the constructor locales
argument:
// US English
const enCardinalRules = new Intl.PluralRules("en-US");
console.log(enCardinalRules.select(0)); // "other"
console.log(enCardinalRules.select(1)); // "one"
console.log(enCardinalRules.select(2)); // "other"
console.log(enCardinalRules.select(3)); // "other"
// Arabic
const arCardinalRules = new Intl.PluralRules("ar-EG");
console.log(arCardinalRules.select(0)); // "zero"
console.log(arCardinalRules.select(1)); // "one"
console.log(arCardinalRules.select(2)); // "two"
console.log(arCardinalRules.select(6)); // "few"
console.log(arCardinalRules.select(18)); // "many"
Using options
The plural form of the specified number may also depend on constructor options
, such as how the number is rounded, and whether it is cardinal or ordinal.
This example shows how you can set the type of rules to "ordinal", and how this affects the form for some numbers in US English.
// US English - ordinal
const enOrdinalRules = new Intl.PluralRules("en-US", { type: "ordinal" });
console.log(enOrdinalRules.select(0)); // "other" (0th)
console.log(enOrdinalRules.select(1)); // "one" (1st)
console.log(enOrdinalRules.select(2)); // "two" (2nd)
console.log(enOrdinalRules.select(3)); // "few" (3rd)
console.log(enOrdinalRules.select(4)); // "other" (4th)
console.log(enOrdinalRules.select(21)); // "one" (21st)
Formatting text using the returned tag
The code below extends the previous example, showing how you might use the returned tag for an ordinal number to format text in English.
const enOrdinalRules = new Intl.PluralRules("en-US", { type: "ordinal" });
const suffixes = new Map([
["one", "st"],
["two", "nd"],
["few", "rd"],
["other", "th"],
]);
const formatOrdinals = (n) => {
const rule = enOrdinalRules.select(n);
const suffix = suffixes.get(rule);
return `${n}${suffix}`;
};
formatOrdinals(0); // '0th'
formatOrdinals(1); // '1st'
formatOrdinals(2); // '2nd'
formatOrdinals(3); // '3rd'
formatOrdinals(4); // '4th'
formatOrdinals(11); // '11th'
formatOrdinals(21); // '21st'
formatOrdinals(42); // '42nd'
formatOrdinals(103); // '103rd'
Specifications
Specification |
---|
ECMAScript Internationalization API Specification # pluralrules-objects |
Browser compatibility
BCD tables only load in the browser