diff --git a/docs/api/injection.md b/docs/api/injection.md index 15c271c8d..4f629b59f 100644 --- a/docs/api/injection.md +++ b/docs/api/injection.md @@ -64,7 +64,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path): TranslateResult; +$t(key: Key): TranslateResult; ``` **Details** @@ -82,7 +82,7 @@ In [Legacy API mode](general#mode), the input / output is the same as for VueI18 #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | #### Returns @@ -98,7 +98,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, locale: Locale): TranslateResult; +$t(key: Key, locale: Locale): TranslateResult; ``` **Details** @@ -108,7 +108,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | locale | Locale | A locale, override locale that global scope or local scope | #### Returns @@ -125,7 +125,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, locale: Locale, list: unknown[]): TranslateResult; +$t(key: Key, locale: Locale, list: unknown[]): TranslateResult; ``` **Details** @@ -135,7 +135,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | locale | Locale | A locale, override locale that global scope or local scope | | list | unknown[] | A values of list interpolation | @@ -153,7 +153,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, locale: Locale, named: object): TranslateResult; +$t(key: Key, locale: Locale, named: object): TranslateResult; ``` **Details** @@ -163,7 +163,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | locale | Locale | A locale, override locale that global scope or local scope | | named | object | A values of named interpolation | @@ -177,7 +177,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, plural: number): TranslateResult; +$t(key: Key, plural: number): TranslateResult; ``` :::tip NOTE @@ -191,7 +191,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | plural | number | A choice number of plural | #### Returns @@ -204,7 +204,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, plural: number, options: TranslateOptions): TranslateResult; +$t(key: Key, plural: number, options: TranslateOptions): TranslateResult; ``` :::tip NOTE @@ -218,7 +218,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | plural | number | A choice number of plural | | options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) | @@ -232,7 +232,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, defaultMsg: string): TranslateResult; +$t(key: Key, defaultMsg: string): TranslateResult; ``` :::tip NOTE @@ -246,7 +246,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | defaultMsg | string | A default message to return if no translation was found | #### Returns @@ -259,7 +259,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, defaultMsg: string, options: TranslateOptions): TranslateResult; +$t(key: Key, defaultMsg: string, options: TranslateOptions): TranslateResult; ``` :::tip NOTE @@ -273,7 +273,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | defaultMsg | string | A default message to return if no translation was found | | options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) | @@ -287,7 +287,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, list: unknown[]): TranslateResult; +$t(key: Key, list: unknown[]): TranslateResult; ``` **Details** @@ -297,7 +297,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | list | unknown[] | A values of list interpolation | #### Returns @@ -310,7 +310,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, list: unknown[], plural: number): TranslateResult; +$t(key: Key, list: unknown[], plural: number): TranslateResult; ``` :::tip NOTE @@ -324,7 +324,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | list | unknown[] | A values of list interpolation | | plural | number | A choice number of plural | @@ -338,7 +338,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, list: unknown[], defaultMsg: string): TranslateResult; +$t(key: Key, list: unknown[], defaultMsg: string): TranslateResult; ``` :::tip NOTE @@ -352,7 +352,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | list | unknown[] | A values of list interpolation | | defaultMsg | string | A default message to return if no translation was found | @@ -366,7 +366,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, list: unknown[], options: TranslateOptions): TranslateResult; +$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult; ``` :::tip NOTE @@ -380,7 +380,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | list | unknown[] | A values of list interpolation | | options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) | @@ -394,7 +394,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, named: NamedValue): TranslateResult; +$t(key: Key, named: NamedValue): TranslateResult; ``` **Details** @@ -404,7 +404,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | named | NamedValue | A values of named interpolation | #### Returns @@ -417,7 +417,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, named: NamedValue, plural: number): TranslateResult; +$t(key: Key, named: NamedValue, plural: number): TranslateResult; ``` :::tip NOTE @@ -431,7 +431,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | named | NamedValue | A values of named interpolation | | plural | number | A choice number of plural | @@ -445,7 +445,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, named: NamedValue, defaultMsg: string): TranslateResult; +$t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult; ``` :::tip NOTE @@ -459,7 +459,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | named | NamedValue | A values of named interpolation | | defaultMsg | string | A default message to return if no translation was found | @@ -473,7 +473,7 @@ Locale message translation **Signature:** ```typescript -$t(key: Path, named: NamedValue, options: TranslateOptions): TranslateResult; +$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult; ``` :::tip NOTE @@ -487,7 +487,7 @@ Overloaded `$t`. About details, see the [$t](injection#t-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | named | NamedValue | A values of named interpolation | | options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) | @@ -603,7 +603,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path): TranslateResult; +$tc(key: Key): TranslateResult; ``` :::warning NOTE @@ -624,7 +624,7 @@ The value of plural is handled with default `1`. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | #### Returns @@ -636,7 +636,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, locale: Locale): TranslateResult; +$tc(key: Key, locale: Locale): TranslateResult; ``` :::warning NOTE @@ -650,7 +650,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | locale | Locale | A locale, override locale that global scope or local scope | #### Returns @@ -663,7 +663,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, list: unknown[]): TranslateResult; +$tc(key: Key, list: unknown[]): TranslateResult; ``` :::warning NOTE @@ -677,7 +677,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | list | unknown[] | A values of list interpolation | #### Returns @@ -690,7 +690,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, named: Record): TranslateResult; +$tc(key: Key, named: Record): TranslateResult; ``` :::warning NOTE @@ -704,7 +704,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | named | Record<string, unknown> | A values of named interpolation | #### Returns @@ -717,7 +717,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, choice: number): TranslateResult; +$tc(key: Key, choice: number): TranslateResult; ``` :::warning NOTE @@ -731,7 +731,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | choice | number | Which plural string to get. 1 returns the first one | #### Returns @@ -744,7 +744,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, choice: number, locale: Locale): TranslateResult; +$tc(key: Key, choice: number, locale: Locale): TranslateResult; ``` :::warning NOTE @@ -758,7 +758,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | choice | number | Which plural string to get. 1 returns the first one | | locale | Locale | A locale, override locale that global scope or local scope | @@ -772,7 +772,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, choice: number, list: unknown[]): TranslateResult; +$tc(key: Key, choice: number, list: unknown[]): TranslateResult; ``` :::warning NOTE @@ -786,7 +786,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | choice | number | Which plural string to get. 1 returns the first one | | list | unknown[] | A values of list interpolation | @@ -800,7 +800,7 @@ Locale message pluralization **Signature:** ```typescript -$tc(key: Path, choice: number, named: Record): TranslateResult; +$tc(key: Key, choice: number, named: Record): TranslateResult; ``` :::warning NOTE @@ -814,7 +814,7 @@ Overloaded `$tc`. About details, see the [$tc](injection#tc-key) remarks. #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | choice | number | Which plural string to get. 1 returns the first one | | named | Record<string, unknown> | A values of named interpolation | @@ -828,7 +828,7 @@ Translation message exist **Signature:** ```typescript -$te(key: Path, locale?: Locale): boolean; +$te(key: Key, locale?: Locale): boolean; ``` **Details** @@ -838,7 +838,7 @@ About that details, see [VueI18n#te](legacy#te-key-locale) #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | | locale | Locale | Optional, A locale, override locale that global scope or local scope | #### Returns @@ -851,7 +851,7 @@ Locale messages getter **Signature:** ```typescript -$tm(key: Path): LocaleMessageValue | {} +$tm(key: Key): LocaleMessageValue | {} ``` **Details** @@ -869,7 +869,7 @@ If there are no locale messages for the given `key` in the composer instance mes #### Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | Path | A target locale message key | +| key | Key | A target locale message key | #### Returns diff --git a/docs/guide/migration/breaking10.md b/docs/guide/migration/breaking10.md index 836cb45ab..45429ba3f 100644 --- a/docs/guide/migration/breaking10.md +++ b/docs/guide/migration/breaking10.md @@ -6,42 +6,61 @@ Vue I18n v10 **is still an alpha version**. ## APIs -### Change `$t` overloaded signature for Legacy API mode - -In Vue I18n v9, it has a different interface from the Composition API mode and Legacy API mode of the `$t` overloaded signature. - -Especially, `$t` signature in Legacy API mode has fewer overloaded signatures than in Composition API mode, as shown below: - -| `$t` overloaded signatures | Legacy API v9 | Legacy API v10 | Composition API v9 & v10 | -| -------------------------------------------------------------------------------- | ------------- | -------------- | ------------------------ | -| `$t(key: Path): TranslateResult;` | ✅ | ✅ | ✅ | -| `$t(key: Path, locale: Locale): TranslateResult;` | ✅ | - | - | -| `$t(key: Path, locale: Locale, list: unknown[]): TranslateResult;` | ✅ | - | - | -| `$t(key: Path, locale: Locale, named: NamedValue): TranslateResult;` | ✅ | - | - | -| `$t(key: Path, plural: number): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, plural: number, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, defaultMsg: string, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, list: unknown[]): TranslateResult;` | ✅ | ✅ | ✅ | -| `$t(key: Path, list: unknown[], plural: number): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, list: unknown[], defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, list: unknown[], options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, named: Record): TranslateResult;` | ✅ | ✅ | ✅ | -| `$t(key: Path, named: NamedValue, plural: number): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, named: NamedValue, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | -| `$t(key: Path, named: NamedValue, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | - -Starting from v10, Legacy API mode can use the same `$t` overload signature as Composition API mode. - -**Reason**: After that migration, when migrating to Composition API mode, we sometimes fall into a pitfall due to the different signature of `$t`. +### Change `$t` and `t` overloaded signature for Legacy API mode + +In Vue I18n v9, it has a different interface from the Composition API mode and Legacy API mode of `$t` and `t` overloaded signature. + +Especially, `$t` and `t` signature in Legacy API mode has fewer overloaded signatures than in Composition API mode, as shown below: + +| `$t` and `t` overloaded signatures | Legacy API v9 | Legacy API v10 | Composition API v9 & v10 | +| --------------------------------------------------------------------------------------- | ------------- | -------------- | ------------------------ | +| `$t(key: Key): TranslateResult;` | ✅ | ✅ | ✅ | +| `$t(key: Key, locale: Locale): TranslateResult;` | ✅ | - | - | +| `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` | ✅ | - | - | +| `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;` | ✅ | - | - | +| `$t(key: Key, plural: number): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, plural: number, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, defaultMsg: string, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, list: unknown[]): TranslateResult;` | ✅ | ✅ | ✅ | +| `$t(key: Key, list: unknown[], plural: number): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, list: unknown[], defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, named: Record): TranslateResult;` | ✅ | ✅ | ✅ | +| `$t(key: Key, named: NamedValue, plural: number): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key): TranslateResult;` | ✅ | ✅ | ✅ | +| `t(key: Key, locale: Locale): TranslateResult;` | ✅ | - | - | +| `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` | ✅ | - | - | +| `t(key: Key, locale: Locale, named: Record): TranslateResult;` | ✅ | - | - | +| `t(key: Key, plural: number): TranslateResult; ` | - | ✅ | ✅ | +| `t(key: Key, plural: number, options: TranslateOptions): TranslateResult; ` | - | ✅ | ✅ | +| `t(key: Key, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, defaultMsg: string, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, list: unknown[]): TranslateResult;` | ✅ | ✅ | ✅ | +| `t(key: Key, list: unknown[], plural: number): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, list: unknown[], defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, named: Record): TranslateResult;` | ✅ | ✅ | ✅ | +| `t(key: Key, named: NamedValue, plural: number): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult;` | - | ✅ | ✅ | +| `t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` | - | ✅ | ✅ | + +Starting from v10, Legacy API mode can use the same `$t` and `t` overload signature as Composition API mode. + +**Reason**: After that migration, when migrating to Composition API mode, we sometimes fall into a pitfall due to the different signature. If you are using the following APIs in Legacy API mode, you must change to another signature because of the breaking changes: -- `$t(key: Path, locale: Locale): TranslateResult;` -- `$t(key: Path, locale: Locale, list: unknown[]): TranslateResult;` -- `$t(key: Path, locale: Locale, named: NamedValue): TranslateResult;` +- `$t(key: Key, locale: Locale): TranslateResult;` +- `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` +- `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;` +- `t(key: Key, locale: Locale): TranslateResult;` +- `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` +- `t(key: Key, locale: Locale, named: NamedValue): TranslateResult;` -#### `$t(key: Path, locale: Locale): TranslateResult;` +#### `$t(key: Key, locale: Locale): TranslateResult;` Vue I18n v9.x: @@ -53,7 +72,7 @@ Vue I18n v9.x: Vue I18n v10 or later: -use `$t(key: Path, list: unknown[], options: TranslateOptions): TranslateResult;` or `$t(key: Path, named: NamedValue, options: TranslateOptions): TranslateResult;` +use `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` or `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` ```vue ``` -#### `$t(key: Path, locale: Locale, list: unknown[]): TranslateResult;` +#### `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` Vue I18n v9.x: @@ -73,7 +92,7 @@ Vue I18n v9.x: Vue I18n v10 or later: -use `$t(key: Path, list: unknown[], options: TranslateOptions): TranslateResult;` +use `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` ```vue ``` -#### `$t(key: Path, locale: Locale, named: NamedValue): TranslateResult;` +#### `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;` Vue I18n v9.x: @@ -93,10 +112,88 @@ Vue I18n v9.x: Vue I18n v10 or later: -use `$t(key: Path, named: NamedValue, options: TranslateOptions): TranslateResult;` +use `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` ```vue ``` + +#### `t(key: Key, locale: Locale): TranslateResult;` + +Vue I18n v9.x: + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', 'ja')) +``` + +Vue I18n v10 or later: + +use `t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` or `t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', {}, { locale: 'ja' }) +``` + +#### `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;` + +Vue I18n v9.x: + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', 'ja', ['dio'])) +``` + +Vue I18n v10 or later: + +use `t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', ['dio'], { locale: 'ja' })) +``` + +#### `t(key: Key, locale: Locale, named: NamedValue): TranslateResult;` + +Vue I18n v9.x: + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', 'ja', { name: 'dio' })) +``` + +Vue I18n v10 or later: + +use `t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;` + +```ts +const i18n = createI18n({ + legacy: true, + // something options ... +}) + +console.log(i18n.global.t('message.hello', { name: 'dio' }, { locale: 'ja' })) +``` diff --git a/packages/vue-i18n-core/src/composer.ts b/packages/vue-i18n-core/src/composer.ts index 7c9124c44..5bebc0c7d 100644 --- a/packages/vue-i18n-core/src/composer.ts +++ b/packages/vue-i18n-core/src/composer.ts @@ -689,6 +689,24 @@ export interface ComposerTranslation< * @VueI18nSee [Scope and Locale Changing](../guide/essentials/scope) */ (key: Key | ResourceKeys | number): string + /** + * Locale message translation for plurals + * + * @remarks + * Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) details. + * + * In this overloaded `t`, return a pluralized translation message. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * @param key - A target locale message key + * @param plural - Which plural string to get. 1 returns the first one. + * + * @returns Translated message + * + * @VueI18nSee [Pluralization](../guide/essentials/pluralization) + */ + (key: Key | ResourceKeys | number, plural: number): string /** * Locale message translation for plurals * @@ -712,7 +730,26 @@ export interface ComposerTranslation< ( key: Key | ResourceKeys | number, plural: number, - options?: TranslateOptions + options: TranslateOptions + ): string + /** + * Locale message translation for missing default message + * + * @remarks + * Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) details. + * + * In this overloaded `t`, if no translation was found, return a default message. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * @param key - A target locale message key + * @param defaultMsg - A default message to return if no translation was found + * + * @returns Translated message + */ + ( + key: Key | ResourceKeys | number, + defaultMsg: string ): string /** * Locale message translation for missing default message @@ -735,7 +772,7 @@ export interface ComposerTranslation< ( key: Key | ResourceKeys | number, defaultMsg: string, - options?: TranslateOptions + options: TranslateOptions ): string /** * Locale message translation for list interpolations @@ -747,11 +784,8 @@ export interface ComposerTranslation< * * You can also suppress the warning, when the translation missing according to the options. * - * About details of options, see the {@link TranslateOptions}. - * * @param key - A target locale message key * @param list - A values of list interpolation - * @param options - Additional {@link TranslateOptions | options} for translation * * @returns Translated message * @@ -759,8 +793,7 @@ export interface ComposerTranslation< */ ( key: Key | ResourceKeys | number, - list: unknown[], - options?: TranslateOptions + list: unknown[] ): string /** * Locale message translation for list interpolations and plurals @@ -806,29 +839,50 @@ export interface ComposerTranslation< defaultMsg: string ): string /** - * Locale message translation for named interpolations + * Locale message translation for list interpolations * * @remarks * Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) details. * - * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token. + * In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list. * * You can also suppress the warning, when the translation missing according to the options. * * About details of options, see the {@link TranslateOptions}. * * @param key - A target locale message key - * @param named - A values of named interpolation + * @param list - A values of list interpolation * @param options - Additional {@link TranslateOptions | options} for translation * * @returns Translated message * + * @VueI18nSee [List interpolation](../guide/essentials/syntax#list-interpolation) + */ + ( + key: Key | ResourceKeys | number, + list: unknown[], + options: TranslateOptions + ): string + /** + * Locale message translation for named interpolations + * + * @remarks + * Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) details. + * + * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * @param key - A target locale message key + * @param named - A values of named interpolation + * + * @returns Translated message + * * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) */ ( key: Key | ResourceKeys | number, - named: NamedValue, - options?: TranslateOptions + named: NamedValue ): string /** * Locale message translation for named interpolations and plurals @@ -873,6 +927,31 @@ export interface ComposerTranslation< named: NamedValue, defaultMsg: string ): string + /** + * Locale message translation for named interpolations + * + * @remarks + * Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) details. + * + * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * About details of options, see the {@link TranslateOptions}. + * + * @param key - A target locale message key + * @param named - A values of named interpolation + * @param options - Additional {@link TranslateOptions | options} for translation + * + * @returns Translated message + * + * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) + */ + ( + key: Key | ResourceKeys | number, + named: NamedValue, + options: TranslateOptions + ): string } /** diff --git a/packages/vue-i18n-core/src/legacy.ts b/packages/vue-i18n-core/src/legacy.ts index 22d9bf80d..6edbf38b6 100644 --- a/packages/vue-i18n-core/src/legacy.ts +++ b/packages/vue-i18n-core/src/legacy.ts @@ -415,19 +415,89 @@ export interface VueI18nTranslation< */ (key: Key | ResourceKeys): TranslateResult /** - * Locale message translation. + * Locale message translation for plurals * * @remarks * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. * + * In this overloaded `t`, return a pluralized translation message. + * + * You can also suppress the warning, when the translation missing according to the options. + * * @param key - A target locale message key - * @param locale - A locale, it will be used over than global scope or local scope. + * @param plural - Which plural string to get. 1 returns the first one. * * @returns Translated message + * + * @VueI18nSee [Pluralization](../guide/essentials/pluralization) + */ + (key: Key | ResourceKeys, plural: number): TranslateResult + /** + * Locale message translation for plurals + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, return a pluralized translation message. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * About details of options, see the {@link TranslateOptions}. + * + * @param key - A target locale message key + * @param plural - Which plural string to get. 1 returns the first one. + * @param options - Additional {@link TranslateOptions | options} for translation + * + * @returns Translated message + * + * @VueI18nSee [Pluralization](../guide/essentials/pluralization) */ ( key: Key | ResourceKeys, - locale: Locales | Locale + plural: number, + options: TranslateOptions + ): TranslateResult + /** + * Locale message translation for missing default message + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, if no translation was found, return a default message. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * @param key - A target locale message key + * @param defaultMsg - A default message to return if no translation was found + * + * @returns Translated message + */ + ( + key: Key | ResourceKeys, + defaultMsg: string + ): TranslateResult + /** + * Locale message translation for missing default message + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, if no translation was found, return a default message. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * About details of options, see the {@link TranslateOptions}. + * + * @param key - A target locale message key + * @param defaultMsg - A default message to return if no translation was found + * @param options - Additional {@link TranslateOptions | options} for translation + * + * @returns Translated message + */ + ( + key: Key | ResourceKeys, + defaultMsg: string, + options: TranslateOptions ): TranslateResult /** * Locale message translation. @@ -436,7 +506,6 @@ export interface VueI18nTranslation< * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. * * @param key - A target locale message key - * @param locale - A locale, it will be used over than global scope or local scope. * @param list - A values of list interpolation * * @returns Translated message @@ -445,36 +514,41 @@ export interface VueI18nTranslation< */ ( key: Key | ResourceKeys, - locale: Locales | Locale, list: unknown[] ): TranslateResult /** - * Locale message translation. + * Locale message translation for list interpolations and plurals * * @remarks * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. * + * In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list, and return a pluralized translation message. + * * @param key - A target locale message key - * @param locale - A locale, it will be used over than global scope or local scope. - * @param named - A values of named interpolation + * @param list - A values of list interpolation + * @param plural - Which plural string to get. 1 returns the first one. * * @returns Translated message * - * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) + * @VueI18nSee [Pluralization](../guide/essentials/pluralization) + * @VueI18nSee [List interpolation](../guide/essentials/syntax#list-interpolation) */ ( key: Key | ResourceKeys, - locale: Locales | Locale, - named: Record + list: unknown[], + plural: number ): TranslateResult /** - * Locale message translation. + * Locale message translation for list interpolations and missing default message * * @remarks * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. * + * In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list, and if no translation was found, return a default message. + * * @param key - A target locale message key * @param list - A values of list interpolation + * @param defaultMsg - A default message to return if no translation was found * * @returns Translated message * @@ -482,7 +556,33 @@ export interface VueI18nTranslation< */ ( key: Key | ResourceKeys, - list: unknown[] + list: unknown[], + defaultMsg: string + ): TranslateResult + /** + * Locale message translation for list interpolations + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * About details of options, see the {@link TranslateOptions}. + * + * @param key - A target locale message key + * @param list - A values of list interpolation + * @param options - Additional {@link TranslateOptions | options} for translation + * + * @returns Translated message + * + * @VueI18nSee [List interpolation](../guide/essentials/syntax#list-interpolation) + */ + ( + key: Key | ResourceKeys, + list: unknown[], + options: TranslateOptions ): TranslateResult /** * Locale message translation. @@ -501,6 +601,74 @@ export interface VueI18nTranslation< key: Key | ResourceKeys, named: Record ): TranslateResult + /** + * Locale message translation for named interpolations and plurals + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token, and return a pluralized translation message. + * + * @param key - A target locale message key + * @param named - A values of named interpolation + * @param plural - Which plural string to get. 1 returns the first one. + * + * @returns Translated message + * + * @VueI18nSee [Pluralization](../guide/essentials/pluralization) + * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) + */ + ( + key: Key | ResourceKeys, + named: NamedValue, + plural: number + ): TranslateResult + /** + * Locale message translation for named interpolations and plurals + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token, and if no translation was found, return a default message. + * + * @param key - A target locale message key + * @param named - A values of named interpolation + * @param defaultMsg - A default message to return if no translation was found + * + * @returns Translated message + * + * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) + */ + ( + key: Key | ResourceKeys, + named: NamedValue, + defaultMsg: string + ): TranslateResult + /** + * Locale message translation for named interpolations + * + * @remarks + * Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details. + * + * In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token. + * + * You can also suppress the warning, when the translation missing according to the options. + * + * About details of options, see the {@link TranslateOptions}. + * + * @param key - A target locale message key + * @param named - A values of named interpolation + * @param options - Additional {@link TranslateOptions | options} for translation + * + * @returns Translated message + * + * @VueI18nSee [Named interpolation](../guide/essentials/syntax#named-interpolation) + */ + ( + key: Key | ResourceKeys, + named: NamedValue, + options: TranslateOptions + ): TranslateResult } /** diff --git a/packages/vue-i18n-core/test/i18n.test.ts b/packages/vue-i18n-core/test/i18n.test.ts index 2571277dc..e40dfcbc3 100644 --- a/packages/vue-i18n-core/test/i18n.test.ts +++ b/packages/vue-i18n-core/test/i18n.test.ts @@ -1369,7 +1369,7 @@ describe('Composer & VueI18n extend hooking', () => { }) }) -describe('component injections', () => { +describe('dollar prefixed API (component injections)', () => { const mockWarn = vi.spyOn(shared, 'warn') // eslint-disable-next-line @typescript-eslint/no-empty-function mockWarn.mockImplementation(() => {}) @@ -1457,3 +1457,105 @@ describe('component injections', () => { ) }) }) + +test('`t` on Legacy API mode', async () => { + const messages = { + en: { + hello: 'hello world!', + list: 'hello, {0}!', + named: 'hello, {name}!', + plural: 'no apples | one apple | {count} apples' + }, + ja: { + hello: 'こんにちは、世界!', + list: 'こんにちは、{0}!', + named: 'こんにちは、{name}!', + plural: 'りんご無い | りんご1個 | りんご{count}個' + } + } + + const i18n = createI18n({ + legacy: true, + locale: 'en', + messages + }) + + expect(i18n.global.t('hello')).toEqual('hello world!') + expect(i18n.global.t('list', ['world'])).toEqual('hello, world!') + expect(i18n.global.t('named', { name: 'world' })).toEqual('hello, world!') + expect(i18n.global.t('plural', 0)).toEqual('no apples') + expect(i18n.global.t('plural', 1)).toEqual('one apple') + expect(i18n.global.t('default', 'default message')).toEqual('default message') + expect( + i18n.global.t('default', 'default {msg}', { named: { msg: 'msg' } }) + ).toEqual('default msg') + expect(i18n.global.t('plural', ['many'], 4)).toEqual('4 apples') + expect(i18n.global.t('default', ['list msg'], 'default {0}')).toEqual( + 'default list msg' + ) + expect(i18n.global.t('list', ['世界'], { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) + expect(i18n.global.t('plural', { count: 'many' }, 4)).toEqual('many apples') + expect( + i18n.global.t('default', { msg: 'named msg' }, 'default {msg}') + ).toEqual('default named msg') + expect(i18n.global.t('named', { name: '世界' }, { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) + expect(i18n.global.t('hello', {}, { locale: 'en' })).toEqual('hello world!') + expect(i18n.global.t('hello', [], { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) +}) + +test('`t` on Composition API mode', async () => { + const messages = { + en: { + hello: 'hello world!', + list: 'hello, {0}!', + named: 'hello, {name}!', + plural: 'no apples | one apple | {count} apples' + }, + ja: { + hello: 'こんにちは、世界!', + list: 'こんにちは、{0}!', + named: 'こんにちは、{name}!', + plural: 'りんご無い | りんご1個 | りんご{count}個' + } + } + + const i18n = createI18n({ + legacy: false, + locale: 'en', + messages + }) + + expect(i18n.global.t('hello')).toEqual('hello world!') + expect(i18n.global.t('list', ['world'])).toEqual('hello, world!') + expect(i18n.global.t('named', { name: 'world' })).toEqual('hello, world!') + expect(i18n.global.t('plural', 0)).toEqual('no apples') + expect(i18n.global.t('plural', 1)).toEqual('one apple') + expect(i18n.global.t('default', 'default message')).toEqual('default message') + expect( + i18n.global.t('default', 'default {msg}', { named: { msg: 'msg' } }) + ).toEqual('default msg') + expect(i18n.global.t('plural', ['many'], 4)).toEqual('4 apples') + expect(i18n.global.t('default', ['list msg'], 'default {0}')).toEqual( + 'default list msg' + ) + expect(i18n.global.t('list', ['世界'], { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) + expect(i18n.global.t('plural', { count: 'many' }, 4)).toEqual('many apples') + expect( + i18n.global.t('default', { msg: 'named msg' }, 'default {msg}') + ).toEqual('default named msg') + expect(i18n.global.t('named', { name: '世界' }, { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) + expect(i18n.global.t('hello', {}, { locale: 'en' })).toEqual('hello world!') + expect(i18n.global.t('hello', [], { locale: 'ja' })).toEqual( + 'こんにちは、世界!' + ) +}) diff --git a/test-dts/vue-i18n/i18n.test-d.ts b/test-dts/vue-i18n/i18n.test-d.ts index be8fa281c..752515305 100644 --- a/test-dts/vue-i18n/i18n.test-d.ts +++ b/test-dts/vue-i18n/i18n.test-d.ts @@ -324,8 +324,6 @@ expectType<{ 'en-US': { short: {} } }>(looseI18n.datetimeFormats) expectType<{ 'ja-JP': { currency: {} } }>(looseI18n.numberFormats) expectType(looseI18n.t('nest.bar')) expectType(looseI18n.t('nest', 'en')) -expectType(looseI18n.t('nest', 'en', [1])) -expectType(looseI18n.t('nest', 'en', { foo: 'test' })) expectType(looseI18n.t('foo', [1])) expectType(looseI18n.t('nest', { foo: 1 })) expectType(looseI18n.tc('nest')) diff --git a/test-dts/vue-i18n/legacy.test-d.ts b/test-dts/vue-i18n/legacy.test-d.ts index 71749af3a..b291c4ca2 100644 --- a/test-dts/vue-i18n/legacy.test-d.ts +++ b/test-dts/vue-i18n/legacy.test-d.ts @@ -118,8 +118,6 @@ expectType<{ 'en-US': { short: {} } }>(looseVueI18n.datetimeFormats) expectType<{ 'ja-JP': { currency: {} } }>(looseVueI18n.numberFormats) expectType(looseVueI18n.t('nest.bar')) expectType(looseVueI18n.t('nest', 'en')) -expectType(looseVueI18n.t('nest', 'en', [1])) -expectType(looseVueI18n.t('nest', 'en', { foo: 'test' })) expectType(looseVueI18n.t('foo', [1])) expectType(looseVueI18n.t('nest', { foo: 1 })) expectType(looseVueI18n.tc('nest')) @@ -202,8 +200,6 @@ expectType<{ en: {}; ja: {} }>(strictVueI18n.datetimeFormats) expectType<{ en: {}; ja: {} }>(strictVueI18n.numberFormats) expectType(strictVueI18n.t('nest.bar')) expectType(strictVueI18n.t('nest', 'en')) -expectType(strictVueI18n.t('nest', 'en', [1])) -expectType(strictVueI18n.t('nest', 'en', { foo: 'test' })) expectType(strictVueI18n.t('foo', [1])) expectType(strictVueI18n.t('nest', { foo: 1 })) expectType(strictVueI18n.tc('nest'))