diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md index 7fdc85692e0857f..51892d6cb8f56e1 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/index.md @@ -9,6 +9,34 @@ browser-compat: javascript.builtins.Intl.PluralRules 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()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/select) and [`Intl.PluralRules.prototype.selectRange()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/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](https://cldr.unicode.org/index/cldr-spec/plural-rules). +For a list of the rules and how they apply for different languages, see the [LDML Language Plural Rules](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html). + ## Constructor - {{jsxref("Intl/PluralRules/PluralRules", "Intl.PluralRules()")}} @@ -41,21 +69,72 @@ These properties are defined on `Intl.PluralRules.prototype` and shared by all ` ### Using locales -This example shows some of the variations in localized plural rules. In order to get the format of the language used in the user interface of your application, make sure to specify that language (and possibly some fallback languages) using the `locales` argument: +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`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#locales) argument: + +```js +// 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`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#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. + +```js +// 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. ```js -// Arabic has different plural rules - -new Intl.PluralRules("ar-EG").select(0); -// → 'zero' -new Intl.PluralRules("ar-EG").select(1); -// → 'one' -new Intl.PluralRules("ar-EG").select(2); -// → 'two' -new Intl.PluralRules("ar-EG").select(6); -// → 'few' -new Intl.PluralRules("ar-EG").select(18); -// → 'many' +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 diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/pluralrules/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/pluralrules/index.md index 097dd56e29c6baf..625769bd23d7233 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/pluralrules/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/pluralrules/index.md @@ -28,58 +28,72 @@ new Intl.PluralRules(locales, options) - : An object with some or all of the following properties: - `localeMatcher` - - : The locale matching algorithm to use. Possible values are - `"lookup"` and `"best fit"`; the default is - `"best fit"`. For information about this option, see the - {{jsxref("Global_Objects/Intl", "Intl", "#locale_identification_and_negotiation", 1)}} page. + - : The locale matching algorithm to use. Possible values are `"lookup"` and `"best fit"`; the default is + `"best fit"`. For information about this option, see the {{jsxref("Global_Objects/Intl", "Intl", "#locale_identification_and_negotiation", 1)}} page. - `type` - : The type to use. Possible values are: - - `"cardinal"` for cardinal numbers (referring to the - quantity of things). This is the default value. - - `"ordinal"` for ordinal number (referring to the - ordering or ranking of things, e.g. "1st", "2nd", "3rd" in - English). + - `"cardinal"` for cardinal numbers (referring to the quantity of things). This is the default value. + - `"ordinal"` for ordinal number (referring to the ordering or ranking of things, e.g. "1st", "2nd", "3rd" in English). + + - `roundingMode` {{experimental_inline}} + + - : Specifies how fractional values are rounded. + The options are are: `"ceil"`, `"floor"`, `"expand"`, `"trunc"`, `"halfCeil"`, `"halfFloor"`, `"halfExpand"` (default), `"halfTrunc"`, `"halfEven"`. + The meanings of the values are documented in more detail in the corresponding [`Intl.NumberFormat` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingmode) option. + + - `roundingPriority` {{experimental_inline}} + + - : Specify how rounding conflicts will be resolved if both "FractionDigits" ([`minimumFractionDigits`](#minimumfractiondigits)/[`maximumFractionDigits`](#maximumfractiondigits)) and "SignificantDigits" ([`minimumSignificantDigits`](#minimumsignificantdigits)/[`maximumSignificantDigits`](#maximumsignificantdigits)) are specified: + + - `"auto"`: the result from the significant digits property is used (default). + - `"morePrecision"`: the result from the property that results in more precision is used. + - `"lessPrecision"`: the result from the property that results in less precision is used. + + Note that for values other than `auto` the result with more precision is calculated from the [`maximumSignificantDigits`](#minimumsignificantdigits) and [`maximumFractionDigits`](#maximumfractiondigits) (minimum fractional and significant digit settings are ignored). + + - `roundingIncrement` {{experimental_inline}} + + - : Specifies the rounding-increment precision. + Must be one of the following integers: + `1`, `2`, `5`, `10`, `20`, `25`, `50`, `100`, `200`, `250`, `500`, `1000`, `2000`, `2500`, `5000`. + The behavior is described in more detail in the corresponding [`Intl.NumberFormat` constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#roundingincrement) option. + + - `trailingZeroDisplay` {{experimental_inline}} + + - : A string expressing the strategy for displaying trailing zeros on whole numbers. + The default is `"auto"`. + + - `"auto"`: keep trailing zeros according to `minimumFractionDigits` and `minimumSignificantDigits`. + - `"stripIfInteger"`: remove the fraction digits _if_ they are all zero. + This is the same as `auto` if any of the fraction digits is non-zero. The following properties fall into two groups: - `minimumIntegerDigits`, `minimumFractionDigits`, and - `maximumFractionDigits` in one group, - `minimumSignificantDigits` and - `maximumSignificantDigits` in the other. If at least one property - from the second group is defined, then the first group is ignored. + `minimumIntegerDigits`, `minimumFractionDigits`, and `maximumFractionDigits` in one group, and `minimumSignificantDigits` and `maximumSignificantDigits` in the other. If at least one property from the second group is defined, then the first group is ignored. - `minimumIntegerDigits` - - : The minimum number of integer digits to use. Possible values are from 1 to - 21; the default is 1. + - : The minimum number of integer digits to use. Possible values are from 1 to 21; the default is 1. - `minimumFractionDigits` - - : The minimum number of fraction digits to use. Possible values are from 0 - to 20; the default for plain number and percent formatting is 0; the - default for currency formatting is the number of minor unit digits - provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml) - (2 if the list doesn't provide that information). + - : The minimum number of fraction digits to use. Possible values are from 0 to 20; + the default for plain number and percent formatting is 0; + the default for currency formatting is the number of minor unit digits provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml) (2 if the list doesn't provide that information). - `maximumFractionDigits` - - : The maximum number of fraction digits to use. Possible values are from 0 - to 20; the default for plain number formatting is the larger of - `minimumFractionDigits` and 3; the default for currency - formatting is the larger of `minimumFractionDigits` and the - number of minor unit digits provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml) - (2 if the list doesn't provide that information); the default for percent formatting is the larger of - `minimumFractionDigits` and 0. + - : The maximum number of fraction digits to use. + Possible values are from 0 to 20; the default for plain number formatting is the larger of `minimumFractionDigits` and 3; the default for currency formatting is the larger of `minimumFractionDigits` and the number of minor unit digits provided by the [ISO 4217 currency code list](https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml) (2 if the list doesn't provide that information); the default for percent formatting is the larger of `minimumFractionDigits` and 0. - `minimumSignificantDigits` - - : The minimum number of significant digits to use. Possible values are from - 1 to 21; the default is 1. + - : The minimum number of significant digits to use. + Possible values are from 1 to 21; the default is 1. - `maximumSignificantDigits` - - : The maximum number of significant digits to use. Possible values are from - 1 to 21; the default is 21. + - : The maximum number of significant digits to use. + Possible values are from 1 to 21; the default is 21. ## Examples ### Basic usage -In basic use without specifying a locale, a formatted string in the default locale and -with default options is returned. This is useful to distinguish between singular and -plural forms, e.g. "dog" and "dogs". +In basic use without specifying a locale, a formatted string in the default locale and with default options is returned. +This is useful to distinguish between singular and plural forms, e.g. "dog" and "dogs". ```js const pr = new Intl.PluralRules(); @@ -93,9 +107,7 @@ pr.select(2); // 'other' if in US English locale ### Using options -The results can be customized using the `options` argument, which has one -property called `type` which you can set to `ordinal`. This is -useful to figure out the ordinal indicator, e.g. "1st", "2nd", "3rd", "4th", "42nd" +The results can be customized using the `options` argument, which has one property called `type` which you can set to `ordinal`. This is useful to figure out the ordinal indicator, e.g. "1st", "2nd", "3rd", "4th", "42nd", and so forth. ```js diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/resolvedoptions/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/resolvedoptions/index.md index 5d1399ac7361cf2..1685a90b99676e4 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/resolvedoptions/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/resolvedoptions/index.md @@ -17,51 +17,73 @@ The **`resolvedOptions()`** method of {{jsxref("Intl.PluralRules")}} instances r resolvedOptions() ``` -### Return value +### Parameters + +None. -A new object with properties reflecting the locale and plural formatting options -computed during the initialization of the given {{jsxref("Intl.PluralRules")}} object. +### Return value -## Description +A new object with properties reflecting the locale and plural formatting options computed during the initialization of the given {{jsxref("Intl.PluralRules")}} object. -The resulting object has the following properties: +The object has the following properties: - `locale` - - : The BCP 47 language tag for the locale actually used. If any Unicode extension - values were requested in the input BCP 47 language tag that led to this locale, - the key-value pairs that were requested and are supported for this locale are - included in `locale`. + - : The BCP 47 language tag for the locale actually used. If any Unicode extension values were requested in the input BCP 47 language tag that led to this locale, the key-value pairs that were requested and are supported for this locale are included in `locale`. - `pluralCategories` - : An {{jsxref("Array")}} of plural categories used by the given locale, selected from the list `"zero"`, `"one"`, `"two"`, `"few"`, `"many"` and `"other"`. - `type` + - : The type used (`cardinal` or `ordinal`). +- `roundingMode` {{experimental_inline}} + - : The rounding mode. + This is the value provided for the [`options.roundingMode`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#roundingmode) argument in the constructor, or the default value: `halfExpand`. +- `roundingPriority` {{experimental_inline}} + - : The priority for resolving rounding conflicts if both "FractionDigits" and "SignificantDigits" are specified. + This is the value provided for the [`options.roundingPriority`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#roundingpriority) argument in the constructor, or the default value: `auto`. +- `roundingIncrement` {{experimental_inline}} + - : The rounding-increment precision (the increment used when rounding numbers). + This is the value specified in the [`options.roundingIncrement`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#roundingincrement) argument in the constructor. +- `trailingZeroDisplay` {{experimental_inline}} + - : The strategy for displaying trailing zeros on whole numbers. + This is the value specified in the [`options.trailingZeroDisplay`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules#trailingzerodisplay) argument in the constructor, or the default value: `"auto"`. + Only one of the following two groups of properties is included: - `minimumIntegerDigits`, `minimumFractionDigits`, `maximumFractionDigits` - - : The values provided for these properties in the `options` argument or - filled in as defaults. These properties are present only if neither - `minimumSignificantDigits` nor `maximumSignificantDigits` - was provided in the `options` argument. + - : The values provided for these properties in the `options` argument or filled in as defaults. + These properties are present only if neither `minimumSignificantDigits` nor `maximumSignificantDigits` was provided in the `options` argument. - `minimumSignificantDigits`, `maximumSignificantDigits` - - : The values provided for these properties in the `options` argument or - filled in as defaults. These properties are present only if at least one of them - was provided in the `options` argument. + - : The values provided for these properties in the `options` argument or filled in as defaults. + These properties are present only if at least one of them was provided in the `options` argument. ## Examples ### Using the resolvedOptions() method +The code below shows the construction of a `PluralRules` object, followed by logging of each of the resolved options. + ```js -const de = new Intl.PluralRules("de-DE"); -const usedOptions = de.resolvedOptions(); +// Create a PluralRules instance +const de = new Intl.PluralRules("de-DE", { + maximumSignificantDigits: 2, + trailingZeroDisplay: "auto", +}); -usedOptions.locale; // "de-DE" -usedOptions.maximumFractionDigits; // 3 -usedOptions.minimumFractionDigits; // 0 -usedOptions.minimumIntegerDigits; // 1 -usedOptions.pluralCategories; // [ "one", "other" ] -usedOptions.type; // "cardinal" +// Resolve the options +const usedOptions = de.resolvedOptions(); +console.log(usedOptions.locale); // "de-DE" +console.log(usedOptions.pluralCategories); // Array ["one", "other"] +console.log(usedOptions.type); // "cardinal" +console.log(usedOptions.minimumIntegerDigits); // 1 +console.log(usedOptions.minimumFractionDigits); // undefined (maximumSignificantDigits is set) +console.log(usedOptions.maximumFractionDigits); //undefined (maximumSignificantDigits is set) +console.log(usedOptions.minimumSignificantDigits); // 1 +console.log(usedOptions.maximumSignificantDigits); //2 +console.log(usedOptions.roundingIncrement); // 1 +console.log(usedOptions.roundingMode); // "halfExpand" +console.log(usedOptions.roundingPriority); // "auto" +console.log(usedOptions.trailingZeroDisplay); // "auto" ``` ## Specifications diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/select/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/select/index.md index c2cdcadda50d136..243b8032fbd8861 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/select/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/select/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Intl.PluralRules.select {{JSRef}} -The **`select()`** method of {{jsxref("Intl.PluralRules")}} instances returns a string indicating which plural rule to use for locale-aware formatting. +The **`select()`** method of {{jsxref("Intl.PluralRules")}} instances returns a string indicating which plural rule to use for locale-aware formatting of a number. {{EmbedInteractiveExample("pages/js/intl-pluralrules-prototype-select.html")}} @@ -24,22 +24,30 @@ select(number) ### Return value -A string representing the pluralization category of the `number`, can be one -of `zero`, `one`, `two`, `few`, -`many` or `other`. +A string representing the pluralization category of the `number`. +This can be one of `zero`, `one`, `two`, `few`, `many`, or `other`. ## Description -This function selects a pluralization category according to the locale and formatting -options of a {{jsxref("Intl.PluralRules")}} object. +This function selects a pluralization category according to the locale and formatting options of an {{jsxref("Intl.PluralRules")}} object. +These options are set in the [`Intl.PluralRules()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules/PluralRules) constructor. ## Examples ### Using select() +First, create an `Intl.PluralRules` object, passing the appropriate `locales` and `options` parameters. +Here we create a plural rules object for Arabic in the Egyptian dialect. +Because the `type` is not specified the rules object will provide formatting for cardinal numbers (the default). + ```js const pr = new Intl.PluralRules("ar-EG"); +``` +Then call `select()` on the rules object, specifying the number for which the plural form is required. +Note that Arabic has 5 forms for cardinal numbers, as shown. + +```js pr.select(0); // 'zero' pr.select(1); // 'one' pr.select(2); // 'two' diff --git a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md index ad608d3adf88542..d8b817b928b0f5f 100644 --- a/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md +++ b/files/en-us/web/javascript/reference/global_objects/intl/pluralrules/selectrange/index.md @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Intl.PluralRules.selectRange {{JSRef}} -The **`selectRange()`** method of {{jsxref("Intl.PluralRules")}} instances receives two values and returns a string indicating which plural rule to use for locale-aware formatting. +The **`selectRange()`** method of {{jsxref("Intl.PluralRules")}} instances receives two values and returns a string indicating which plural rule to use for locale-aware formatting of the indicated range. ## Syntax @@ -17,13 +17,18 @@ selectRange(startRange, endRange) ### Return value -A string representing the pluralization category of the `number`. +A string representing the pluralization category of the specified range. This can be one of `zero`, `one`, `two`, `few`, `many` or `other`, that are relevant for the locale whose localization is specified in [LDML Language Plural Rules](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html). ## Description This function selects a pluralization category according to the locale and formatting options of an {{jsxref("Intl.PluralRules")}} object. +Conceptually the behavior is the same as getting plural rules for a single cardinal or ordinal number. +Languages have one or more forms for describing ranges, and this method returns the appropriate form given the supplied locale and formatting options. +In English there is only one plural form, such as "1–10 apples", and the method will return `other`. +Other languages can have many forms. + ## Examples ### Using selectRange()