diff --git a/docs/pages/docs/usage/messages.mdx b/docs/pages/docs/usage/messages.mdx index 9da2c2a9f..5f7903342 100644 --- a/docs/pages/docs/usage/messages.mdx +++ b/docs/pages/docs/usage/messages.mdx @@ -184,24 +184,22 @@ Note that by using the `#` marker, the value will be [formatted as a number](/do
Which plural forms are supported? -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)).
@@ -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)). diff --git a/packages/use-intl/test/react/useTranslations.test.tsx b/packages/use-intl/test/react/useTranslations.test.tsx index 69dfffe0f..457aca8f3 100644 --- a/packages/use-intl/test/react/useTranslations.test.tsx +++ b/packages/use-intl/test/react/useTranslations.test.tsx @@ -157,7 +157,7 @@ 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} @@ -165,6 +165,18 @@ it('handles pluralisation', () => { 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.',