You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guide/essentials/pluralization.md
+36-3Lines changed: 36 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -114,11 +114,44 @@ As result the below:
114
114
<p>too many bananas</p>
115
115
```
116
116
117
-
## Custom Pluralization
117
+
## Automatic Pluralization with `Intl.PluralRules`
118
+
119
+
Vue I18n automatically uses [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) to select the correct plural form based on the current locale. This means that for most languages, you don't need to write custom pluralization rules — just provide the correct number of message cases in CLDR plural category order: `zero | one | two | few | many | other`.
120
+
121
+
For example, Russian has 4 plural categories (`one`, `few`, `many`, `other`):
122
+
123
+
```js
124
+
consti18n=createI18n({
125
+
locale:'ru',
126
+
messages: {
127
+
ru: {
128
+
car:'{n} машина | {n} машины | {n} машин | {n} машин',
129
+
// one few many other
130
+
}
131
+
}
132
+
})
133
+
```
134
+
135
+
Vue I18n will automatically select the correct form:
118
136
119
-
Such pluralization, however, does not apply to all languages (Slavic languages, for example, have different pluralization rules).
137
+
| Value |`Intl.PluralRules` category | Selected case |
138
+
|---|---|---|
139
+
| 1 |`one`|`{n} машина`|
140
+
| 2 |`few`|`{n} машины`|
141
+
| 5 |`many`|`{n} машин`|
142
+
| 21 |`one`|`{n} машина`|
143
+
144
+
:::tip NOTE
145
+
When the number of message cases exceeds the number of plural categories for the locale, Vue I18n falls back to the default rule (suitable for English).
146
+
:::
147
+
148
+
:::tip NOTE
149
+
If `Intl.PluralRules` is not available in the runtime environment, Vue I18n falls back to the default English-based rule.
150
+
:::
151
+
152
+
## Custom Pluralization
120
153
121
-
To implement these rules you can pass an optional `pluralRules` object into `createI18n` options.
154
+
While automatic pluralization via `Intl.PluralRules` works for most languages, you may need custom logic for special cases. You can pass an optional `pluralRules` object into `createI18n` options to override the automatic behavior for specific locales.
122
155
123
156
Very simplified example using rules for Slavic languages (Russian, Ukrainian, etc.):
Copy file name to clipboardExpand all lines: docs/guide/migration/breaking12.md
+34Lines changed: 34 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -507,6 +507,40 @@ Replace all `v-t` directive usage with `$t()` (global scope) or `t()` from `useI
507
507
508
508
You can use the `@intlify/vue-i18n/no-deprecated-v-t` rule to detect all `v-t` usage in your codebase.
509
509
510
+
## Default pluralization now uses `Intl.PluralRules`
511
+
512
+
**Reason**: The previous default pluralization rule was a simple English-only implementation that did not correctly handle languages with complex plural categories (e.g., Russian, Arabic, Polish). Vue I18n v12 now uses `Intl.PluralRules` to automatically select the correct plural form based on the current locale.
513
+
514
+
### What changed
515
+
516
+
- When no custom `pluralRules` is set for a locale, Vue I18n automatically uses `Intl.PluralRules` to determine the correct plural category (zero, one, two, few, many, other)
517
+
- Message cases must be ordered according to the CLDR plural category order: `zero | one | two | few | many | other` (only include categories that exist for the locale)
518
+
- If the number of message cases exceeds the locale's plural category count, Vue I18n falls back to the previous default rule
519
+
- If `Intl.PluralRules` is not available in the runtime environment, Vue I18n falls back to the previous default rule
520
+
521
+
### Migration
522
+
523
+
If you were relying on the previous default rule for non-English locales **without** custom `pluralRules`, you need to reorder your message cases to match the CLDR plural category order for the locale.
524
+
525
+
**Before (v11) — Russian with custom `pluralRules`:**
526
+
527
+
No change needed. Custom `pluralRules` take priority and continue to work as before.
528
+
529
+
**After (v12) — Russian (automatic, no custom `pluralRules` needed):**
530
+
531
+
```js
532
+
consti18n=createI18n({
533
+
locale:'ru',
534
+
// No pluralRules needed — Intl.PluralRules handles it automatically
535
+
messages: {
536
+
ru: {
537
+
// Order: one | few | many | other (CLDR order for Russian)
538
+
car:'{n} машина | {n} машины | {n} машин | {n} машин'
539
+
}
540
+
}
541
+
})
542
+
```
543
+
510
544
## Change `MissingHandler` signature
511
545
512
546
**Reason**: Vue 3.6+ deprecates `getCurrentInstance()` API. The `MissingHandler` type previously received a `ComponentInternalInstance` as the third parameter, but this is no longer available.
Copy file name to clipboardExpand all lines: docs/jp/guide/essentials/pluralization.md
+36-3Lines changed: 36 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -114,11 +114,44 @@ const messages = {
114
114
<p>too many bananas</p>
115
115
```
116
116
117
-
## カスタム複数化
117
+
## `Intl.PluralRules` による自動複数化
118
+
119
+
Vue I18n は現在のロケールに基づいて正しい複数形を自動的に選択するために [`Intl.PluralRules`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) を使用します。これにより、ほとんどの言語ではカスタムの複数化ルールを書く必要がありません。CLDR 複数形カテゴリの順序でメッセージのケースを正しい数だけ提供するだけです: `zero | one | two | few | many | other`。
0 commit comments