Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference · Date and Intl

The Intl.PluralRules object

Reference for Intl.PluralRules: pick the right plural category (one, few, many, other) or ordinal suffix for a number in any language, with live examples.

Intl.PluralRules tells you which plural category a number belongs to in a given language. English has two cardinal categories (one and other), but Russian has four, Arabic has six, and Japanese has just one. Hard-coding n === 1 ? "file" : "files" works only for languages that follow the English rule.

The object does not produce words. It returns a category name, and you map that name to your own text. It can also select ordinal categories, which is how you build "1st, 2nd, 3rd, 4th".

JavaScript
const rules = new Intl.PluralRules("en-US");
rules.select(1); // "one"
rules.select(5); // "other"

Try it

JS Cardinal plurals

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Ordinal numbers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
new Intl.PluralRules()
new Intl.PluralRules(locales)
new Intl.PluralRules(locales, options)

rules.select(number)
rules.resolvedOptions()
Name Description
locales A language tag, an array of tags, or undefined for the default locale.
options.type "cardinal" (default) for counting things, or "ordinal" for positions (1st, 2nd).
options.minimumFractionDigits and related digit options Control how the number is rounded before choosing a category, as in Intl.NumberFormat.
number The number to classify. Other values are converted to numbers.

Return value: one of the strings "zero", "one", "two", "few", "many" or "other". resolvedOptions().pluralCategories lists the categories the locale actually uses.

Exceptions: a RangeError is thrown for an invalid locale tag or invalid option values.

Usage notes

  • The names are labels, not meanings. one does not always mean exactly 1: in French it covers 0 and 1, and in Russian it covers 1, 21, 31 and so on. Do not compare categories to numbers.
  • Always provide other. Every language has it, and it is the fallback. Build your lookup table so a missing category never produces undefined.
  • Categories vary by language. Only translators know which words go with which category; store one message per category for each locale.
  • Ordinals are separate. English ordinals use one, two, few and other, which is why 11, 12 and 13 get "th" while 21, 22 and 23 get "st", "nd" and "rd".
  • Fractions follow language rules. In English, 1.5 is other ("1.5 files"), and so is 1 when the options force a decimal such as minimumFractionDigits: 1.
  • Formatting the number itself is a different job; use Intl.NumberFormat for separators and digits, and PluralRules only for the word.
  • Templates: libraries such as message-format systems build on PluralRules. For a handful of strings a small lookup table is enough.

Browser support

Supported in all current browsers and in Node.js. selectRange() is a newer method, so check a compatibility table before using it.