# Pluralization 1.0.3+

# Introduction

Languages vary in how they handle plurals of nouns or unit expressions (“hour” vs “hours”, and so on). Some languages have two forms, like English; some
languages have only a single form; and some languages have multiple
forms. This component uses Unicode CLDR Plural Rules to determine the form of a word in a given number. CLDR uses short, mnemonic tags for these plural categories:

zero
one (singular)
two (dual)
few (paucal)
many (also used for fractions if they have a separate class)
other (general plural form; also used if the language has only one form or if the required form is not defined. This form is required)

See Language Plural Rules for the categories for each language in CLDR.

These categories are used to provide localized units, with a more natural ways of expressing phrases that vary in plural form, such as “1 hour” vs “2 hours”. While they cannot express all the intricacies of natural languages, they allow for more natural phrasing than constructions like 1 hour(s)”.

Pluralization is carried out using the Intl.PluralRules object.

# TeslaCloud.Pluralization

# Properties

Property	Type	Description
language	string	A string with a BCP 47 language tag.
pluralRules	object	An `Intl.PluralRules` object for the current language.
isSupported (static)	boolean	If `false`, the user's browser does not support pluralization.
current (static)	object	A `TeslaCloud.Pluralization` object for current user's language.

# __construct

Class constructor.

__construct: function(language)

# Arguments

Argument	Type	Default value	Description
language	string	The value of the `lang` attribute of the `html` tag.	A string with a BCP 47 language tag.

# pluralPhraseName

Returns phrase names in the required plural form.

pluralPhraseName: function(number, phrases)

# Arguments

Argument	Type	Description
number	number	Number for pluralization.
phrases	object\|string	Names of phrases for different forms of pluralization. If a string is specified, it will be the name of the phrase in the form `other`, and names for other forms will be formed by adding the suffixes `_zero`, `_one`, `_two`, `_few` and `_many`. The `other` form is required.

# Examples

# Getting the phrase name from a list

/**
 * If the current language is English and count($items) == 1, “there_is_one_item” will be returned,
 * otherwise “there_are_x_items”. Other forms are not used by English, but may be used by other languages.
 */
const phraseName = TeslaCloud.Pluralization.current.pluralPhraseName(
    Object.keys(items).length,
    {
        zero: 'there_are_zero_items',
        one: 'there_is_one_item',
        few: 'there_are_few_items',
        many: 'there_are_many_items',
        other: 'there_are_x_items'
    }
);

# Getting the name of a phrase without specifying a list of phrases

/**
 * Unlike the previous example, here is not a list of named phrases, but the name of one phrase for the “other” form. Other phrases will
 * be formed by adding a suffix to it with the name of the form: “there_are_x_items_zero”, “there_are_x_items_one”, “there_are_x_items_two”,
 * “there_are_x_items_few”, “there_are_x_items_many”.
 */
const phraseName = TeslaCloud.Pluralization.current.pluralPhraseName(Object.keys(items).length, 'there_are_x_items');

# phrasePlural

Returns a phrase in the required plural form.

phrasePlural: function (number, phrases, vars, fallback)

# Arguments

Argument	Type	Description
number	number	Number for pluralization.
phrases	object\|string	Names of phrases for different forms of pluralization. If a string is specified, it will be the name of the phrase in the form `other`, and names for other forms will be formed by adding the suffixes `_zero`, `_one`, `_two`, `_few` and `_many`. The `other` form is required.
vars	object	An object of phrase parameters.
fallback	string	The value that will be returned in the following cases: ⋅ Pluralization is not supported by the user's browser ⋅ The resulting phrase was not found

# Examples

const phrase = TeslaCloud.Pluralization.current.phrasePlural(
    Object.keys(items).length,
    'there_are_x_items',
    {'{count}': Object.keys(items).length}
);

# getCardinal

Returns the name of the plural form for the current language.

getCardinal: function (number, availableCardinals = [])

# Arguments

Argument	Type	Default value	Description
number	number		Number for pluralization.
availableCardinals	array	[]	List of available plural forms. If the required plural form is not available, `other` will be returned.

If the user's browser does not support pluralization, the form other will be returned.

# Pluralization in phrases

It is possible to set pluralization rules directly in phrases. To do this, you need to create a similar construction in the phrase:

{plural
  number="{number}"
  zero="…"
  one="…"
  two="…"
  few="…"
  many="…"
  other="…"
  123="…"
  precision="0"
}

# Arguments

Argument	Description
number	Number for pluralization. Required parameter.
precision	The number of decimal places in the displayed number.
other	The value for the form `other`. Also used if the required form is not available. Required parameter.
Name of any form	The value for the specified form.
Any number	A value for a specific number.

# Examples

Let's create a phrase named test_plural_phrase for the English language:

There {plural
           number="{count}"
           0="are no books"
           one="is #n book"
           other="are #n books"
         } on the table.

For testing purposes, it is possible to add a phrase to JavaScript directly from the console:

XF.phrases.test_plural_phrase = `There {plural
                                         number="{count}"
                                         0="are no books"
                                         one="is #n book"
                                         other="are #n books"
                                       } on the table.`;

This phrase for the Russian language will look like this:

На столе {plural
           number="{count}"
           0="нет книг"
           1="одна книга"
           one="#n книга"
           few="#n книги"
           other="#n книг"
         }.

Note the difference between 1 (exactly 1) and one (ending in 1, except ending in 11).

Next, display the phrase:

console.log(XF.phrase('test_plural_phrase', {'{count}': 0}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 1}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 2}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 5}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 10}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 11}));
console.log(XF.phrase('test_plural_phrase', {'{count}': 101}));

Result for English:

There are no books on the table.

There is 1 book on the table.

There are 2 books on the table.

There are 5 books on the table.

There are 10 books on the table.

There are 11 books on the table.

There are 101 books on the table.

Result for Russian:

На столе нет книг.

На столе одна книга.

На столе 2 книги.

На столе 5 книг.

На столе 10 книг.

На столе 11 книг.

На столе 101 книга.

If the user's browser does not support pluralization, the XF.phrase function will return the text of the phrase without pluralization rules:

There on the table.

To prevent such situations, the fallback argument can be passed to the XF.phrase function: its value will be used instead of the specified phrase.