Skip to content

Commit

Permalink
docs: Clarify usage of tags for pluralization (#964)
Browse files Browse the repository at this point in the history
Fixes #958 

See this for reference:

```tsx
new Intl.PluralRules("en").select(0); // other
new Intl.PluralRules("lv").select(0); // zero
```
  • Loading branch information
amannn authored Mar 29, 2024
1 parent 1e1a07c commit 05325a5
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 20 deletions.
36 changes: 17 additions & 19 deletions docs/pages/docs/usage/messages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -184,24 +184,22 @@ Note that by using the `#` marker, the value will be [formatted as a number](/do
<details>
<summary>Which plural forms are supported?</summary>

Depending on the language, different forms of cardinal pluralization are supported.
Languages have different rules for pluralization and your messages should reflect these rules.

For example, English has two forms: One for the singular (e.g. "1 _follower_") and one for everything else (e.g. "0 _followers_" and "2 _followers_"). In contrast, Chinese only has one form, while Arabic has six.

`next-intl` uses [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) to detect the correct _tag_ that should be used for a given number.
The other aspect to consider is that from a usability perspective, it can be helpful to consider additional cases on top—most commonly the special case for zero (e.g. "No followers yet" instead of "0 followers").

**These tags are supported:**
While you can always use the `=value` syntax to match a specific number (e.g. `=0`), you can choose from the following tags depending on what grammar rules apply to a given language:

- `zero`
- `one`
- `two`
- `few`
- `many`
- `other`
- `zero`: For languages with zero-item grammar (e.g., Arabic, Latvian).
- `one`: For languages with singular-item grammar (e.g., English, German).
- `two`: For languages with dual-item grammar (e.g., Arabic, Welsh).
- `few`: For languages with grammar specific to a small number of items (e.g., Arabic, Polish, Croatian).
- `many`: For languages with grammar specific to a larger number of items (e.g., Arabic, Polish, Croatian).
- `other`: Used when the value doesn't match other plural categories.

The exact range that `few` and `many` applies to varies depending on the locale (see [the language plural rules table in the Unicode CLDR](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html)).

To match a specific number, `next-intl` additionally supports the special `=value` syntax (e.g. `=3`) that always takes precedence.
`next-intl` uses [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) to detect the correct tag that should be used for a given number. The exact range that `few` and `many` applies to varies depending on the locale (see [the language plural rules table in the Unicode CLDR](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html)).

</details>

Expand All @@ -218,18 +216,18 @@ To apply pluralization based on an order of items, the `selectordinal` argument

Depending on the language, different forms of ordinal pluralization are supported.

For example, English has four forms: "th", "st", "nd" and "rd" (e.g. 1st, 2nd, 3rd, 4th … 21st, 22nd, 23rd, 24th, etc.). In contrast, both Chinese and Arabic use only one form for ordinal numbers.
For example, English has four forms: "th", "st", "nd" and "rd" (e.g. 1st, 2nd, 3rd, 4th … 11th, 12th, 13th … 21st, 22nd, 23rd, 24th, etc.). In contrast, both Chinese and Arabic use only one form for ordinal numbers.

`next-intl` uses [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) to detect the correct _tag_ that should be used for a given number.

**These tags are supported:**

- `zero`
- `one`
- `two`
- `few`
- `many`
- `other`
- `zero`: For languages with zero-item grammar (e.g., Arabic, Latvian).
- `one`: For languages with singular-item grammar (e.g., English, German).
- `two`: For languages with dual-item grammar (e.g., Arabic, Welsh).
- `few`: For languages with grammar specific to a small number of items (e.g., Arabic, Polish, Croatian).
- `many`: For languages with grammar specific to a larger number of items (e.g., Arabic, Polish, Croatian).
- `other`: Used when the value doesn't match other plural categories.

The exact range that `few` and `many` applies to varies depending on the locale (see [the language plural rules table in the Unicode CLDR](https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html)).

Expand Down
14 changes: 13 additions & 1 deletion packages/use-intl/test/react/useTranslations.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -157,14 +157,26 @@ it('applies a time zone when using a skeleton', () => {
screen.getByText('1/1/2024, 00:00');
});

it('handles pluralisation', () => {
it('supports pluralisation via specific numbers', () => {
renderMessage(
'You have {numMessages, plural, =0 {no messages} =1 {one message} other {# messages}}.',
{numMessages: 1}
);
screen.getByText('You have one message.');
});

it('supports pluralisation via tags like "zero" and "one" if the locale supports it', () => {
renderMessage(
'Jums ir {count, plural, zero {vēl nav sekotāju} one {viens sekotājs} other {# sekotāji}}.',
{count: 0},
undefined,
{
locale: 'lv'
}
);
screen.getByText('Jums ir vēl nav sekotāju.');
});

it('handles selects', () => {
renderMessage(
'{gender, select, male {He} female {She} other {They}} is online.',
Expand Down

0 comments on commit 05325a5

Please sign in to comment.