From 19a56de69e3abacc2913843ee49e456b9ea32f68 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Tue, 17 Jun 2025 00:25:04 +0900 Subject: [PATCH 1/4] fix: error on duplicate `useI18n` calling on local scope --- packages/vue-i18n-core/src/errors.ts | 12 +- packages/vue-i18n-core/src/i18n.ts | 4 + .../test/__snapshots__/i18n.test.ts.snap | 2 + packages/vue-i18n-core/test/i18n.test.ts | 60 + v11/component.md | 1 + v11/composition.md | 2338 +++++++++++++++++ v11/directive.md | 1 + v11/general.md | 1313 +++++++++ v11/legacy.md | 1 + 9 files changed, 3728 insertions(+), 4 deletions(-) create mode 100644 v11/component.md create mode 100644 v11/composition.md create mode 100644 v11/directive.md create mode 100644 v11/general.md create mode 100644 v11/legacy.md diff --git a/packages/vue-i18n-core/src/errors.ts b/packages/vue-i18n-core/src/errors.ts index c9cc541b1..ce9bc2726 100644 --- a/packages/vue-i18n-core/src/errors.ts +++ b/packages/vue-i18n-core/src/errors.ts @@ -1,6 +1,6 @@ import { - createCompileError, - CORE_ERROR_CODES_EXTEND_POINT + CORE_ERROR_CODES_EXTEND_POINT, + createCompileError } from '@intlify/core-base' import type { BaseError } from '@intlify/shared' @@ -26,7 +26,9 @@ export const I18nErrorCodes = { // not compatible legacy vue-i18n constructor NOT_COMPATIBLE_LEGACY_VUE_I18N: 33, // Not available Compostion API in Legacy API mode. Please make sure that the legacy API mode is working properly - NOT_AVAILABLE_COMPOSITION_IN_LEGACY: 34 + NOT_AVAILABLE_COMPOSITION_IN_LEGACY: 34, + // duplicate `useI18n` calling + DUPLICATE_USE_I18N_CALLING: 35 } as const type I18nErrorCodes = (typeof I18nErrorCodes)[keyof typeof I18nErrorCodes] @@ -57,5 +59,7 @@ export const errorMessages: { [code: number]: string } = { [I18nErrorCodes.NOT_COMPATIBLE_LEGACY_VUE_I18N]: 'Not compatible legacy VueI18n.', [I18nErrorCodes.NOT_AVAILABLE_COMPOSITION_IN_LEGACY]: - 'Not available Compostion API in Legacy API mode. Please make sure that the legacy API mode is working properly' + 'Not available Compostion API in Legacy API mode. Please make sure that the legacy API mode is working properly', + [I18nErrorCodes.DUPLICATE_USE_I18N_CALLING]: + "Duplicate `useI18n` calling by local scope. Please don't call it on local scope" } diff --git a/packages/vue-i18n-core/src/i18n.ts b/packages/vue-i18n-core/src/i18n.ts index 1fc5eec4f..13e44194b 100644 --- a/packages/vue-i18n-core/src/i18n.ts +++ b/packages/vue-i18n-core/src/i18n.ts @@ -772,6 +772,10 @@ export function useI18n< setupLifeCycle(i18nInternal, instance, composer) i18nInternal.__setInstance(instance, composer) + } else { + if (scope === 'local') { + throw createI18nError(I18nErrorCodes.DUPLICATE_USE_I18N_CALLING) + } } return composer as unknown as Composer< diff --git a/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap b/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap index d2ba3da67..f7712a7da 100644 --- a/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap +++ b/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap @@ -7,3 +7,5 @@ exports[`slot reactivity > composable > ja 1`] = `"

Root

hello!

Child

hello!

Sub Child

hello!

$t inside of slot

hello!

i18n-t inside of slot

hello!

"`; exports[`slot reactivity > legacy > ja 1`] = `"

Root

こんにちは!

Child

こんにちは!

Sub Child

こんにちは!

$t inside of slot

こんにちは!

i18n-t inside of slot

こんにちは!

"`; + +exports[`useI18n > Duplicate \`useI18n\` calling by local scope. Please don't call it on local scope 1`] = `"

Root

hi!

Duplicate \`useI18n\` calling by local scope. Please don't call it on local scope

"`; diff --git a/packages/vue-i18n-core/test/i18n.test.ts b/packages/vue-i18n-core/test/i18n.test.ts index 0d6ae7488..f69ddbe47 100644 --- a/packages/vue-i18n-core/test/i18n.test.ts +++ b/packages/vue-i18n-core/test/i18n.test.ts @@ -622,6 +622,66 @@ describe('useI18n', () => { errorMessages[I18nErrorCodes.NOT_INSTALLED_WITH_PROVIDE] ) }) + + test(errorMessages[I18nErrorCodes.DUPLICATE_USE_I18N_CALLING], async () => { + const i18n = createI18n({ + legacy: false, + locale: 'en', + fallbackLocale: ['en'], + messages: { + en: { hello: 'hello!' } + } + }) + + const useMyComposable = () => { + const count = ref(0) + const { t } = useI18n({ + messages: { + en: { + there: 'hi there! {count}' + } + } + }) + return { message: t('there', { count: count.value }) } + } + + let error = '' + const App = defineComponent({ + setup() { + let message: string = '' + let t: any // eslint-disable-line @typescript-eslint/no-explicit-any + try { + const i18n = useI18n({ + messages: { + en: { + hi: 'hi!' + } + } + }) + t = i18n.t + const ret = useMyComposable() + message = ret.message + } catch (e: any) { + error = e.message + } + return { t, message, error } + }, + template: ` +

Root

+
+ +
+

{{ t('hi') }}

+

{{ message }}

+

{{ error }}

+ ` + }) + const { html } = await mount(App, i18n as any) // eslint-disable-line @typescript-eslint/no-explicit-any + expect(html()).toMatchSnapshot() + }) }) describe('slot reactivity', () => { diff --git a/v11/component.md b/v11/component.md new file mode 100644 index 000000000..0eac4eb52 --- /dev/null +++ b/v11/component.md @@ -0,0 +1 @@ +# Components diff --git a/v11/composition.md b/v11/composition.md new file mode 100644 index 000000000..e0457b759 --- /dev/null +++ b/v11/composition.md @@ -0,0 +1,2338 @@ +# Composition API + +## Composer + +Composer interfaces + +**Signature:** + +```typescript +export interface Composer = {}, DateTimeFormats extends Record = {}, NumberFormats extends Record = {}, OptionLocale = Locale, ResourceLocales = PickupLocales> | PickupLocales> | PickupLocales>, Locales = Locale extends GeneratedLocale ? GeneratedLocale : OptionLocale extends Locale ? IsNever extends true ? Locale : ResourceLocales : OptionLocale | ResourceLocales> extends ComposerCustom +``` + +**Details** + +This is the interface for being used for Vue 3 Composition API. + +### availableLocales + +**Signature:** + +```typescript +readonly availableLocales: ComputedRef; +``` + +**Details** + +The list of available locales in `messages` in lexical order. + +### d + +Datetime formatting + +**Signature:** + +```typescript +d: ComposerDateTimeFormatting< + DateTimeFormats, + Locales, + RemoveIndexSignature<{ + [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K] + }> +> +``` + +**Details** + +About details functions, See the [ComposerDateTimeFormatting](composition#composerdatetimeformatting) + +### datetimeFormats + +**Signature:** + +```typescript +readonly datetimeFormats: ComputedRef<{ + [K in keyof DateTimeFormats]: DateTimeFormats[K]; + }>; +``` + +**Details** + +The datetime formats of localization. + +**See Also** + +- [Datetime Formatting](../../guide/essentials/datetime) + +### escapeParameter + +**Signature:** + +```typescript +escapeParameter: boolean +``` + +**Details** + +Whether interpolation parameters are escaped before the message is translated. + +**See Also** + +- [HTML Message](../../guide/essentials/syntax#html-message) + +### fallbackFormat + +**Signature:** + +```typescript +fallbackFormat: boolean +``` + +**Details** + +Whether suppress warnings when falling back to either `fallbackLocale` or root. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackLocale + +**Signature:** + +```typescript +fallbackLocale: WritableComputedRef> +``` + +**Details** + +The current fallback locales this Composer instance is using. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackRoot + +**Signature:** + +```typescript +fallbackRoot: boolean +``` + +**Details** + +Whether to fall back to root level (global scope) localization when localization fails. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackWarn + +**Signature:** + +```typescript +fallbackWarn: boolean | RegExp +``` + +**Details** + +Whether suppress fall back warnings when localization fails. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### id + +**Signature:** + +```typescript +id: number +``` + +**Details** + +Instance ID. + +### inheritLocale + +**Signature:** + +```typescript +inheritLocale: boolean +``` + +**Details** + +Whether inherit the root level locale to the component localization locale. + +**See Also** + +- [Local Scope](../../guide/essentials/scope#local-scope-2) + +### isGlobal + +**Signature:** + +```typescript +readonly isGlobal: boolean; +``` + +**Details** + +Whether this composer instance is global or not + +### locale + +**Signature:** + +```typescript +locale: WritableComputedRef +``` + +**Details** + +The current locale this Composer instance is using. + +If the locale contains a territory and a dialect, this locale contains an implicit fallback. + +**See Also** + +- [Scope and Locale Changing](../../guide/essentials/scope) + +### messages + +**Signature:** + +```typescript +readonly messages: ComputedRef<{ + [K in keyof Messages]: Messages[K]; + }>; +``` + +**Details** + +The locale messages of localization. + +**See Also** + +- [Getting Started](../../guide/essentials/started) + +### missingWarn + +**Signature:** + +```typescript +missingWarn: boolean | RegExp +``` + +**Details** + +Whether suppress warnings outputted when localization fails. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### modifiers + +**Signature:** + +```typescript +readonly modifiers: LinkedModifiers; +``` + +**Details** + +Custom Modifiers for linked messages. + +**See Also** + +- [Custom Modifiers](../../guide/essentials/syntax#custom-modifiers) + +### n + +Number Formatting + +**Signature:** + +```typescript +n: ComposerNumberFormatting< + NumberFormats, + Locales, + RemoveIndexSignature<{ + [K in keyof DefineNumberFormat]: DefineNumberFormat[K] + }> +> +``` + +**Details** + +About details functions, See the [ComposerNumberFormatting](composition#composernumberformatting) + +### numberFormats + +**Signature:** + +```typescript +readonly numberFormats: ComputedRef<{ + [K in keyof NumberFormats]: NumberFormats[K]; + }>; +``` + +**Details** + +The number formats of localization. + +**See Also** + +- [Number Formatting](../../guide/essentials/number) + +### pluralRules + +**Signature:** + +```typescript +readonly pluralRules: PluralizationRules; +``` + +**Details** + +A set of rules for word pluralization + +**See Also** + +- [Custom Pluralization](../../guide/essentials/pluralization#custom-pluralization) + +### rt + +Resolve locale message translation + +**Signature:** + +```typescript +rt: ComposerResolveLocaleMessageTranslation +``` + +**Details** + +About details functions, See the [ComposerResolveLocaleMessageTranslation](composition#composerresolvelocalemessagetranslation) + +### t + +Locale message translation + +**Signature:** + +```typescript +t: ComposerTranslation< + Messages, + Locales, + RemoveIndexSignature<{ + [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K] + }> +> +``` + +**Details** + +About details functions, See the [ComposerTranslation](composition#composertranslation) + +### warnHtmlMessage + +**Signature:** + +```typescript +warnHtmlMessage: boolean +``` + +**Details** + +Whether to allow the use locale messages of HTML formatting. + +If you set `false`, will check the locale messages on the Composer instance. + +If you are specified `true`, a warning will be output at console. + +**See Also** + +- [HTML Message](../../guide/essentials/syntax#html-message) +- [Change `warnHtmlInMessage` option default value](../../guide/migration/breaking#change-warnhtmlinmessage-option-default-value) + +### getDateTimeFormat(locale) + +Get datetime format + +**Signature:** + +```typescript +getDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K]; + }> : NonNullable[Locale] : DateTimeSchema>(locale: LocaleSchema | Locale): Return; +``` + +#### Type Parameters + +| Parameter | Description | +| -------------- | ------------------------------------------- | +| DateTimeSchema | The datetime format schema, default `never` | + +**Details** + +get datetime format from Composer instance [datetimeFormats](composition#datetimeformats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | --------------- | +| locale | LocaleSchema | Locale | A target locale | + +#### Returns + +Datetime format + +### getLocaleMessage(locale) + +Get locale message + +**Signature:** + +```typescript +getLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; + }> : NonNullable[Locale] : MessageSchema>(locale: LocaleSchema | Locale): Return; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------- | ------------------------------------------ | +| MessageSchema | The locale message schema, default `never` | + +**Details** + +get locale message from Composer instance [messages](composition#messages). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | --------------- | +| locale | LocaleSchema | Locale | A target locale | + +#### Returns + +Locale messages + +### getMissingHandler() + +Get missing handler + +**Signature:** + +```typescript +getMissingHandler(): MissingHandler | null; +``` + +**See Also** + +- [missing](composition#missing) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ---- | ----------- | + +#### Returns + +[MissingHandler](composition#missinghandler) + +### getNumberFormat(locale) + +Get number format + +**Signature:** + +```typescript +getNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineNumberFormat]: DefineNumberFormat[K]; + }> : NonNullable[Locale] : NumberSchema>(locale: LocaleSchema | Locale): Return; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------ | ----------------------------------------- | +| NumberSchema | The number format schema, default `never` | + +**Details** + +get number format from Composer instance [numberFormats](composition#numberFormats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | --------------- | +| locale | LocaleSchema | Locale | A target locale | + +#### Returns + +Number format + +### getPostTranslationHandler() + +Get post translation handler + +**Signature:** + +```typescript +getPostTranslationHandler(): PostTranslationHandler | null; +``` + +**See Also** + +- [missing](composition#posttranslation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ---- | ----------- | + +#### Returns + +### mergeDateTimeFormat(locale, format) + +Merge datetime format + +**Signature:** + +```typescript +mergeDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Formats = IsNever extends true ? Record : DateTimeSchema>(locale: LocaleSchema | Locale, format: Formats): void; +``` + +#### Type Parameters + +| Parameter | Description | +| -------------- | ------------------------------------------- | +| DateTimeSchema | The datetime format schema, default `never` | + +**Details** + +Merge datetime format to Composer instance [datetimeFormats](composition#datetimeformats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ------------------------ | +| locale | LocaleSchema | Locale | A target locale | +| format | Formats | A target datetime format | + +### mergeLocaleMessage(locale, message) + +Merge locale message + +**Signature:** + +```typescript +mergeLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Message = IsNever extends true ? Record : MessageSchema>(locale: LocaleSchema | Locale, message: Message): void; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------- | ------------------------------------------ | +| MessageSchema | The locale message schema, default `never` | + +**Details** + +Merge locale message to Composer instance [messages](composition#messages). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | --------------- | +| locale | LocaleSchema | Locale | A target locale | +| message | Message | A message | + +### mergeNumberFormat(locale, format) + +Merge number format + +**Signature:** + +```typescript +mergeNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Formats = IsNever extends true ? Record : NumberSchema>(locale: LocaleSchema | Locale, format: Formats): void; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------ | ----------------------------------------- | +| NumberSchema | The number format schema, default `never` | + +**Details** + +Merge number format to Composer instance [numberFormats](composition#numberFormats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ---------------------- | +| locale | LocaleSchema | Locale | A target locale | +| format | Formats | A target number format | + +### setDateTimeFormat(locale, format) + +Set datetime format + +**Signature:** + +```typescript +setDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, FormatsType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K]; + }> : NonNullable[Locale] : DateTimeSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void; +``` + +#### Type Parameters + +| Parameter | Description | +| -------------- | ------------------------------------------- | +| DateTimeSchema | The datetime format schema, default `never` | + +**Details** + +Set datetime format to Composer instance [datetimeFormats](composition#datetimeformats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ------------------------ | +| locale | LocaleSchema | Locale | A target locale | +| format | Formats | A target datetime format | + +### setLocaleMessage(locale, message) + +Set locale message + +**Signature:** + +```typescript +setLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, MessageType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; + }> : NonNullable[Locale] : MessageSchema, Message extends MessageType = MessageType>(locale: LocaleSchema | Locale, message: Message): void; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------- | ------------------------------------------ | +| MessageSchema | The locale message schema, default `never` | + +**Details** + +Set locale message to Composer instance [messages](composition#messages). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | --------------- | +| locale | LocaleSchema | Locale | A target locale | +| message | Message | A message | + +### setMissingHandler(handler) + +Set missing handler + +**Signature:** + +```typescript +setMissingHandler(handler: MissingHandler | null): void; +``` + +**See Also** + +- [missing](composition#missing) + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ---------------------------------------------- | +| handler | MissingHandler | null | A [MissingHandler](composition#missinghandler) | + +### setNumberFormat(locale, format) + +Set number format + +**Signature:** + +```typescript +setNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, FormatsType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ + [K in keyof DefineNumberFormat]: DefineNumberFormat[K]; + }> : NonNullable[Locale] : NumberSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void; +``` + +#### Type Parameters + +| Parameter | Description | +| ------------ | ----------------------------------------- | +| NumberSchema | The number format schema, default `never` | + +**Details** + +Set number format to Composer instance [numberFormats](composition#numberFormats). + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ---------------------- | +| locale | LocaleSchema | Locale | A target locale | +| format | Formats | A target number format | + +### setPostTranslationHandler(handler) + +Set post translation handler + +**Signature:** + +```typescript +setPostTranslationHandler(handler: PostTranslationHandler | null): void; +``` + +**See Also** + +- [missing](composition#posttranslation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------------------------------------- | ----------- | +| handler | PostTranslationHandler<VueMessageType> | null | A | + +### te(key, locale) + +Translation locale message exist + +**Signature:** + +```typescript +te = PickupKeys>(key: Str | Key, locale?: Locales): boolean; +``` + +**Details** + +whether do exist locale message on Composer instance [messages](composition#messages). + +If you specified `locale`, check the locale messages of `locale`. + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------- | --------------------------------------------------------------- | +| key | Str | Key | A target locale message key | +| locale | Locales | A locale, it will be used over than global scope or local scope | + +#### Returns + +If found locale message, `true`, else `false`, Note that `false` is returned even if the value present in the key is not translatable, yet if `translateExistCompatible` is set to `true`, it will return `true` if the key is available, even if the value is not translatable. + +### tm(key) + +Locale messages getter + +**Signature:** + +```typescript +tm = PickupKeys, Locale extends PickupLocales> = PickupLocales>, Target = IsEmptyObject extends false ? NonNullable[Locale] : RemoveIndexSignature<{ + [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; + }>, Return = ResourceKeys extends ResourcePath ? ResourceValue : Record>(key: Key | ResourceKeys): Return; +``` + +**Details** + +If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. + +Based on the current `locale`, locale messages will be returned from Composer instance messages. + +If you change the `locale`, the locale messages returned will also correspond to the locale. + +If there are no locale messages for the given `key` in the composer instance messages, they will be returned with [fallbacking](../../guide/essentials/fallback). + +:::warning +You need to use `rt` for the locale message returned by `tm`. see the [rt](composition#rt-message) details. +::: + +#### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------- | --------------------------- | +| key | Key | ResourceKeys | A target locale message key | + +Locale messages | + +**Examples** + +template block: + +```html +
+ +
+``` + +script block: + +```js +import { defineComponent } from 'vue +import { useI18n } from 'vue-i18n' + +export default defineComponent({ + setup() { + const { rt, tm } = useI18n({ + messages: { + en: { + contents: [ + { + title: 'Title1', + // ... + paragraphs: [ + // ... + ] + } + ] + } + } + // ... + }) + // ... + return { ... , rt, tm } + } +}) +``` + +## ComposerAdditionalOptions + +Composer additional options for `useI18n` + +**Signature:** + +```typescript +export interface ComposerAdditionalOptions +``` + +**Details** + +`ComposerAdditionalOptions` is extend for [ComposerOptions](composition#composeroptions), so you can specify these options. + +**See Also** + +- [useI18n](composition#usei18n) + +### useScope + +## ComposerCustom + +The type custom definition of Composer + +**Signature:** + +```typescript +export interface ComposerCustom +``` + +**Details** + +The interface that can extend Composer. + +The type defined by 3rd party (e.g. nuxt/i18n) + +**Examples** + +```ts +// vue-i18n.d.ts (`.d.ts` file at your app) + +declare module 'vue-i18n' { + interface ComposerCustom { + localeCodes: string[] + } +} +``` + +## ComposerDateTimeFormatting + +Datetime formatting functions + +**Signature:** + +```typescript +export interface ComposerDateTimeFormatting = {}, Locales = 'en-US', DefinedDateTimeFormat extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? PickupFormatPathKeys<{ + [K in keyof DefinedDateTimeFormat]: DefinedDateTimeFormat[K]; +}> : never, M = IsEmptyObject extends false ? PickupFormatKeys : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> +``` + +**Details** + +This is the interface for [Composer](composition#composer) + +### (value: number | Date | string): string; + +Datetime formatting + +**Signature:** + +```typescript +(value: number | Date | string): string; +``` + +**Details** + +If this is used in a reactive context, it will re-evaluate once the locale changes. + +If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope datetime formats than global scope datetime formats. + +If not, then it’s formatted with global scope datetime formats. + +**See Also** + +- [Datetime formatting](../../guide/essentials/datetime) + +#### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------------- | --------------------------------------------------------------- | +| value | number | Date | string | A value, timestamp number or `Date` instance or ISO 8601 string | + +#### Returns + +Formatted value + +### (value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>): string; + +Datetime formatting + +**Signature:** + +```typescript +(value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions): string; +``` + +**Details** + +Overloaded `d`. About details, see the [call signature](composition#value-number-date-string-string) details. + +In this overloaded `d`, format in datetime format for a key registered in datetime formats. + +#### Parameters + +| Parameter | Type | Description | +| ------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| value | Value | A value, timestamp number or `Date` instance or ISO 8601 string | +| keyOrOptions | Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> | A key of datetime formats, or additional for datetime formatting | + +#### Returns + +Formatted value + +### (value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>, locale: Locales): string; + +Datetime formatting + +**Signature:** + +```typescript +(value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions, locale: Locales): string; +``` + +**Details** + +Overloaded `d`. About details, see the [call signature](composition#value-number-date-string-string) details. + +In this overloaded `d`, format in datetime format for a key registered in datetime formats at target locale + +#### Parameters + +| Parameter | Type | Description | +| ------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| value | Value | A value, timestamp number or `Date` instance or ISO 8601 string | +| keyOrOptions | Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> | A key of datetime formats, or additional for datetime formatting | +| locale | Locales | A locale, it will be used over than global scope or local scope. | + +#### Returns + +Formatted value + +## ComposerNumberFormatting + +Number formatting functions + +**Signature:** + +```typescript +export interface ComposerNumberFormatting = {}, Locales = 'en-US', DefinedNumberFormat extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? PickupFormatPathKeys<{ + [K in keyof DefinedNumberFormat]: DefinedNumberFormat[K]; +}> : never, M = IsEmptyObject extends false ? PickupFormatKeys : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> +``` + +**Details** + +This is the interface for [Composer](composition#composer) + +### (value: number): string; + +Number Formatting + +**Signature:** + +```typescript +(value: number): string; +``` + +**Details** + +If this is used in a reactive context, it will re-evaluate once the locale changes. + +If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope datetime formats than global scope datetime formats. + +If not, then it’s formatted with global scope number formats. + +**See Also** + +- [Number formatting](../../guide/essentials/number) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------ | -------------- | +| value | number | A number value | + +#### Returns + +Formatted value + +### (value: number, keyOrOptions: Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>): PartType; + +Number Formatting + +**Signature:** + +```typescript +(value: number, keyOrOptions: Key | ResourceKeys | NumberOptions): PartType; +``` + +**Details** + +Overloaded `n`. About details, see the [call signature](composition#value-number-string) details. + +In this overloaded `n`, format in number format for a key registered in number formats. + +#### Parameters + +| Parameter | Type | Description | +| ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------ | +| value | number | A number value | +| keyOrOptions | Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> | A key of number formats, or additional for number formatting | + +#### Returns + +Formatted value + +### (value: number, keyOrOptions: Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>, locale: Locales): PartType; + +Number Formatting + +**Signature:** + +```typescript +(value: number, keyOrOptions: Key | ResourceKeys | NumberOptions, locale: Locales): PartType; +``` + +**Details** + +Overloaded `n`. About details, see the [call signature](composition#value-number-string) details. + +In this overloaded `n`, format in number format for a key registered in number formats at target locale. + +#### Parameters + +| Parameter | Type | Description | +| ------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| value | number | A number value | +| keyOrOptions | Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> | A key of number formats, or additional for number formatting | +| locale | Locales | A locale, it will be used over than global scope or local scope. | + +#### Returns + +Formatted value + +## ComposerOptions + +Composer Options + +**Signature:** + +```typescript +export interface ComposerOptions = LocaleMessages, _DateTimeFormats extends DateTimeFormatsType = DateTimeFormatsType, _NumberFormats extends NumberFormatsType = NumberFormatsType> +``` + +**Details** + +This is options to create composer. + +### datetime + +### datetimeFormats + +### escapeParameter + +**Signature:** + +```typescript +escapeParameter?: boolean; +``` + +**Details** + +If `escapeParameter` is configured as true then interpolation parameters are escaped before the message is translated. + +This is useful when translation output is used in `v-html` and the translation resource contains html markup (e.g. around a user provided value). + +This usage pattern mostly occurs when passing precomputed text strings into UI components. + +The escape process involves replacing the following symbols with their respective HTML character entities: `<`, `>`, `"`, `'`. + +Setting `escapeParameter` as true should not break existing functionality but provides a safeguard against a subtle type of XSS attack vectors. + +**Default Value** + +`false` + +**See Also** + +- [HTML Message](../../guide/essentials/syntax#html-message) + +### fallbackFormat + +**Signature:** + +```typescript +fallbackFormat?: boolean; +``` + +**Details** + +Whether do template interpolation on translation keys when your language lacks a translation for a key. + +If `true`, skip writing templates for your "base" language; the keys are your templates. + +**Default Value** + +`false` + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackLocale + +**Signature:** + +```typescript +fallbackLocale?: FallbackLocale; +``` + +**Details** + +The locale of fallback localization. + +For more complex fallback definitions see fallback. + +**Default Value** + +The default `'en-US'` for the `locale` if it's not specified, or it's `locale` value + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackRoot + +**Signature:** + +```typescript +fallbackRoot?: boolean; +``` + +**Details** + +In the component localization, whether to fallback to root level (global scope) localization when localization fails. + +If `false`, it's not fallback to root. + +**Default Value** + +`true` + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### fallbackWarn + +**Signature:** + +```typescript +fallbackWarn?: boolean | RegExp; +``` + +**Details** + +Whether suppress warnings when falling back to either `fallbackLocale` or root. + +If `false`, suppress fall back warnings. + +If you use regular expression, you can suppress fallback warnings that it match with translation key (e.g. `t`). + +**Default Value** + +`true` + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### flatJson + +**Signature:** + +```typescript +flatJson?: boolean; +``` + +**Details** + +Allow use flat json messages or not + +**Default Value** + +`false` + +### inheritLocale + +**Signature:** + +```typescript +inheritLocale?: boolean; +``` + +**Details** + +Whether inheritance the root level locale to the component localization locale. + +If `false`, regardless of the root level locale, localize for each component locale. + +**Default Value** + +`true` + +**See Also** + +- [Local Scope](../../guide/essentials/scope#local-scope-2) + +### locale + +**Signature:** + +```typescript +locale?: Locale; +``` + +**Details** + +The locale of localization. + +If the locale contains a territory and a dialect, this locale contains an implicit fallback. + +**Default Value** + +`'en-US'` + +**See Also** + +- [Scope and Locale Changing](../../guide/essentials/scope) + +### message + +### messageCompiler + +**Signature:** + +```typescript +messageCompiler?: MessageCompiler; +``` + +**Details** + +A compiler for custom message format. + +If not specified, the vue-i18n default message compiler will be used. + +You will need to implement your own message compiler that returns Message Functions + +:::tip +:new: v9.3+ +::: + +:::warning +The Custom Message Format is an experimental feature. It may receive breaking changes or be removed in the future. +::: + +**Default Value** + +`undefined` + +**See Also** + +- [Custom Message Format](../../guide/advanced/format) + +**Examples** + +Here is an example of how to custom message compiler with `intl-messageformat` + +```js +import { createI18n } from 'vue-i18n' +import IntlMessageFormat from 'intl-messageformat' + +function messageCompiler(message, { locale, key, onError }) { + if (typeof message === 'string') { + // You can tune your message compiler performance more with your cache strategy or also memoization at here + const formatter = new IntlMessageFormat(message, locale) + return ctx => formatter.format(ctx.values) + } else { + // If you would like to support it for AST, + // You need to transform locale mesages such as `json`, `yaml`, etc. with the bundle plugin. + onError && onError(new Error('not support for AST')) + return () => key // return default with `key` + } +} + +// call with I18n option +const i18n = createI18n({ + locale: 'ja', + messageCompiler, // set your message compiler + messages: { + en: { + hello: 'hello world!', + greeting: 'hi, {name}!', + // ICU Message format + photo: `You have {numPhotos, plural, + =0 {no photos.} + =1 {one photo.} + other {# photos.} + }` + } + } +}) + +// the below your something to do ... +// ... +``` + +### messageResolver + +**Signature:** + +```typescript +messageResolver?: MessageResolver; +``` + +**Details** + +A message resolver to resolve [`messages`](composition#messages). + +If not specified, the vue-i18n internal message resolver will be used by default. + +You need to implement a message resolver yourself that supports the following requirements: + +- Resolve the message using the locale message of [`locale`](composition#locale) passed as the first argument of the message resolver, and the path passed as the second argument. + +- If the message could not be resolved, you need to return `null`. + +- If you will be returned `null`, the message resolver will also be called on fallback if [`fallbackLocale`](composition#fallbacklocale-2) is enabled, so the message will need to be resolved as well. + +The message resolver is called indirectly by the following APIs: + +- [`t`](composition#t-key) + +- [`te`](composition#te-key-locale) + +- [`tm`](composition#tm-key) + +- [Translation component](component#translation) + +:::tip +:new: v9.2+ +::: + +:::warning +If you use the message resolver, the [`flatJson`](composition#flatjson) setting will be ignored. That is, you need to resolve the flat JSON by yourself. +::: + +**Default Value** + +`undefined` + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +**Examples** + +Here is an example of how to set it up using your `createI18n`: + +```js +import { createI18n } from 'vue-i18n' + +// your message resolver +function messageResolver(obj, path) { + // simple message resolving! + const msg = obj[path] + return msg != null ? msg : null +} + +// call with I18n option +const i18n = createI18n({ + locale: 'ja', + messageResolver, // set your message resolver + messages: { + en: { ... }, + ja: { ... } + } +}) + +// the below your something to do ... +// ... +``` + +### messages + +### missing + +**Signature:** + +```typescript +missing?: MissingHandler; +``` + +**Details** + +A handler for localization missing. + +The handler gets called with the localization target locale, localization path key, the Vue instance and values. + +If missing handler is assigned, and occurred localization missing, it's not warned. + +**Default Value** + +`null` + +### missingWarn + +**Signature:** + +```typescript +missingWarn?: boolean | RegExp; +``` + +**Details** + +Whether suppress warnings outputted when localization fails. + +If `false`, suppress localization fail warnings. + +If you use regular expression, you can suppress localization fail warnings that it match with translation key (e.g. `t`). + +**Default Value** + +`true` + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### modifiers + +**Signature:** + +```typescript +modifiers?: LinkedModifiers; +``` + +**Details** + +Custom Modifiers for linked messages. + +**See Also** + +- [Custom Modifiers](../../guide/essentials/syntax#custom-modifiers) + +### number + +### numberFormats + +### pluralRules + +**Signature:** + +```typescript +pluralRules?: PluralizationRules; +``` + +**Details** + +A set of rules for word pluralization + +**Default Value** + +`{}` + +**See Also** + +- [Custom Pluralization](../../guide/essentials/pluralization#custom-pluralization) + +### postTranslation + +**Signature:** + +```typescript +postTranslation?: PostTranslationHandler; +``` + +**Details** + +A handler for post processing of translation. + +The handler gets after being called with the `t`. + +This handler is useful if you want to filter on translated text such as space trimming. + +**Default Value** + +`null` + +### warnHtmlMessage + +**Signature:** + +```typescript +warnHtmlMessage?: boolean; +``` + +**Details** + +Whether to allow the use locale messages of HTML formatting. + +See the warnHtmlMessage property. + +**Default Value** + +`'off'` + +**See Also** + +- [HTML Message](../../guide/essentials/syntax#html-message) +- [Change `warnHtmlInMessage` option default value](../../guide/migration/breaking#change-warnhtmlinmessage-option-default-value) + +## ComposerResolveLocaleMessageTranslation + +Resolve locale message translation functions + +**Signature:** + +```typescript +export interface ComposerResolveLocaleMessageTranslation +``` + +**Details** + +This is the interface for [Composer](composition#composer) + +### (message: MessageFunction<VueMessageType> | VueMessageType): string; + +Resolve locale message translation + +**Signature:** + +```typescript +(message: MessageFunction | VueMessageType): string; +``` + +**Details** + +If this is used in a reactive context, it will re-evaluate once the locale changes. + +If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. + +If not, then it’s translated with global scope locale messages. + +**See Also** + +- [Scope and Locale Changing](../../guide/essentials/scope) + +:::tip +The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. +::: + +:::warning +`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. +::: + +#### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | + +#### Returns + +Translated message + +### (message: MessageFunction<VueMessageType> | VueMessageType, plural: number, options?: TranslateOptions<Locales>): string; + +Resolve locale message translation for plurals + +**Signature:** + +```typescript +(message: MessageFunction | VueMessageType, plural: number, options?: TranslateOptions): string; +``` + +**Details** + +Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. + +In this overloaded `rt`, return a pluralized translation message. + +**See Also** + +- [Pluralization](../../guide/essentials/pluralization) + +:::tip +The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. +::: + +:::warning +`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. +::: + +#### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | +| plural | number | Which plural string to get. 1 returns the first one. | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +### (message: MessageFunction<VueMessageType> | VueMessageType, list: unknown[], options?: TranslateOptions<Locales>): string; + +Resolve locale message translation for list interpolations + +**Signature:** + +```typescript +(message: MessageFunction | VueMessageType, list: unknown[], options?: TranslateOptions): string; +``` + +**Details** + +Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. + +In this overloaded `rt`, return a pluralized translation message. + +**See Also** + +- [List interpolation](../../guide/essentials/syntax#list-interpolation) + +:::tip +The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. +::: + +:::warning +`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. +::: + +#### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | +| list | unknown[] | A values of list interpolation. | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +### (message: MessageFunction<VueMessageType> | VueMessageType, named: NamedValue, options?: TranslateOptions<Locales>): string; + +Resolve locale message translation for named interpolations + +**Signature:** + +```typescript +(message: MessageFunction | VueMessageType, named: NamedValue, options?: TranslateOptions): string; +``` + +**Details** + +Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. + +In this overloaded `rt`, for each placeholder x, the locale messages should contain a `{x}` token. + +**See Also** + +- [Named interpolation](../../guide/essentials/syntax#named-interpolation) + +:::tip +The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. +::: + +:::warning +`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. +::: + +#### Parameters + +| Parameter | Type | Description | +| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | +| named | NamedValue | A values of named interpolation. | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +## ComposerTranslation + +Locale message translation functions + +**Signature:** + +```typescript +export interface ComposerTranslation = {}, Locales = 'en-US', DefinedLocaleMessage extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? JsonPaths<{ + [K in keyof DefinedLocaleMessage]: DefinedLocaleMessage[K]; +}> : never, M = IsEmptyObject extends false ? TranslationsPaths : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> +``` + +**Details** + +This is the interface for [Composer](composition#composer) + +### (key: Key | ResourceKeys | number): string; + +Locale message translation + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number): string; +``` + +**Details** + +If this is used in a reactive context, it will re-evaluate once the locale changes. + +If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. + +If not, then it’s translated with global scope locale messages. + +**See Also** + +- [Scope and Locale Changing](../../guide/essentials/scope) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | --------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, named: NamedValue): string; + +Locale message translation for named interpolations + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, named: NamedValue): string; +``` + +**Details** + +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. + +**See Also** + +- [Named interpolation](../../guide/essentials/syntax#named-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| named | NamedValue | A values of named interpolation | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, named: NamedValue, plural: number): string; + +Locale message translation for named interpolations and plurals + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, named: NamedValue, plural: number): string; +``` + +**Details** + +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, and return a pluralized translation message. + +**See Also** + +- [Pluralization](../../guide/essentials/pluralization) +- [Named interpolation](../../guide/essentials/syntax#named-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ---------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| named | NamedValue | A values of named interpolation | +| plural | number | Which plural string to get. 1 returns the first one. | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string; + +Locale message translation for named interpolations and plurals + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string; +``` + +**Details** + +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, and if no translation was found, return a default message. + +**See Also** + +- [Named interpolation](../../guide/essentials/syntax#named-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------------------- | ------------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| named | NamedValue | A values of named interpolation | +| defaultMsg | string | A default message to return if no translation was found | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions<Locales>): string; + +Locale message translation for named interpolations + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions): string; +``` + +**Details** + +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 . + +**See Also** + +- [Named interpolation](../../guide/essentials/syntax#named-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| named | NamedValue | A values of named interpolation | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, plural: number): string; + +Locale message translation for plurals + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, plural: number): string; +``` + +**Details** + +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. + +**See Also** + +- [Pluralization](../../guide/essentials/pluralization) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ---------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| plural | number | Which plural string to get. 1 returns the first one. | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, plural: number, options: TranslateOptions<Locales>): string; + +Locale message translation for plurals + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, plural: number, options: TranslateOptions): string; +``` + +**Details** + +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. + +About details of options, see the . + +**See Also** + +- [Pluralization](../../guide/essentials/pluralization) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ---------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| plural | number | Which plural string to get. 1 returns the first one. | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, defaultMsg: string): string; + +Locale message translation for missing default message + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, defaultMsg: string): string; +``` + +**Details** + +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. + +#### Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------------------- | ------------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| defaultMsg | string | A default message to return if no translation was found | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions<Locales>): string; + +Locale message translation for missing default message + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions): string; +``` + +**Details** + +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. + +About details of options, see the . + +#### Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------------------- | ------------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| defaultMsg | string | A default message to return if no translation was found | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, list: unknown[]): string; + +Locale message translation for list interpolations + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, list: unknown[]): string; +``` + +**Details** + +Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. + +**See Also** + +- [List interpolation](../../guide/essentials/syntax#list-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ------------------------------ | +| key | Key | ResourceKeys | number | A target locale message key | +| list | unknown[] | A values of list interpolation | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, list: unknown[], plural: number): string; + +Locale message translation for list interpolations and plurals + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, list: unknown[], plural: number): string; +``` + +**Details** + +Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. + +**See Also** + +- [Pluralization](../../guide/essentials/pluralization) +- [List interpolation](../../guide/essentials/syntax#list-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ---------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| list | unknown[] | A values of list interpolation | +| plural | number | Which plural string to get. 1 returns the first one. | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, list: unknown[], defaultMsg: string): string; + +Locale message translation for list interpolations and missing default message + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, list: unknown[], defaultMsg: string): string; +``` + +**Details** + +Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. + +**See Also** + +- [List interpolation](../../guide/essentials/syntax#list-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| ---------- | ------------------------------------- | ------------------------------------------------------- | +| key | Key | ResourceKeys | number | A target locale message key | +| list | unknown[] | A values of list interpolation | +| defaultMsg | string | A default message to return if no translation was found | + +#### Returns + +Translated message + +### (key: Key | ResourceKeys | number, list: unknown[], options: TranslateOptions<Locales>): string; + +Locale message translation for list interpolations + +**Signature:** + +```typescript +(key: Key | ResourceKeys | number, list: unknown[], options: TranslateOptions): string; +``` + +**Details** + +Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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 . + +**See Also** + +- [List interpolation](../../guide/essentials/syntax#list-interpolation) + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------------------------------- | ------------------------------ | +| key | Key | ResourceKeys | number | A target locale message key | +| list | unknown[] | A values of list interpolation | +| options | TranslateOptions<Locales> | Additional for translation | + +#### Returns + +Translated message + +## MissingHandler + +**Signature:** + +```typescript +export type MissingHandler = ( + locale: Locale, + key: Path, + instance?: ComponentInternalInstance, + type?: string +) => string | void +``` + +## useI18n + +Use Composition API for Vue I18n + +**Signature:** + +```typescript +export declare function useI18n< + Schema = DefaultLocaleMessageSchema, + Locales = 'en-US', + Options extends UseI18nOptions< + SchemaParams, + LocaleParams + > = UseI18nOptions< + SchemaParams, + LocaleParams + > +>( + options?: Options +): Composer< + NonNullable, + NonNullable, + NonNullable, + NonNullable +> +``` + +### Type Parameters + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------- | +| Schema | The i18n resources (messages, datetimeFormats, numberFormats) schema, default | +| Locales | The locales of i18n resource schema, default `en-US` | + +**Details** + +This function is mainly used by `setup`. + +If options are specified, Composer instance is created for each component and you can be localized on the component. + +If options are not specified, you can be localized using the global Composer. + +### Parameters + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------------ | +| options | Options | An options, see [UseI18nOptions](composition#usei18noptions) | + +### Returns + +[Composer](composition#composer) instance + +**Examples** + +case: Component resource base localization + +```html + + + +``` + +## UseI18nOptions + +I18n Options for `useI18n` + +**Signature:** + +```typescript +export type UseI18nOptions< + Schema extends { + message?: unknown + datetime?: unknown + number?: unknown + } = { + message: DefaultLocaleMessageSchema + datetime: DefaultDateTimeFormatSchema + number: DefaultNumberFormatSchema + }, + Locales extends + | { + messages: unknown + datetimeFormats: unknown + numberFormats: unknown + } + | string = Locale, + Options extends ComposerOptions = ComposerOptions< + Schema, + Locales + > +> = ComposerAdditionalOptions & Options +``` + +**Details** + +`UseI18nOptions` is inherited [ComposerAdditionalOptions](composition#composeradditionaloptions) and [ComposerOptions](composition#composeroptions), so you can specify these options. + +**See Also** + +- [useI18n](composition#usei18n) + +## VueMessageType + +**Signature:** + +```typescript +export type VueMessageType = string | ResourceNode | VNode +``` diff --git a/v11/directive.md b/v11/directive.md new file mode 100644 index 000000000..dab690fad --- /dev/null +++ b/v11/directive.md @@ -0,0 +1 @@ +# Directives diff --git a/v11/general.md b/v11/general.md new file mode 100644 index 000000000..6d440cfd1 --- /dev/null +++ b/v11/general.md @@ -0,0 +1,1313 @@ +# General + +## createI18n + +Vue I18n factory + +**Signature:** + +```typescript +export declare function createI18n< + Schema extends object = DefaultLocaleMessageSchema, + Locales extends string | object = 'en-US', + Options extends I18nOptions< + SchemaParams, + LocaleParams + > = I18nOptions, LocaleParams>, + Messages extends Record = NonNullable< + Options['messages'] + > extends Record + ? NonNullable + : {}, + DateTimeFormats extends Record = NonNullable< + Options['datetimeFormats'] + > extends Record + ? NonNullable + : {}, + NumberFormats extends Record = NonNullable< + Options['numberFormats'] + > extends Record + ? NonNullable + : {}, + OptionLocale = Options['locale'] extends string ? Options['locale'] : Locale +>( + options: Options +): I18n +``` + +### Type Parameters + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------- | +| Schema | The i18n resources (messages, datetimeFormats, numberFormats) schema, default | +| Locales | The locales of i18n resource schema, default `en-US` | + +**See Also** + +- [Getting Started](../../guide/essentials/started) +- [Composition API](../../guide/advanced/composition) + +### Parameters + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------ | +| options | Options | An options, see the [I18nOptions](general#i18noptions) | + +### Returns + +[I18n](general#i18n) instance + +**Examples** + +```js +import { createApp } from 'vue' +import { createI18n, useI18n } from 'vue-i18n' + +// call with I18n option +const i18n = createI18n({ + locale: 'ja', + messages: { + en: { ... }, + ja: { ... } + } +}) + +const App = { + setup() { + // ... + const { t } = useI18n({ ... }) + return { ... , t } + } +} + +const app = createApp(App) + +// install! +app.use(i18n) +app.mount('#app') +``` + +## DefineDateTimeFormat + +The type definition of datetime format + +**Signature:** + +```typescript +export interface DefineDateTimeFormat extends DateTimeFormat +``` + +**Details** + +The typealias is used to strictly define the type of the Datetime format. + +The type defined by this can be used in the global scope. + +**Examples** + +```ts +// type.d.ts (`.d.ts` file at your app) +import { DefineDateTimeFormat } from 'vue-i18n' + +declare module 'vue-i18n' { + export interface DefineDateTimeFormat { + short: { + hour: 'numeric' + timezone: string + } + } +} +``` + +## DefineLocaleMessage + +The type definition of Locale Message + +**Signature:** + +```typescript +export interface DefineLocaleMessage extends LocaleMessage +``` + +**Details** + +The typealias is used to strictly define the type of the Locale message. + +The type defined by this can be used in the global scope. + +**Examples** + +```ts +// type.d.ts (`.d.ts` file at your app) +import { DefineLocaleMessage } from 'vue-i18n' + +declare module 'vue-i18n' { + export interface DefineLocaleMessage { + title: string + menu: { + login: string + } + } +} +``` + +## DefineNumberFormat + +The type definition of number format + +**Signature:** + +```typescript +export interface DefineNumberFormat extends NumberFormat +``` + +**Details** + +The typealias is used to strictly define the type of the Number format. + +The type defined by this can be used in the global scope. + +**Examples** + +```ts +// type.d.ts (`.d.ts` file at your app) +import { DefineNumberFormat } from 'vue-i18n' + +declare module 'vue-i18n' { + export interface DefineNumberFormat { + currency: { + style: 'currency' + currencyDisplay: 'symbol' + currency: string + } + } +} +``` + +## ExportedGlobalComposer + +Exported global composer instance + +**Signature:** + +```typescript +export interface ExportedGlobalComposer +``` + +**Details** + +This interface is the [global composer](general#global) that is provided interface that is injected into each component with `app.config.globalProperties`. + +### availableLocales + +Available locales + +**Signature:** + +```typescript +readonly availableLocales: Locale[]; +``` + +**Details** + +This property is proxy-like property for `Composer#availableLocales`. About details, see the [Composer#availableLocales](composition#availablelocales) + +### fallbackLocale + +Fallback locale + +**Signature:** + +```typescript +fallbackLocale: FallbackLocale +``` + +**Details** + +This property is proxy-like property for `Composer#fallbackLocale`. About details, see the [Composer#fallbackLocale](composition#fallbacklocale) + +### locale + +Locale + +**Signature:** + +```typescript +locale: Locale +``` + +**Details** + +This property is proxy-like property for `Composer#locale`. About details, see the [Composer#locale](composition#locale) + +## I18n + +I18n instance + +**Signature:** + +```typescript +export interface I18n = {}, DateTimeFormats extends Record = {}, NumberFormats extends Record = {}, OptionLocale = Locale> +``` + +**Details** + +The instance required for installation as the Vue plugin + +### global + +The property accessible to the global Composer instance + +An instance of this property is **global scope\***. + +**Signature:** + +```typescript +readonly global: Composer; +``` + +### dispose() + +Release global scope resource + +**Signature:** + +```typescript +dispose(): void; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ---- | ----------- | + +### install(app, options) + +Install entry point + +**Signature:** + +```typescript +install(app: App, ...options: unknown[]): void; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | --------- | ------------------------- | +| app | App | A target Vue app instance | +| options | unknown[] | An install options | + +## I18nAdditionalOptions + +I18n Additional Options + +**Signature:** + +```typescript +export interface I18nAdditionalOptions +``` + +**Details** + +Specific options for + +### globalInjection + +Whether to inject global properties & functions into for each component. + +**Signature:** + +```typescript +globalInjection?: boolean; +``` + +**Details** + +If set to `true`, then properties and methods prefixed with `$` are injected into Vue Component. + +**Default Value** + +`true` + +**See Also** + +- [Implicit with injected properties and functions](../../guide/advanced/composition#implicit-with-injected-properties-and-functions) +- [ComponentCustomProperties](injection#componentcustomproperties) + +## I18nOptions + +I18n Options for `createI18n` + +**Signature:** + +```typescript +export type I18nOptions< + Schema extends { + message?: unknown + datetime?: unknown + number?: unknown + } = { + message: DefaultLocaleMessageSchema + datetime: DefaultDateTimeFormatSchema + number: DefaultNumberFormatSchema + }, + Locales extends + | { + messages: unknown + datetimeFormats: unknown + numberFormats: unknown + } + | string = Locale, + Options = ComposerOptions +> = I18nAdditionalOptions & Options +``` + +## I18nPluginOptions + +Vue I18n plugin options + +**Signature:** + +```typescript +export interface I18nPluginOptions +``` + +**Details** + +An options specified when installing Vue I18n as Vue plugin with using `app.use`. + +### globalInstall + +Whether to globally install the components that is offered by Vue I18n + +**Signature:** + +```typescript +globalInstall?: boolean; +``` + +**Details** + +If this option is enabled, the components will be installed globally at `app.use` time. + +If you want to install manually in the `import` syntax, you can set it to `false` to install when needed. + +**Default Value** + +`true` + +## I18nScope + +I18n Scope + +**Signature:** + +```typescript +export type I18nScope = 'local' | 'parent' | 'global' +``` + +**See Also** + +- [ComposerAdditionalOptions#useScope](composition#usescope) +- [useI18n](composition#usei18n) + +## VERSION + +Vue I18n Version + +**Signature:** + +```typescript +VERSION: string +``` + +**Details** + +Semver format. Same format as the package.json `version` field. + +## DateTimeOptions + +DateTime options + +**Signature:** + +```typescript +export interface DateTimeOptions extends Intl.DateTimeFormatOptions, LocaleOptions +``` + +**Details** + +Options for Datetime formatting API + +### fallbackWarn + +**Signature:** + +```typescript +fallbackWarn?: boolean; +``` + +**Details** + +Whether do resolve on format keys when your language lacks a formatting for a key + +### key + +**Signature:** + +```typescript +key?: Key; +``` + +**Details** + +The target format key + +### missingWarn + +**Signature:** + +```typescript +missingWarn?: boolean; +``` + +**Details** + +Whether suppress warnings outputted when localization fails + +### part + +**Signature:** + +```typescript +part?: boolean; +``` + +**Details** + +Whether to use [Intel.DateTimeFormat#formatToParts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts) + +## DefineCoreLocaleMessage + +The type definition of Locale Message for `@intlify/core-base` package + +**Signature:** + +```typescript +export interface DefineCoreLocaleMessage extends LocaleMessage +``` + +**Details** + +The typealias is used to strictly define the type of the Locale message. + +**Examples** + +```ts +// type.d.ts (`.d.ts` file at your app) +import { DefineCoreLocaleMessage } from '@intlify/core-base' + +declare module '@intlify/core-base' { + export interface DefineCoreLocaleMessage { + title: string + menu: { + login: string + } + } +} +``` + +## FallbackLocale + +**Signature:** + +```typescript +export type FallbackLocale = + | Locale + | Locale[] + | { + [locale in string]: Locale[] + } + | false +``` + +## fallbackWithLocaleChain + +Fallback with locale chain + +**Signature:** + +```typescript +export declare function fallbackWithLocaleChain( + ctx: CoreContext, + fallback: FallbackLocale, + start: Locale +): Locale[] +``` + +**Details** + +A fallback locale function implemented with a fallback chain algorithm. It's used in VueI18n as default. + +**See Also** + +- [Fallbacking](../../guide/essentials/fallback) + +### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ------------------------------------------- | +| ctx | CoreContext<Message> | A [context](#corecontext) | +| fallback | FallbackLocale | A [fallback locale](general#fallbacklocale) | +| start | Locale | A starting [locale](general#locale) | + +### Returns + +Fallback locales + +## fallbackWithSimple + +Fallback with simple implemenation + +**Signature:** + +```typescript +export declare function fallbackWithSimple( + ctx: CoreContext, + fallback: FallbackLocale, + start: Locale +): Locale[] +``` + +**Details** + +A fallback locale function implemented with a simple fallback algorithm. + +Basically, it returns the value as specified in the `fallbackLocale` props, and is processed with the fallback inside intlify. + +### Parameters + +| Parameter | Type | Description | +| --------- | -------------------------- | ------------------------------------------- | +| ctx | CoreContext<Message> | A [context](#corecontext) | +| fallback | FallbackLocale | A [fallback locale](general#fallbacklocale) | +| start | Locale | A starting [locale](general#locale) | + +### Returns + +Fallback locales + +## LinkedModifiers + +**Signature:** + +```typescript +export type LinkedModifiers = { + [key: string]: LinkedModify +} +``` + +## Locale + +**Signature:** + +```typescript +export type Locale = + IsNever extends true ? string : GeneratedLocale +``` + +## LocaleDetector + +**Signature:** + +```typescript +export interface LocaleDetector +``` + +### resolvedOnce + +### (...args: Args): Locale | Promise<Locale>; + +## LocaleFallbacker + +The locale fallbacker + +**Signature:** + +```typescript +export type LocaleFallbacker = ( + ctx: CoreContext, + fallback: FallbackLocale, + start: Locale +) => Locale[] +``` + +## LocaleMessage + +**Signature:** + +```typescript +export type LocaleMessage = Record< + string, + LocaleMessageValue +> +``` + +## LocaleMessageDictionary + +**Signature:** + +```typescript +export type LocaleMessageDictionary = { + [K in keyof T]: LocaleMessageType +} +``` + +## LocaleMessages + +**Signature:** + +```typescript +export type LocaleMessages< + Schema, + Locales = Locale, + Message = string +> = LocaleRecord, Schema> +``` + +## LocaleMessageType + +**Signature:** + +```typescript +export type LocaleMessageType = T extends string + ? string + : T extends () => Promise + ? LocaleMessageDictionary + : T extends (...args: infer Arguments) => any + ? (...args: Arguments) => ReturnType + : T extends Record + ? LocaleMessageDictionary + : T extends Array + ? { + [K in keyof T]: T[K] + } + : T +``` + +## LocaleMessageValue + +**Signature:** + +```typescript +export type LocaleMessageValue = + | LocaleMessageDictionary + | string +``` + +## LocaleOptions + +**Signature:** + +```typescript +export interface LocaleOptions +``` + +### locale + +**Signature:** + +```typescript +locale?: Locales | LocaleDetector; +``` + +**Details** + +The locale of localization + +## MessageCompiler + +The message compiler + +**Signature:** + +```typescript +export type MessageCompiler< + Message = string, + MessageSource = string | ResourceNode +> = ( + message: MessageSource, + context: MessageCompilerContext +) => MessageFunction +``` + +## MessageCompilerContext + +The context that will pass the message compiler. + +**Signature:** + +```typescript +export type MessageCompilerContext = Pick< + CompileOptions, + 'onError' | 'onCacheKey' +> & { + warnHtmlMessage?: boolean + key: string + locale: Locale +} +``` + +## MessageContext + +The message context. + +**Signature:** + +```typescript +export interface MessageContext +``` + +### type + +The message type to be handled by the message function. + +**Signature:** + +```typescript +type: string +``` + +**Details** + +Usually `text`, you need to return **string** in message function. + +### values + +The message values. + +**Signature:** + +```typescript +values: Record +``` + +**Details** + +The message values are the argument values passed from translation function, such as `$t`, `t`, or `translate`. + +**Examples** + +vue-i18n `$t` (or `t`) case: + +```html +

{{ $t('greeting', { name: 'DIO' }) }}

+ +``` + +`@intlify/core` (`@intlify/core-base`) `translate` case: + +```js +translate(context, 'foo.bar', ['dio']) // `['dio']` is message values +``` + +### linked(key, modifier) + +Resolve linked message. + +**Signature:** + +```typescript +linked(key: Path, modifier?: string): MessageType; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ------------- | +| key | Path | A message key | +| modifier | string | A modifier | + +#### Returns + +A resolve message. + +### linked(key, modifier, type) + +Overloaded `linked` + +**Signature:** + +```typescript +linked(key: Path, modifier?: string, type?: string): MessageType; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------ | -------------- | +| key | Path | A message key | +| modifier | string | A modifier | +| type | string | A message type | + +#### Returns + +A resolve message. + +### linked(key, optoins) + +Overloaded `linked` + +**Signature:** + +```typescript +linked(key: Path, optoins?: LinkedOptions): MessageType; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------------- | ----------------------------------- | +| key | Path | A message key | +| optoins | LinkedOptions | An [linked options](#linkedoptions) | + +#### Returns + +A resolve message. + +### list(index) + +Resolve message value from list. + +**Signature:** + +```typescript +list(index: number): unknown; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------ | --------------------------- | +| index | number | An index of message values. | + +#### Returns + +A resolved message value. + +**Examples** + +```js +const messages = { + en: { + greeting: ({ list }) => `hello, ${list(0)}!` + } +} +``` + +### named(key) + +Resolve message value from named. + +**Signature:** + +```typescript +named(key: string): unknown; +``` + +#### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ----------------------- | +| key | string | A key of message value. | + +#### Returns + +A resolved message value. + +**Examples** + +```js +const messages = { + en: { + greeting: ({ named }) => `hello, ${named('name')}!` + } +} +``` + +### plural(messages) + +Resolve message with plural index. + +**Signature:** + +```typescript +plural(messages: T[]): T; +``` + +**Details** + +That's resolved with plural index with translation function. + +#### Parameters + +| Parameter | Type | Description | +| --------- | ---- | --------------------------------------------------------------------------- | +| messages | T[] | the messages, that is resolved with plural index with translation function. | + +#### Returns + +A resolved message. + +**Examples** + +```js +const messages = { + en: { + car: ({ plural }) => plural(['car', 'cars']), + apple: ({ plural, named }) => + plural(['no apples', 'one apple', `${named('count')} apples`]) + } +} +``` + +## MessageFunction + +The Message Function. + +**Signature:** + +```typescript +export type MessageFunction = + | MessageFunctionCallable + | MessageFunctionInternal +``` + +## MessageFunctionReturn + +**Signature:** + +```typescript +export type MessageFunctionReturn = T extends string + ? MessageType + : MessageType[] +``` + +## MessageResolver + +**Signature:** + +```typescript +export type MessageResolver = (obj: unknown, path: Path) => PathValue +``` + +## NamedValue + +**Signature:** + +```typescript +export type NamedValue = T & Record +``` + +## NumberOptions + +Number Options + +**Signature:** + +```typescript +export interface NumberOptions extends Intl.NumberFormatOptions, LocaleOptions +``` + +**Details** + +Options for Number formatting API + +### fallbackWarn + +**Signature:** + +```typescript +fallbackWarn?: boolean; +``` + +**Details** + +Whether do resolve on format keys when your language lacks a formatting for a key + +### key + +**Signature:** + +```typescript +key?: Key; +``` + +**Details** + +The target format key + +### missingWarn + +**Signature:** + +```typescript +missingWarn?: boolean; +``` + +**Details** + +Whether suppress warnings outputted when localization fails + +### part + +**Signature:** + +```typescript +part?: boolean; +``` + +**Details** + +Whether to use [Intel.NumberFormat#formatToParts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts) + +## Path + +**Signature:** + +```typescript +export type Path = string +``` + +## PathValue + +**Signature:** + +```typescript +export type PathValue = + | string + | number + | boolean + | Function + | null + | { + [key: string]: PathValue + } + | PathValue[] +``` + +## PluralizationRules + +**Signature:** + +```typescript +export type PluralizationRules = { + [locale: string]: PluralizationRule +} +``` + +## PostTranslationHandler + +**Signature:** + +```typescript +export type PostTranslationHandler = ( + translated: MessageFunctionReturn, + key: string +) => MessageFunctionReturn +``` + +## registerLocaleFallbacker + +Register the locale fallbacker + +**Signature:** + +```typescript +export declare function registerLocaleFallbacker( + fallbacker: LocaleFallbacker +): void +``` + +### Parameters + +| Parameter | Type | Description | +| ---------- | ---------------- | ------------------------------------------------------- | +| fallbacker | LocaleFallbacker | A [LocaleFallbacker](general#localefallbacker) function | + +## registerMessageResolver + +Register the message resolver + +**Signature:** + +```typescript +export declare function registerMessageResolver(resolver: MessageResolver): void +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | --------------- | ----------------------------------------------------- | +| resolver | MessageResolver | A [MessageResolver](general#messageresolver) function | + +## resolveValue + +message resolver + +**Signature:** + +```typescript +export declare function resolveValue(obj: unknown, path: Path): PathValue +``` + +**Details** + +Resolves messages. messages with a hierarchical structure such as objects can be resolved. This resolver is used in VueI18n as default. + +### Parameters + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------ | +| obj | unknown | A target object to be resolved with path | +| path | Path | A [path](general#path) to resolve the value of message | + +### Returns + +A resolved [path value](general#pathvalue) + +## resolveWithKeyValue + +key-value message resolver + +**Signature:** + +```typescript +export declare function resolveWithKeyValue(obj: unknown, path: Path): PathValue +``` + +**Details** + +Resolves messages with the key-value structure. Note that messages with a hierarchical structure such as objects cannot be resolved + +### Parameters + +| Parameter | Type | Description | +| --------- | ------- | ------------------------------------------------------ | +| obj | unknown | A target object to be resolved with path | +| path | Path | A [path](general#path) to resolve the value of message | + +### Returns + +A resolved [path value](general#pathvalue) + +## TranslateOptions + +Translate Options + +**Signature:** + +```typescript +export interface TranslateOptions extends LocaleOptions +``` + +**Details** + +Options for Translation API + +### default + +**Signature:** + +```typescript +default?: string | boolean; +``` + +**Details** + +Default message when is occurred translation missing + +### escapeParameter + +**Signature:** + +```typescript +escapeParameter?: boolean; +``` + +**Details** + +Whether do escape parameter for list or named interpolation values + +### fallbackWarn + +**Signature:** + +```typescript +fallbackWarn?: boolean; +``` + +**Details** + +Whether do template interpolation on translation keys when your language lacks a translation for a key + +### list + +**Signature:** + +```typescript +list?: unknown[]; +``` + +**Details** + +List interpolation + +### missingWarn + +**Signature:** + +```typescript +missingWarn?: boolean; +``` + +**Details** + +Whether suppress warnings outputted when localization fails + +### named + +**Signature:** + +```typescript +named?: NamedValue; +``` + +**Details** + +Named interpolation + +### plural + +**Signature:** + +```typescript +plural?: number; +``` + +**Details** + +Plulralzation choice number + +### resolvedMessage + +**Signature:** + +```typescript +resolvedMessage?: boolean; +``` + +**Details** + +Whether the message has been resolved diff --git a/v11/legacy.md b/v11/legacy.md new file mode 100644 index 000000000..d10d85e5d --- /dev/null +++ b/v11/legacy.md @@ -0,0 +1 @@ +# Legacy API From 8dbd0db5dfdb0073fa5b597aa3853a1e0fc9200e Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Tue, 17 Jun 2025 00:28:38 +0900 Subject: [PATCH 2/4] chore: wrong commits --- v11/component.md | 1 - v11/directive.md | 1 - v11/legacy.md | 1 - 3 files changed, 3 deletions(-) delete mode 100644 v11/component.md delete mode 100644 v11/directive.md delete mode 100644 v11/legacy.md diff --git a/v11/component.md b/v11/component.md deleted file mode 100644 index 0eac4eb52..000000000 --- a/v11/component.md +++ /dev/null @@ -1 +0,0 @@ -# Components diff --git a/v11/directive.md b/v11/directive.md deleted file mode 100644 index dab690fad..000000000 --- a/v11/directive.md +++ /dev/null @@ -1 +0,0 @@ -# Directives diff --git a/v11/legacy.md b/v11/legacy.md deleted file mode 100644 index d10d85e5d..000000000 --- a/v11/legacy.md +++ /dev/null @@ -1 +0,0 @@ -# Legacy API From 2cfb55978b938426e39a9154a9d53dc82867d26a Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Tue, 17 Jun 2025 00:29:25 +0900 Subject: [PATCH 3/4] chore: remove more wrong commits --- v11/composition.md | 2338 -------------------------------------------- v11/general.md | 1313 ------------------------- 2 files changed, 3651 deletions(-) delete mode 100644 v11/composition.md delete mode 100644 v11/general.md diff --git a/v11/composition.md b/v11/composition.md deleted file mode 100644 index e0457b759..000000000 --- a/v11/composition.md +++ /dev/null @@ -1,2338 +0,0 @@ -# Composition API - -## Composer - -Composer interfaces - -**Signature:** - -```typescript -export interface Composer = {}, DateTimeFormats extends Record = {}, NumberFormats extends Record = {}, OptionLocale = Locale, ResourceLocales = PickupLocales> | PickupLocales> | PickupLocales>, Locales = Locale extends GeneratedLocale ? GeneratedLocale : OptionLocale extends Locale ? IsNever extends true ? Locale : ResourceLocales : OptionLocale | ResourceLocales> extends ComposerCustom -``` - -**Details** - -This is the interface for being used for Vue 3 Composition API. - -### availableLocales - -**Signature:** - -```typescript -readonly availableLocales: ComputedRef; -``` - -**Details** - -The list of available locales in `messages` in lexical order. - -### d - -Datetime formatting - -**Signature:** - -```typescript -d: ComposerDateTimeFormatting< - DateTimeFormats, - Locales, - RemoveIndexSignature<{ - [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K] - }> -> -``` - -**Details** - -About details functions, See the [ComposerDateTimeFormatting](composition#composerdatetimeformatting) - -### datetimeFormats - -**Signature:** - -```typescript -readonly datetimeFormats: ComputedRef<{ - [K in keyof DateTimeFormats]: DateTimeFormats[K]; - }>; -``` - -**Details** - -The datetime formats of localization. - -**See Also** - -- [Datetime Formatting](../../guide/essentials/datetime) - -### escapeParameter - -**Signature:** - -```typescript -escapeParameter: boolean -``` - -**Details** - -Whether interpolation parameters are escaped before the message is translated. - -**See Also** - -- [HTML Message](../../guide/essentials/syntax#html-message) - -### fallbackFormat - -**Signature:** - -```typescript -fallbackFormat: boolean -``` - -**Details** - -Whether suppress warnings when falling back to either `fallbackLocale` or root. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackLocale - -**Signature:** - -```typescript -fallbackLocale: WritableComputedRef> -``` - -**Details** - -The current fallback locales this Composer instance is using. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackRoot - -**Signature:** - -```typescript -fallbackRoot: boolean -``` - -**Details** - -Whether to fall back to root level (global scope) localization when localization fails. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackWarn - -**Signature:** - -```typescript -fallbackWarn: boolean | RegExp -``` - -**Details** - -Whether suppress fall back warnings when localization fails. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### id - -**Signature:** - -```typescript -id: number -``` - -**Details** - -Instance ID. - -### inheritLocale - -**Signature:** - -```typescript -inheritLocale: boolean -``` - -**Details** - -Whether inherit the root level locale to the component localization locale. - -**See Also** - -- [Local Scope](../../guide/essentials/scope#local-scope-2) - -### isGlobal - -**Signature:** - -```typescript -readonly isGlobal: boolean; -``` - -**Details** - -Whether this composer instance is global or not - -### locale - -**Signature:** - -```typescript -locale: WritableComputedRef -``` - -**Details** - -The current locale this Composer instance is using. - -If the locale contains a territory and a dialect, this locale contains an implicit fallback. - -**See Also** - -- [Scope and Locale Changing](../../guide/essentials/scope) - -### messages - -**Signature:** - -```typescript -readonly messages: ComputedRef<{ - [K in keyof Messages]: Messages[K]; - }>; -``` - -**Details** - -The locale messages of localization. - -**See Also** - -- [Getting Started](../../guide/essentials/started) - -### missingWarn - -**Signature:** - -```typescript -missingWarn: boolean | RegExp -``` - -**Details** - -Whether suppress warnings outputted when localization fails. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### modifiers - -**Signature:** - -```typescript -readonly modifiers: LinkedModifiers; -``` - -**Details** - -Custom Modifiers for linked messages. - -**See Also** - -- [Custom Modifiers](../../guide/essentials/syntax#custom-modifiers) - -### n - -Number Formatting - -**Signature:** - -```typescript -n: ComposerNumberFormatting< - NumberFormats, - Locales, - RemoveIndexSignature<{ - [K in keyof DefineNumberFormat]: DefineNumberFormat[K] - }> -> -``` - -**Details** - -About details functions, See the [ComposerNumberFormatting](composition#composernumberformatting) - -### numberFormats - -**Signature:** - -```typescript -readonly numberFormats: ComputedRef<{ - [K in keyof NumberFormats]: NumberFormats[K]; - }>; -``` - -**Details** - -The number formats of localization. - -**See Also** - -- [Number Formatting](../../guide/essentials/number) - -### pluralRules - -**Signature:** - -```typescript -readonly pluralRules: PluralizationRules; -``` - -**Details** - -A set of rules for word pluralization - -**See Also** - -- [Custom Pluralization](../../guide/essentials/pluralization#custom-pluralization) - -### rt - -Resolve locale message translation - -**Signature:** - -```typescript -rt: ComposerResolveLocaleMessageTranslation -``` - -**Details** - -About details functions, See the [ComposerResolveLocaleMessageTranslation](composition#composerresolvelocalemessagetranslation) - -### t - -Locale message translation - -**Signature:** - -```typescript -t: ComposerTranslation< - Messages, - Locales, - RemoveIndexSignature<{ - [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K] - }> -> -``` - -**Details** - -About details functions, See the [ComposerTranslation](composition#composertranslation) - -### warnHtmlMessage - -**Signature:** - -```typescript -warnHtmlMessage: boolean -``` - -**Details** - -Whether to allow the use locale messages of HTML formatting. - -If you set `false`, will check the locale messages on the Composer instance. - -If you are specified `true`, a warning will be output at console. - -**See Also** - -- [HTML Message](../../guide/essentials/syntax#html-message) -- [Change `warnHtmlInMessage` option default value](../../guide/migration/breaking#change-warnhtmlinmessage-option-default-value) - -### getDateTimeFormat(locale) - -Get datetime format - -**Signature:** - -```typescript -getDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K]; - }> : NonNullable[Locale] : DateTimeSchema>(locale: LocaleSchema | Locale): Return; -``` - -#### Type Parameters - -| Parameter | Description | -| -------------- | ------------------------------------------- | -| DateTimeSchema | The datetime format schema, default `never` | - -**Details** - -get datetime format from Composer instance [datetimeFormats](composition#datetimeformats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | --------------- | -| locale | LocaleSchema | Locale | A target locale | - -#### Returns - -Datetime format - -### getLocaleMessage(locale) - -Get locale message - -**Signature:** - -```typescript -getLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; - }> : NonNullable[Locale] : MessageSchema>(locale: LocaleSchema | Locale): Return; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------- | ------------------------------------------ | -| MessageSchema | The locale message schema, default `never` | - -**Details** - -get locale message from Composer instance [messages](composition#messages). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | --------------- | -| locale | LocaleSchema | Locale | A target locale | - -#### Returns - -Locale messages - -### getMissingHandler() - -Get missing handler - -**Signature:** - -```typescript -getMissingHandler(): MissingHandler | null; -``` - -**See Also** - -- [missing](composition#missing) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ---- | ----------- | - -#### Returns - -[MissingHandler](composition#missinghandler) - -### getNumberFormat(locale) - -Get number format - -**Signature:** - -```typescript -getNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Return = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineNumberFormat]: DefineNumberFormat[K]; - }> : NonNullable[Locale] : NumberSchema>(locale: LocaleSchema | Locale): Return; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------ | ----------------------------------------- | -| NumberSchema | The number format schema, default `never` | - -**Details** - -get number format from Composer instance [numberFormats](composition#numberFormats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | --------------- | -| locale | LocaleSchema | Locale | A target locale | - -#### Returns - -Number format - -### getPostTranslationHandler() - -Get post translation handler - -**Signature:** - -```typescript -getPostTranslationHandler(): PostTranslationHandler | null; -``` - -**See Also** - -- [missing](composition#posttranslation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ---- | ----------- | - -#### Returns - -### mergeDateTimeFormat(locale, format) - -Merge datetime format - -**Signature:** - -```typescript -mergeDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Formats = IsNever extends true ? Record : DateTimeSchema>(locale: LocaleSchema | Locale, format: Formats): void; -``` - -#### Type Parameters - -| Parameter | Description | -| -------------- | ------------------------------------------- | -| DateTimeSchema | The datetime format schema, default `never` | - -**Details** - -Merge datetime format to Composer instance [datetimeFormats](composition#datetimeformats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ------------------------ | -| locale | LocaleSchema | Locale | A target locale | -| format | Formats | A target datetime format | - -### mergeLocaleMessage(locale, message) - -Merge locale message - -**Signature:** - -```typescript -mergeLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Message = IsNever extends true ? Record : MessageSchema>(locale: LocaleSchema | Locale, message: Message): void; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------- | ------------------------------------------ | -| MessageSchema | The locale message schema, default `never` | - -**Details** - -Merge locale message to Composer instance [messages](composition#messages). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | --------------- | -| locale | LocaleSchema | Locale | A target locale | -| message | Message | A message | - -### mergeNumberFormat(locale, format) - -Merge number format - -**Signature:** - -```typescript -mergeNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, Formats = IsNever extends true ? Record : NumberSchema>(locale: LocaleSchema | Locale, format: Formats): void; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------ | ----------------------------------------- | -| NumberSchema | The number format schema, default `never` | - -**Details** - -Merge number format to Composer instance [numberFormats](composition#numberFormats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ---------------------- | -| locale | LocaleSchema | Locale | A target locale | -| format | Formats | A target number format | - -### setDateTimeFormat(locale, format) - -Set datetime format - -**Signature:** - -```typescript -setDateTimeFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, FormatsType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K]; - }> : NonNullable[Locale] : DateTimeSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void; -``` - -#### Type Parameters - -| Parameter | Description | -| -------------- | ------------------------------------------- | -| DateTimeSchema | The datetime format schema, default `never` | - -**Details** - -Set datetime format to Composer instance [datetimeFormats](composition#datetimeformats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ------------------------ | -| locale | LocaleSchema | Locale | A target locale | -| format | Formats | A target datetime format | - -### setLocaleMessage(locale, message) - -Set locale message - -**Signature:** - -```typescript -setLocaleMessage = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, MessageType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; - }> : NonNullable[Locale] : MessageSchema, Message extends MessageType = MessageType>(locale: LocaleSchema | Locale, message: Message): void; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------- | ------------------------------------------ | -| MessageSchema | The locale message schema, default `never` | - -**Details** - -Set locale message to Composer instance [messages](composition#messages). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | --------------- | -| locale | LocaleSchema | Locale | A target locale | -| message | Message | A message | - -### setMissingHandler(handler) - -Set missing handler - -**Signature:** - -```typescript -setMissingHandler(handler: MissingHandler | null): void; -``` - -**See Also** - -- [missing](composition#missing) - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ---------------------------------------------- | -| handler | MissingHandler | null | A [MissingHandler](composition#missinghandler) | - -### setNumberFormat(locale, format) - -Set number format - -**Signature:** - -```typescript -setNumberFormat = never, LocaleSchema extends string = string, Locale extends PickupLocales> = PickupLocales>, FormatsType = IsNever extends true ? IsEmptyObject extends true ? RemoveIndexSignature<{ - [K in keyof DefineNumberFormat]: DefineNumberFormat[K]; - }> : NonNullable[Locale] : NumberSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void; -``` - -#### Type Parameters - -| Parameter | Description | -| ------------ | ----------------------------------------- | -| NumberSchema | The number format schema, default `never` | - -**Details** - -Set number format to Composer instance [numberFormats](composition#numberFormats). - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ---------------------- | -| locale | LocaleSchema | Locale | A target locale | -| format | Formats | A target number format | - -### setPostTranslationHandler(handler) - -Set post translation handler - -**Signature:** - -```typescript -setPostTranslationHandler(handler: PostTranslationHandler | null): void; -``` - -**See Also** - -- [missing](composition#posttranslation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------------------------------------- | ----------- | -| handler | PostTranslationHandler<VueMessageType> | null | A | - -### te(key, locale) - -Translation locale message exist - -**Signature:** - -```typescript -te = PickupKeys>(key: Str | Key, locale?: Locales): boolean; -``` - -**Details** - -whether do exist locale message on Composer instance [messages](composition#messages). - -If you specified `locale`, check the locale messages of `locale`. - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------- | --------------------------------------------------------------- | -| key | Str | Key | A target locale message key | -| locale | Locales | A locale, it will be used over than global scope or local scope | - -#### Returns - -If found locale message, `true`, else `false`, Note that `false` is returned even if the value present in the key is not translatable, yet if `translateExistCompatible` is set to `true`, it will return `true` if the key is available, even if the value is not translatable. - -### tm(key) - -Locale messages getter - -**Signature:** - -```typescript -tm = PickupKeys, Locale extends PickupLocales> = PickupLocales>, Target = IsEmptyObject extends false ? NonNullable[Locale] : RemoveIndexSignature<{ - [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K]; - }>, Return = ResourceKeys extends ResourcePath ? ResourceValue : Record>(key: Key | ResourceKeys): Return; -``` - -**Details** - -If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. - -Based on the current `locale`, locale messages will be returned from Composer instance messages. - -If you change the `locale`, the locale messages returned will also correspond to the locale. - -If there are no locale messages for the given `key` in the composer instance messages, they will be returned with [fallbacking](../../guide/essentials/fallback). - -:::warning -You need to use `rt` for the locale message returned by `tm`. see the [rt](composition#rt-message) details. -::: - -#### Parameters - -| Parameter | Type | Description | -| --------- | ----------------------- | --------------------------- | -| key | Key | ResourceKeys | A target locale message key | - -Locale messages | - -**Examples** - -template block: - -```html -
- -
-``` - -script block: - -```js -import { defineComponent } from 'vue -import { useI18n } from 'vue-i18n' - -export default defineComponent({ - setup() { - const { rt, tm } = useI18n({ - messages: { - en: { - contents: [ - { - title: 'Title1', - // ... - paragraphs: [ - // ... - ] - } - ] - } - } - // ... - }) - // ... - return { ... , rt, tm } - } -}) -``` - -## ComposerAdditionalOptions - -Composer additional options for `useI18n` - -**Signature:** - -```typescript -export interface ComposerAdditionalOptions -``` - -**Details** - -`ComposerAdditionalOptions` is extend for [ComposerOptions](composition#composeroptions), so you can specify these options. - -**See Also** - -- [useI18n](composition#usei18n) - -### useScope - -## ComposerCustom - -The type custom definition of Composer - -**Signature:** - -```typescript -export interface ComposerCustom -``` - -**Details** - -The interface that can extend Composer. - -The type defined by 3rd party (e.g. nuxt/i18n) - -**Examples** - -```ts -// vue-i18n.d.ts (`.d.ts` file at your app) - -declare module 'vue-i18n' { - interface ComposerCustom { - localeCodes: string[] - } -} -``` - -## ComposerDateTimeFormatting - -Datetime formatting functions - -**Signature:** - -```typescript -export interface ComposerDateTimeFormatting = {}, Locales = 'en-US', DefinedDateTimeFormat extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? PickupFormatPathKeys<{ - [K in keyof DefinedDateTimeFormat]: DefinedDateTimeFormat[K]; -}> : never, M = IsEmptyObject extends false ? PickupFormatKeys : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> -``` - -**Details** - -This is the interface for [Composer](composition#composer) - -### (value: number | Date | string): string; - -Datetime formatting - -**Signature:** - -```typescript -(value: number | Date | string): string; -``` - -**Details** - -If this is used in a reactive context, it will re-evaluate once the locale changes. - -If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope datetime formats than global scope datetime formats. - -If not, then it’s formatted with global scope datetime formats. - -**See Also** - -- [Datetime formatting](../../guide/essentials/datetime) - -#### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------------- | --------------------------------------------------------------- | -| value | number | Date | string | A value, timestamp number or `Date` instance or ISO 8601 string | - -#### Returns - -Formatted value - -### (value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>): string; - -Datetime formatting - -**Signature:** - -```typescript -(value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions): string; -``` - -**Details** - -Overloaded `d`. About details, see the [call signature](composition#value-number-date-string-string) details. - -In this overloaded `d`, format in datetime format for a key registered in datetime formats. - -#### Parameters - -| Parameter | Type | Description | -| ------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| value | Value | A value, timestamp number or `Date` instance or ISO 8601 string | -| keyOrOptions | Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> | A key of datetime formats, or additional for datetime formatting | - -#### Returns - -Formatted value - -### (value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>, locale: Locales): string; - -Datetime formatting - -**Signature:** - -```typescript -(value: Value, keyOrOptions: Key | ResourceKeys | DateTimeOptions, locale: Locales): string; -``` - -**Details** - -Overloaded `d`. About details, see the [call signature](composition#value-number-date-string-string) details. - -In this overloaded `d`, format in datetime format for a key registered in datetime formats at target locale - -#### Parameters - -| Parameter | Type | Description | -| ------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| value | Value | A value, timestamp number or `Date` instance or ISO 8601 string | -| keyOrOptions | Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> | A key of datetime formats, or additional for datetime formatting | -| locale | Locales | A locale, it will be used over than global scope or local scope. | - -#### Returns - -Formatted value - -## ComposerNumberFormatting - -Number formatting functions - -**Signature:** - -```typescript -export interface ComposerNumberFormatting = {}, Locales = 'en-US', DefinedNumberFormat extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? PickupFormatPathKeys<{ - [K in keyof DefinedNumberFormat]: DefinedNumberFormat[K]; -}> : never, M = IsEmptyObject extends false ? PickupFormatKeys : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> -``` - -**Details** - -This is the interface for [Composer](composition#composer) - -### (value: number): string; - -Number Formatting - -**Signature:** - -```typescript -(value: number): string; -``` - -**Details** - -If this is used in a reactive context, it will re-evaluate once the locale changes. - -If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope datetime formats than global scope datetime formats. - -If not, then it’s formatted with global scope number formats. - -**See Also** - -- [Number formatting](../../guide/essentials/number) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------ | -------------- | -| value | number | A number value | - -#### Returns - -Formatted value - -### (value: number, keyOrOptions: Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>): PartType; - -Number Formatting - -**Signature:** - -```typescript -(value: number, keyOrOptions: Key | ResourceKeys | NumberOptions): PartType; -``` - -**Details** - -Overloaded `n`. About details, see the [call signature](composition#value-number-string) details. - -In this overloaded `n`, format in number format for a key registered in number formats. - -#### Parameters - -| Parameter | Type | Description | -| ------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -| value | number | A number value | -| keyOrOptions | Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> | A key of number formats, or additional for number formatting | - -#### Returns - -Formatted value - -### (value: number, keyOrOptions: Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>, locale: Locales): PartType; - -Number Formatting - -**Signature:** - -```typescript -(value: number, keyOrOptions: Key | ResourceKeys | NumberOptions, locale: Locales): PartType; -``` - -**Details** - -Overloaded `n`. About details, see the [call signature](composition#value-number-string) details. - -In this overloaded `n`, format in number format for a key registered in number formats at target locale. - -#### Parameters - -| Parameter | Type | Description | -| ------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -| value | number | A number value | -| keyOrOptions | Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> | A key of number formats, or additional for number formatting | -| locale | Locales | A locale, it will be used over than global scope or local scope. | - -#### Returns - -Formatted value - -## ComposerOptions - -Composer Options - -**Signature:** - -```typescript -export interface ComposerOptions = LocaleMessages, _DateTimeFormats extends DateTimeFormatsType = DateTimeFormatsType, _NumberFormats extends NumberFormatsType = NumberFormatsType> -``` - -**Details** - -This is options to create composer. - -### datetime - -### datetimeFormats - -### escapeParameter - -**Signature:** - -```typescript -escapeParameter?: boolean; -``` - -**Details** - -If `escapeParameter` is configured as true then interpolation parameters are escaped before the message is translated. - -This is useful when translation output is used in `v-html` and the translation resource contains html markup (e.g. around a user provided value). - -This usage pattern mostly occurs when passing precomputed text strings into UI components. - -The escape process involves replacing the following symbols with their respective HTML character entities: `<`, `>`, `"`, `'`. - -Setting `escapeParameter` as true should not break existing functionality but provides a safeguard against a subtle type of XSS attack vectors. - -**Default Value** - -`false` - -**See Also** - -- [HTML Message](../../guide/essentials/syntax#html-message) - -### fallbackFormat - -**Signature:** - -```typescript -fallbackFormat?: boolean; -``` - -**Details** - -Whether do template interpolation on translation keys when your language lacks a translation for a key. - -If `true`, skip writing templates for your "base" language; the keys are your templates. - -**Default Value** - -`false` - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackLocale - -**Signature:** - -```typescript -fallbackLocale?: FallbackLocale; -``` - -**Details** - -The locale of fallback localization. - -For more complex fallback definitions see fallback. - -**Default Value** - -The default `'en-US'` for the `locale` if it's not specified, or it's `locale` value - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackRoot - -**Signature:** - -```typescript -fallbackRoot?: boolean; -``` - -**Details** - -In the component localization, whether to fallback to root level (global scope) localization when localization fails. - -If `false`, it's not fallback to root. - -**Default Value** - -`true` - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### fallbackWarn - -**Signature:** - -```typescript -fallbackWarn?: boolean | RegExp; -``` - -**Details** - -Whether suppress warnings when falling back to either `fallbackLocale` or root. - -If `false`, suppress fall back warnings. - -If you use regular expression, you can suppress fallback warnings that it match with translation key (e.g. `t`). - -**Default Value** - -`true` - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### flatJson - -**Signature:** - -```typescript -flatJson?: boolean; -``` - -**Details** - -Allow use flat json messages or not - -**Default Value** - -`false` - -### inheritLocale - -**Signature:** - -```typescript -inheritLocale?: boolean; -``` - -**Details** - -Whether inheritance the root level locale to the component localization locale. - -If `false`, regardless of the root level locale, localize for each component locale. - -**Default Value** - -`true` - -**See Also** - -- [Local Scope](../../guide/essentials/scope#local-scope-2) - -### locale - -**Signature:** - -```typescript -locale?: Locale; -``` - -**Details** - -The locale of localization. - -If the locale contains a territory and a dialect, this locale contains an implicit fallback. - -**Default Value** - -`'en-US'` - -**See Also** - -- [Scope and Locale Changing](../../guide/essentials/scope) - -### message - -### messageCompiler - -**Signature:** - -```typescript -messageCompiler?: MessageCompiler; -``` - -**Details** - -A compiler for custom message format. - -If not specified, the vue-i18n default message compiler will be used. - -You will need to implement your own message compiler that returns Message Functions - -:::tip -:new: v9.3+ -::: - -:::warning -The Custom Message Format is an experimental feature. It may receive breaking changes or be removed in the future. -::: - -**Default Value** - -`undefined` - -**See Also** - -- [Custom Message Format](../../guide/advanced/format) - -**Examples** - -Here is an example of how to custom message compiler with `intl-messageformat` - -```js -import { createI18n } from 'vue-i18n' -import IntlMessageFormat from 'intl-messageformat' - -function messageCompiler(message, { locale, key, onError }) { - if (typeof message === 'string') { - // You can tune your message compiler performance more with your cache strategy or also memoization at here - const formatter = new IntlMessageFormat(message, locale) - return ctx => formatter.format(ctx.values) - } else { - // If you would like to support it for AST, - // You need to transform locale mesages such as `json`, `yaml`, etc. with the bundle plugin. - onError && onError(new Error('not support for AST')) - return () => key // return default with `key` - } -} - -// call with I18n option -const i18n = createI18n({ - locale: 'ja', - messageCompiler, // set your message compiler - messages: { - en: { - hello: 'hello world!', - greeting: 'hi, {name}!', - // ICU Message format - photo: `You have {numPhotos, plural, - =0 {no photos.} - =1 {one photo.} - other {# photos.} - }` - } - } -}) - -// the below your something to do ... -// ... -``` - -### messageResolver - -**Signature:** - -```typescript -messageResolver?: MessageResolver; -``` - -**Details** - -A message resolver to resolve [`messages`](composition#messages). - -If not specified, the vue-i18n internal message resolver will be used by default. - -You need to implement a message resolver yourself that supports the following requirements: - -- Resolve the message using the locale message of [`locale`](composition#locale) passed as the first argument of the message resolver, and the path passed as the second argument. - -- If the message could not be resolved, you need to return `null`. - -- If you will be returned `null`, the message resolver will also be called on fallback if [`fallbackLocale`](composition#fallbacklocale-2) is enabled, so the message will need to be resolved as well. - -The message resolver is called indirectly by the following APIs: - -- [`t`](composition#t-key) - -- [`te`](composition#te-key-locale) - -- [`tm`](composition#tm-key) - -- [Translation component](component#translation) - -:::tip -:new: v9.2+ -::: - -:::warning -If you use the message resolver, the [`flatJson`](composition#flatjson) setting will be ignored. That is, you need to resolve the flat JSON by yourself. -::: - -**Default Value** - -`undefined` - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -**Examples** - -Here is an example of how to set it up using your `createI18n`: - -```js -import { createI18n } from 'vue-i18n' - -// your message resolver -function messageResolver(obj, path) { - // simple message resolving! - const msg = obj[path] - return msg != null ? msg : null -} - -// call with I18n option -const i18n = createI18n({ - locale: 'ja', - messageResolver, // set your message resolver - messages: { - en: { ... }, - ja: { ... } - } -}) - -// the below your something to do ... -// ... -``` - -### messages - -### missing - -**Signature:** - -```typescript -missing?: MissingHandler; -``` - -**Details** - -A handler for localization missing. - -The handler gets called with the localization target locale, localization path key, the Vue instance and values. - -If missing handler is assigned, and occurred localization missing, it's not warned. - -**Default Value** - -`null` - -### missingWarn - -**Signature:** - -```typescript -missingWarn?: boolean | RegExp; -``` - -**Details** - -Whether suppress warnings outputted when localization fails. - -If `false`, suppress localization fail warnings. - -If you use regular expression, you can suppress localization fail warnings that it match with translation key (e.g. `t`). - -**Default Value** - -`true` - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### modifiers - -**Signature:** - -```typescript -modifiers?: LinkedModifiers; -``` - -**Details** - -Custom Modifiers for linked messages. - -**See Also** - -- [Custom Modifiers](../../guide/essentials/syntax#custom-modifiers) - -### number - -### numberFormats - -### pluralRules - -**Signature:** - -```typescript -pluralRules?: PluralizationRules; -``` - -**Details** - -A set of rules for word pluralization - -**Default Value** - -`{}` - -**See Also** - -- [Custom Pluralization](../../guide/essentials/pluralization#custom-pluralization) - -### postTranslation - -**Signature:** - -```typescript -postTranslation?: PostTranslationHandler; -``` - -**Details** - -A handler for post processing of translation. - -The handler gets after being called with the `t`. - -This handler is useful if you want to filter on translated text such as space trimming. - -**Default Value** - -`null` - -### warnHtmlMessage - -**Signature:** - -```typescript -warnHtmlMessage?: boolean; -``` - -**Details** - -Whether to allow the use locale messages of HTML formatting. - -See the warnHtmlMessage property. - -**Default Value** - -`'off'` - -**See Also** - -- [HTML Message](../../guide/essentials/syntax#html-message) -- [Change `warnHtmlInMessage` option default value](../../guide/migration/breaking#change-warnhtmlinmessage-option-default-value) - -## ComposerResolveLocaleMessageTranslation - -Resolve locale message translation functions - -**Signature:** - -```typescript -export interface ComposerResolveLocaleMessageTranslation -``` - -**Details** - -This is the interface for [Composer](composition#composer) - -### (message: MessageFunction<VueMessageType> | VueMessageType): string; - -Resolve locale message translation - -**Signature:** - -```typescript -(message: MessageFunction | VueMessageType): string; -``` - -**Details** - -If this is used in a reactive context, it will re-evaluate once the locale changes. - -If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. - -If not, then it’s translated with global scope locale messages. - -**See Also** - -- [Scope and Locale Changing](../../guide/essentials/scope) - -:::tip -The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. -::: - -:::warning -`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. -::: - -#### Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | - -#### Returns - -Translated message - -### (message: MessageFunction<VueMessageType> | VueMessageType, plural: number, options?: TranslateOptions<Locales>): string; - -Resolve locale message translation for plurals - -**Signature:** - -```typescript -(message: MessageFunction | VueMessageType, plural: number, options?: TranslateOptions): string; -``` - -**Details** - -Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. - -In this overloaded `rt`, return a pluralized translation message. - -**See Also** - -- [Pluralization](../../guide/essentials/pluralization) - -:::tip -The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. -::: - -:::warning -`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. -::: - -#### Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | -| plural | number | Which plural string to get. 1 returns the first one. | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -### (message: MessageFunction<VueMessageType> | VueMessageType, list: unknown[], options?: TranslateOptions<Locales>): string; - -Resolve locale message translation for list interpolations - -**Signature:** - -```typescript -(message: MessageFunction | VueMessageType, list: unknown[], options?: TranslateOptions): string; -``` - -**Details** - -Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. - -In this overloaded `rt`, return a pluralized translation message. - -**See Also** - -- [List interpolation](../../guide/essentials/syntax#list-interpolation) - -:::tip -The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. -::: - -:::warning -`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. -::: - -#### Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | -| list | unknown[] | A values of list interpolation. | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -### (message: MessageFunction<VueMessageType> | VueMessageType, named: NamedValue, options?: TranslateOptions<Locales>): string; - -Resolve locale message translation for named interpolations - -**Signature:** - -```typescript -(message: MessageFunction | VueMessageType, named: NamedValue, options?: TranslateOptions): string; -``` - -**Details** - -Overloaded `rt`. About details, see the [call signature](composition#message-messagefunction-message-message-string) details. - -In this overloaded `rt`, for each placeholder x, the locale messages should contain a `{x}` token. - -**See Also** - -- [Named interpolation](../../guide/essentials/syntax#named-interpolation) - -:::tip -The use-case for `rt` is for programmatic locale messages translation with using `tm`, `v-for`, javascript `for` statement. -::: - -:::warning -`rt` differs from `t` in that it processes the locale message directly, not the key of the locale message. There is no internal fallback with `rt`. You need to understand and use the structure of the locale messge returned by `tm`. -::: - -#### Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| message | MessageFunction<VueMessageType> | VueMessageType | A target locale message to be resolved. You will need to specify the locale message returned by `tm`. | -| named | NamedValue | A values of named interpolation. | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -## ComposerTranslation - -Locale message translation functions - -**Signature:** - -```typescript -export interface ComposerTranslation = {}, Locales = 'en-US', DefinedLocaleMessage extends RemovedIndexResources = RemovedIndexResources, C = IsEmptyObject extends false ? JsonPaths<{ - [K in keyof DefinedLocaleMessage]: DefinedLocaleMessage[K]; -}> : never, M = IsEmptyObject extends false ? TranslationsPaths : never, ResourceKeys extends C | M = IsNever extends false ? IsNever extends false ? C | M : C : IsNever extends false ? M : never> -``` - -**Details** - -This is the interface for [Composer](composition#composer) - -### (key: Key | ResourceKeys | number): string; - -Locale message translation - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number): string; -``` - -**Details** - -If this is used in a reactive context, it will re-evaluate once the locale changes. - -If [UseI18nScope](general#usei18nscope) `'local'` or Some [UseI18nOptions](composition#usei18noptions) are specified at `useI18n`, it’s translated in preferentially local scope locale messages than global scope locale messages. - -If not, then it’s translated with global scope locale messages. - -**See Also** - -- [Scope and Locale Changing](../../guide/essentials/scope) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | --------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, named: NamedValue): string; - -Locale message translation for named interpolations - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, named: NamedValue): string; -``` - -**Details** - -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. - -**See Also** - -- [Named interpolation](../../guide/essentials/syntax#named-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| named | NamedValue | A values of named interpolation | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, named: NamedValue, plural: number): string; - -Locale message translation for named interpolations and plurals - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, named: NamedValue, plural: number): string; -``` - -**Details** - -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, and return a pluralized translation message. - -**See Also** - -- [Pluralization](../../guide/essentials/pluralization) -- [Named interpolation](../../guide/essentials/syntax#named-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ---------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| named | NamedValue | A values of named interpolation | -| plural | number | Which plural string to get. 1 returns the first one. | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string; - -Locale message translation for named interpolations and plurals - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string; -``` - -**Details** - -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, and if no translation was found, return a default message. - -**See Also** - -- [Named interpolation](../../guide/essentials/syntax#named-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| ---------- | ------------------------------------- | ------------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| named | NamedValue | A values of named interpolation | -| defaultMsg | string | A default message to return if no translation was found | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions<Locales>): string; - -Locale message translation for named interpolations - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions): string; -``` - -**Details** - -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 . - -**See Also** - -- [Named interpolation](../../guide/essentials/syntax#named-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| named | NamedValue | A values of named interpolation | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, plural: number): string; - -Locale message translation for plurals - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, plural: number): string; -``` - -**Details** - -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. - -**See Also** - -- [Pluralization](../../guide/essentials/pluralization) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ---------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| plural | number | Which plural string to get. 1 returns the first one. | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, plural: number, options: TranslateOptions<Locales>): string; - -Locale message translation for plurals - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, plural: number, options: TranslateOptions): string; -``` - -**Details** - -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. - -About details of options, see the . - -**See Also** - -- [Pluralization](../../guide/essentials/pluralization) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ---------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| plural | number | Which plural string to get. 1 returns the first one. | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, defaultMsg: string): string; - -Locale message translation for missing default message - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, defaultMsg: string): string; -``` - -**Details** - -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. - -#### Parameters - -| Parameter | Type | Description | -| ---------- | ------------------------------------- | ------------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| defaultMsg | string | A default message to return if no translation was found | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions<Locales>): string; - -Locale message translation for missing default message - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions): string; -``` - -**Details** - -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. - -About details of options, see the . - -#### Parameters - -| Parameter | Type | Description | -| ---------- | ------------------------------------- | ------------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| defaultMsg | string | A default message to return if no translation was found | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, list: unknown[]): string; - -Locale message translation for list interpolations - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, list: unknown[]): string; -``` - -**Details** - -Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. - -**See Also** - -- [List interpolation](../../guide/essentials/syntax#list-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ------------------------------ | -| key | Key | ResourceKeys | number | A target locale message key | -| list | unknown[] | A values of list interpolation | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, list: unknown[], plural: number): string; - -Locale message translation for list interpolations and plurals - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, list: unknown[], plural: number): string; -``` - -**Details** - -Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. - -**See Also** - -- [Pluralization](../../guide/essentials/pluralization) -- [List interpolation](../../guide/essentials/syntax#list-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ---------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| list | unknown[] | A values of list interpolation | -| plural | number | Which plural string to get. 1 returns the first one. | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, list: unknown[], defaultMsg: string): string; - -Locale message translation for list interpolations and missing default message - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, list: unknown[], defaultMsg: string): string; -``` - -**Details** - -Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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. - -**See Also** - -- [List interpolation](../../guide/essentials/syntax#list-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| ---------- | ------------------------------------- | ------------------------------------------------------- | -| key | Key | ResourceKeys | number | A target locale message key | -| list | unknown[] | A values of list interpolation | -| defaultMsg | string | A default message to return if no translation was found | - -#### Returns - -Translated message - -### (key: Key | ResourceKeys | number, list: unknown[], options: TranslateOptions<Locales>): string; - -Locale message translation for list interpolations - -**Signature:** - -```typescript -(key: Key | ResourceKeys | number, list: unknown[], options: TranslateOptions): string; -``` - -**Details** - -Overloaded `t`. About details, see the [call signature](composition#key-key-resourcekeys-number-string) 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 . - -**See Also** - -- [List interpolation](../../guide/essentials/syntax#list-interpolation) - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------- | ------------------------------ | -| key | Key | ResourceKeys | number | A target locale message key | -| list | unknown[] | A values of list interpolation | -| options | TranslateOptions<Locales> | Additional for translation | - -#### Returns - -Translated message - -## MissingHandler - -**Signature:** - -```typescript -export type MissingHandler = ( - locale: Locale, - key: Path, - instance?: ComponentInternalInstance, - type?: string -) => string | void -``` - -## useI18n - -Use Composition API for Vue I18n - -**Signature:** - -```typescript -export declare function useI18n< - Schema = DefaultLocaleMessageSchema, - Locales = 'en-US', - Options extends UseI18nOptions< - SchemaParams, - LocaleParams - > = UseI18nOptions< - SchemaParams, - LocaleParams - > ->( - options?: Options -): Composer< - NonNullable, - NonNullable, - NonNullable, - NonNullable -> -``` - -### Type Parameters - -| Parameter | Description | -| --------- | ----------------------------------------------------------------------------- | -| Schema | The i18n resources (messages, datetimeFormats, numberFormats) schema, default | -| Locales | The locales of i18n resource schema, default `en-US` | - -**Details** - -This function is mainly used by `setup`. - -If options are specified, Composer instance is created for each component and you can be localized on the component. - -If options are not specified, you can be localized using the global Composer. - -### Parameters - -| Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------------ | -| options | Options | An options, see [UseI18nOptions](composition#usei18noptions) | - -### Returns - -[Composer](composition#composer) instance - -**Examples** - -case: Component resource base localization - -```html - - - -``` - -## UseI18nOptions - -I18n Options for `useI18n` - -**Signature:** - -```typescript -export type UseI18nOptions< - Schema extends { - message?: unknown - datetime?: unknown - number?: unknown - } = { - message: DefaultLocaleMessageSchema - datetime: DefaultDateTimeFormatSchema - number: DefaultNumberFormatSchema - }, - Locales extends - | { - messages: unknown - datetimeFormats: unknown - numberFormats: unknown - } - | string = Locale, - Options extends ComposerOptions = ComposerOptions< - Schema, - Locales - > -> = ComposerAdditionalOptions & Options -``` - -**Details** - -`UseI18nOptions` is inherited [ComposerAdditionalOptions](composition#composeradditionaloptions) and [ComposerOptions](composition#composeroptions), so you can specify these options. - -**See Also** - -- [useI18n](composition#usei18n) - -## VueMessageType - -**Signature:** - -```typescript -export type VueMessageType = string | ResourceNode | VNode -``` diff --git a/v11/general.md b/v11/general.md deleted file mode 100644 index 6d440cfd1..000000000 --- a/v11/general.md +++ /dev/null @@ -1,1313 +0,0 @@ -# General - -## createI18n - -Vue I18n factory - -**Signature:** - -```typescript -export declare function createI18n< - Schema extends object = DefaultLocaleMessageSchema, - Locales extends string | object = 'en-US', - Options extends I18nOptions< - SchemaParams, - LocaleParams - > = I18nOptions, LocaleParams>, - Messages extends Record = NonNullable< - Options['messages'] - > extends Record - ? NonNullable - : {}, - DateTimeFormats extends Record = NonNullable< - Options['datetimeFormats'] - > extends Record - ? NonNullable - : {}, - NumberFormats extends Record = NonNullable< - Options['numberFormats'] - > extends Record - ? NonNullable - : {}, - OptionLocale = Options['locale'] extends string ? Options['locale'] : Locale ->( - options: Options -): I18n -``` - -### Type Parameters - -| Parameter | Description | -| --------- | ----------------------------------------------------------------------------- | -| Schema | The i18n resources (messages, datetimeFormats, numberFormats) schema, default | -| Locales | The locales of i18n resource schema, default `en-US` | - -**See Also** - -- [Getting Started](../../guide/essentials/started) -- [Composition API](../../guide/advanced/composition) - -### Parameters - -| Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | -| options | Options | An options, see the [I18nOptions](general#i18noptions) | - -### Returns - -[I18n](general#i18n) instance - -**Examples** - -```js -import { createApp } from 'vue' -import { createI18n, useI18n } from 'vue-i18n' - -// call with I18n option -const i18n = createI18n({ - locale: 'ja', - messages: { - en: { ... }, - ja: { ... } - } -}) - -const App = { - setup() { - // ... - const { t } = useI18n({ ... }) - return { ... , t } - } -} - -const app = createApp(App) - -// install! -app.use(i18n) -app.mount('#app') -``` - -## DefineDateTimeFormat - -The type definition of datetime format - -**Signature:** - -```typescript -export interface DefineDateTimeFormat extends DateTimeFormat -``` - -**Details** - -The typealias is used to strictly define the type of the Datetime format. - -The type defined by this can be used in the global scope. - -**Examples** - -```ts -// type.d.ts (`.d.ts` file at your app) -import { DefineDateTimeFormat } from 'vue-i18n' - -declare module 'vue-i18n' { - export interface DefineDateTimeFormat { - short: { - hour: 'numeric' - timezone: string - } - } -} -``` - -## DefineLocaleMessage - -The type definition of Locale Message - -**Signature:** - -```typescript -export interface DefineLocaleMessage extends LocaleMessage -``` - -**Details** - -The typealias is used to strictly define the type of the Locale message. - -The type defined by this can be used in the global scope. - -**Examples** - -```ts -// type.d.ts (`.d.ts` file at your app) -import { DefineLocaleMessage } from 'vue-i18n' - -declare module 'vue-i18n' { - export interface DefineLocaleMessage { - title: string - menu: { - login: string - } - } -} -``` - -## DefineNumberFormat - -The type definition of number format - -**Signature:** - -```typescript -export interface DefineNumberFormat extends NumberFormat -``` - -**Details** - -The typealias is used to strictly define the type of the Number format. - -The type defined by this can be used in the global scope. - -**Examples** - -```ts -// type.d.ts (`.d.ts` file at your app) -import { DefineNumberFormat } from 'vue-i18n' - -declare module 'vue-i18n' { - export interface DefineNumberFormat { - currency: { - style: 'currency' - currencyDisplay: 'symbol' - currency: string - } - } -} -``` - -## ExportedGlobalComposer - -Exported global composer instance - -**Signature:** - -```typescript -export interface ExportedGlobalComposer -``` - -**Details** - -This interface is the [global composer](general#global) that is provided interface that is injected into each component with `app.config.globalProperties`. - -### availableLocales - -Available locales - -**Signature:** - -```typescript -readonly availableLocales: Locale[]; -``` - -**Details** - -This property is proxy-like property for `Composer#availableLocales`. About details, see the [Composer#availableLocales](composition#availablelocales) - -### fallbackLocale - -Fallback locale - -**Signature:** - -```typescript -fallbackLocale: FallbackLocale -``` - -**Details** - -This property is proxy-like property for `Composer#fallbackLocale`. About details, see the [Composer#fallbackLocale](composition#fallbacklocale) - -### locale - -Locale - -**Signature:** - -```typescript -locale: Locale -``` - -**Details** - -This property is proxy-like property for `Composer#locale`. About details, see the [Composer#locale](composition#locale) - -## I18n - -I18n instance - -**Signature:** - -```typescript -export interface I18n = {}, DateTimeFormats extends Record = {}, NumberFormats extends Record = {}, OptionLocale = Locale> -``` - -**Details** - -The instance required for installation as the Vue plugin - -### global - -The property accessible to the global Composer instance - -An instance of this property is **global scope\***. - -**Signature:** - -```typescript -readonly global: Composer; -``` - -### dispose() - -Release global scope resource - -**Signature:** - -```typescript -dispose(): void; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ---- | ----------- | - -### install(app, options) - -Install entry point - -**Signature:** - -```typescript -install(app: App, ...options: unknown[]): void; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | --------- | ------------------------- | -| app | App | A target Vue app instance | -| options | unknown[] | An install options | - -## I18nAdditionalOptions - -I18n Additional Options - -**Signature:** - -```typescript -export interface I18nAdditionalOptions -``` - -**Details** - -Specific options for - -### globalInjection - -Whether to inject global properties & functions into for each component. - -**Signature:** - -```typescript -globalInjection?: boolean; -``` - -**Details** - -If set to `true`, then properties and methods prefixed with `$` are injected into Vue Component. - -**Default Value** - -`true` - -**See Also** - -- [Implicit with injected properties and functions](../../guide/advanced/composition#implicit-with-injected-properties-and-functions) -- [ComponentCustomProperties](injection#componentcustomproperties) - -## I18nOptions - -I18n Options for `createI18n` - -**Signature:** - -```typescript -export type I18nOptions< - Schema extends { - message?: unknown - datetime?: unknown - number?: unknown - } = { - message: DefaultLocaleMessageSchema - datetime: DefaultDateTimeFormatSchema - number: DefaultNumberFormatSchema - }, - Locales extends - | { - messages: unknown - datetimeFormats: unknown - numberFormats: unknown - } - | string = Locale, - Options = ComposerOptions -> = I18nAdditionalOptions & Options -``` - -## I18nPluginOptions - -Vue I18n plugin options - -**Signature:** - -```typescript -export interface I18nPluginOptions -``` - -**Details** - -An options specified when installing Vue I18n as Vue plugin with using `app.use`. - -### globalInstall - -Whether to globally install the components that is offered by Vue I18n - -**Signature:** - -```typescript -globalInstall?: boolean; -``` - -**Details** - -If this option is enabled, the components will be installed globally at `app.use` time. - -If you want to install manually in the `import` syntax, you can set it to `false` to install when needed. - -**Default Value** - -`true` - -## I18nScope - -I18n Scope - -**Signature:** - -```typescript -export type I18nScope = 'local' | 'parent' | 'global' -``` - -**See Also** - -- [ComposerAdditionalOptions#useScope](composition#usescope) -- [useI18n](composition#usei18n) - -## VERSION - -Vue I18n Version - -**Signature:** - -```typescript -VERSION: string -``` - -**Details** - -Semver format. Same format as the package.json `version` field. - -## DateTimeOptions - -DateTime options - -**Signature:** - -```typescript -export interface DateTimeOptions extends Intl.DateTimeFormatOptions, LocaleOptions -``` - -**Details** - -Options for Datetime formatting API - -### fallbackWarn - -**Signature:** - -```typescript -fallbackWarn?: boolean; -``` - -**Details** - -Whether do resolve on format keys when your language lacks a formatting for a key - -### key - -**Signature:** - -```typescript -key?: Key; -``` - -**Details** - -The target format key - -### missingWarn - -**Signature:** - -```typescript -missingWarn?: boolean; -``` - -**Details** - -Whether suppress warnings outputted when localization fails - -### part - -**Signature:** - -```typescript -part?: boolean; -``` - -**Details** - -Whether to use [Intel.DateTimeFormat#formatToParts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts) - -## DefineCoreLocaleMessage - -The type definition of Locale Message for `@intlify/core-base` package - -**Signature:** - -```typescript -export interface DefineCoreLocaleMessage extends LocaleMessage -``` - -**Details** - -The typealias is used to strictly define the type of the Locale message. - -**Examples** - -```ts -// type.d.ts (`.d.ts` file at your app) -import { DefineCoreLocaleMessage } from '@intlify/core-base' - -declare module '@intlify/core-base' { - export interface DefineCoreLocaleMessage { - title: string - menu: { - login: string - } - } -} -``` - -## FallbackLocale - -**Signature:** - -```typescript -export type FallbackLocale = - | Locale - | Locale[] - | { - [locale in string]: Locale[] - } - | false -``` - -## fallbackWithLocaleChain - -Fallback with locale chain - -**Signature:** - -```typescript -export declare function fallbackWithLocaleChain( - ctx: CoreContext, - fallback: FallbackLocale, - start: Locale -): Locale[] -``` - -**Details** - -A fallback locale function implemented with a fallback chain algorithm. It's used in VueI18n as default. - -**See Also** - -- [Fallbacking](../../guide/essentials/fallback) - -### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ------------------------------------------- | -| ctx | CoreContext<Message> | A [context](#corecontext) | -| fallback | FallbackLocale | A [fallback locale](general#fallbacklocale) | -| start | Locale | A starting [locale](general#locale) | - -### Returns - -Fallback locales - -## fallbackWithSimple - -Fallback with simple implemenation - -**Signature:** - -```typescript -export declare function fallbackWithSimple( - ctx: CoreContext, - fallback: FallbackLocale, - start: Locale -): Locale[] -``` - -**Details** - -A fallback locale function implemented with a simple fallback algorithm. - -Basically, it returns the value as specified in the `fallbackLocale` props, and is processed with the fallback inside intlify. - -### Parameters - -| Parameter | Type | Description | -| --------- | -------------------------- | ------------------------------------------- | -| ctx | CoreContext<Message> | A [context](#corecontext) | -| fallback | FallbackLocale | A [fallback locale](general#fallbacklocale) | -| start | Locale | A starting [locale](general#locale) | - -### Returns - -Fallback locales - -## LinkedModifiers - -**Signature:** - -```typescript -export type LinkedModifiers = { - [key: string]: LinkedModify -} -``` - -## Locale - -**Signature:** - -```typescript -export type Locale = - IsNever extends true ? string : GeneratedLocale -``` - -## LocaleDetector - -**Signature:** - -```typescript -export interface LocaleDetector -``` - -### resolvedOnce - -### (...args: Args): Locale | Promise<Locale>; - -## LocaleFallbacker - -The locale fallbacker - -**Signature:** - -```typescript -export type LocaleFallbacker = ( - ctx: CoreContext, - fallback: FallbackLocale, - start: Locale -) => Locale[] -``` - -## LocaleMessage - -**Signature:** - -```typescript -export type LocaleMessage = Record< - string, - LocaleMessageValue -> -``` - -## LocaleMessageDictionary - -**Signature:** - -```typescript -export type LocaleMessageDictionary = { - [K in keyof T]: LocaleMessageType -} -``` - -## LocaleMessages - -**Signature:** - -```typescript -export type LocaleMessages< - Schema, - Locales = Locale, - Message = string -> = LocaleRecord, Schema> -``` - -## LocaleMessageType - -**Signature:** - -```typescript -export type LocaleMessageType = T extends string - ? string - : T extends () => Promise - ? LocaleMessageDictionary - : T extends (...args: infer Arguments) => any - ? (...args: Arguments) => ReturnType - : T extends Record - ? LocaleMessageDictionary - : T extends Array - ? { - [K in keyof T]: T[K] - } - : T -``` - -## LocaleMessageValue - -**Signature:** - -```typescript -export type LocaleMessageValue = - | LocaleMessageDictionary - | string -``` - -## LocaleOptions - -**Signature:** - -```typescript -export interface LocaleOptions -``` - -### locale - -**Signature:** - -```typescript -locale?: Locales | LocaleDetector; -``` - -**Details** - -The locale of localization - -## MessageCompiler - -The message compiler - -**Signature:** - -```typescript -export type MessageCompiler< - Message = string, - MessageSource = string | ResourceNode -> = ( - message: MessageSource, - context: MessageCompilerContext -) => MessageFunction -``` - -## MessageCompilerContext - -The context that will pass the message compiler. - -**Signature:** - -```typescript -export type MessageCompilerContext = Pick< - CompileOptions, - 'onError' | 'onCacheKey' -> & { - warnHtmlMessage?: boolean - key: string - locale: Locale -} -``` - -## MessageContext - -The message context. - -**Signature:** - -```typescript -export interface MessageContext -``` - -### type - -The message type to be handled by the message function. - -**Signature:** - -```typescript -type: string -``` - -**Details** - -Usually `text`, you need to return **string** in message function. - -### values - -The message values. - -**Signature:** - -```typescript -values: Record -``` - -**Details** - -The message values are the argument values passed from translation function, such as `$t`, `t`, or `translate`. - -**Examples** - -vue-i18n `$t` (or `t`) case: - -```html -

{{ $t('greeting', { name: 'DIO' }) }}

- -``` - -`@intlify/core` (`@intlify/core-base`) `translate` case: - -```js -translate(context, 'foo.bar', ['dio']) // `['dio']` is message values -``` - -### linked(key, modifier) - -Resolve linked message. - -**Signature:** - -```typescript -linked(key: Path, modifier?: string): MessageType; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------ | ------------- | -| key | Path | A message key | -| modifier | string | A modifier | - -#### Returns - -A resolve message. - -### linked(key, modifier, type) - -Overloaded `linked` - -**Signature:** - -```typescript -linked(key: Path, modifier?: string, type?: string): MessageType; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------ | -------------- | -| key | Path | A message key | -| modifier | string | A modifier | -| type | string | A message type | - -#### Returns - -A resolve message. - -### linked(key, optoins) - -Overloaded `linked` - -**Signature:** - -```typescript -linked(key: Path, optoins?: LinkedOptions): MessageType; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------------- | ----------------------------------- | -| key | Path | A message key | -| optoins | LinkedOptions | An [linked options](#linkedoptions) | - -#### Returns - -A resolve message. - -### list(index) - -Resolve message value from list. - -**Signature:** - -```typescript -list(index: number): unknown; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------ | --------------------------- | -| index | number | An index of message values. | - -#### Returns - -A resolved message value. - -**Examples** - -```js -const messages = { - en: { - greeting: ({ list }) => `hello, ${list(0)}!` - } -} -``` - -### named(key) - -Resolve message value from named. - -**Signature:** - -```typescript -named(key: string): unknown; -``` - -#### Parameters - -| Parameter | Type | Description | -| --------- | ------ | ----------------------- | -| key | string | A key of message value. | - -#### Returns - -A resolved message value. - -**Examples** - -```js -const messages = { - en: { - greeting: ({ named }) => `hello, ${named('name')}!` - } -} -``` - -### plural(messages) - -Resolve message with plural index. - -**Signature:** - -```typescript -plural(messages: T[]): T; -``` - -**Details** - -That's resolved with plural index with translation function. - -#### Parameters - -| Parameter | Type | Description | -| --------- | ---- | --------------------------------------------------------------------------- | -| messages | T[] | the messages, that is resolved with plural index with translation function. | - -#### Returns - -A resolved message. - -**Examples** - -```js -const messages = { - en: { - car: ({ plural }) => plural(['car', 'cars']), - apple: ({ plural, named }) => - plural(['no apples', 'one apple', `${named('count')} apples`]) - } -} -``` - -## MessageFunction - -The Message Function. - -**Signature:** - -```typescript -export type MessageFunction = - | MessageFunctionCallable - | MessageFunctionInternal -``` - -## MessageFunctionReturn - -**Signature:** - -```typescript -export type MessageFunctionReturn = T extends string - ? MessageType - : MessageType[] -``` - -## MessageResolver - -**Signature:** - -```typescript -export type MessageResolver = (obj: unknown, path: Path) => PathValue -``` - -## NamedValue - -**Signature:** - -```typescript -export type NamedValue = T & Record -``` - -## NumberOptions - -Number Options - -**Signature:** - -```typescript -export interface NumberOptions extends Intl.NumberFormatOptions, LocaleOptions -``` - -**Details** - -Options for Number formatting API - -### fallbackWarn - -**Signature:** - -```typescript -fallbackWarn?: boolean; -``` - -**Details** - -Whether do resolve on format keys when your language lacks a formatting for a key - -### key - -**Signature:** - -```typescript -key?: Key; -``` - -**Details** - -The target format key - -### missingWarn - -**Signature:** - -```typescript -missingWarn?: boolean; -``` - -**Details** - -Whether suppress warnings outputted when localization fails - -### part - -**Signature:** - -```typescript -part?: boolean; -``` - -**Details** - -Whether to use [Intel.NumberFormat#formatToParts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts) - -## Path - -**Signature:** - -```typescript -export type Path = string -``` - -## PathValue - -**Signature:** - -```typescript -export type PathValue = - | string - | number - | boolean - | Function - | null - | { - [key: string]: PathValue - } - | PathValue[] -``` - -## PluralizationRules - -**Signature:** - -```typescript -export type PluralizationRules = { - [locale: string]: PluralizationRule -} -``` - -## PostTranslationHandler - -**Signature:** - -```typescript -export type PostTranslationHandler = ( - translated: MessageFunctionReturn, - key: string -) => MessageFunctionReturn -``` - -## registerLocaleFallbacker - -Register the locale fallbacker - -**Signature:** - -```typescript -export declare function registerLocaleFallbacker( - fallbacker: LocaleFallbacker -): void -``` - -### Parameters - -| Parameter | Type | Description | -| ---------- | ---------------- | ------------------------------------------------------- | -| fallbacker | LocaleFallbacker | A [LocaleFallbacker](general#localefallbacker) function | - -## registerMessageResolver - -Register the message resolver - -**Signature:** - -```typescript -export declare function registerMessageResolver(resolver: MessageResolver): void -``` - -### Parameters - -| Parameter | Type | Description | -| --------- | --------------- | ----------------------------------------------------- | -| resolver | MessageResolver | A [MessageResolver](general#messageresolver) function | - -## resolveValue - -message resolver - -**Signature:** - -```typescript -export declare function resolveValue(obj: unknown, path: Path): PathValue -``` - -**Details** - -Resolves messages. messages with a hierarchical structure such as objects can be resolved. This resolver is used in VueI18n as default. - -### Parameters - -| Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | -| obj | unknown | A target object to be resolved with path | -| path | Path | A [path](general#path) to resolve the value of message | - -### Returns - -A resolved [path value](general#pathvalue) - -## resolveWithKeyValue - -key-value message resolver - -**Signature:** - -```typescript -export declare function resolveWithKeyValue(obj: unknown, path: Path): PathValue -``` - -**Details** - -Resolves messages with the key-value structure. Note that messages with a hierarchical structure such as objects cannot be resolved - -### Parameters - -| Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | -| obj | unknown | A target object to be resolved with path | -| path | Path | A [path](general#path) to resolve the value of message | - -### Returns - -A resolved [path value](general#pathvalue) - -## TranslateOptions - -Translate Options - -**Signature:** - -```typescript -export interface TranslateOptions extends LocaleOptions -``` - -**Details** - -Options for Translation API - -### default - -**Signature:** - -```typescript -default?: string | boolean; -``` - -**Details** - -Default message when is occurred translation missing - -### escapeParameter - -**Signature:** - -```typescript -escapeParameter?: boolean; -``` - -**Details** - -Whether do escape parameter for list or named interpolation values - -### fallbackWarn - -**Signature:** - -```typescript -fallbackWarn?: boolean; -``` - -**Details** - -Whether do template interpolation on translation keys when your language lacks a translation for a key - -### list - -**Signature:** - -```typescript -list?: unknown[]; -``` - -**Details** - -List interpolation - -### missingWarn - -**Signature:** - -```typescript -missingWarn?: boolean; -``` - -**Details** - -Whether suppress warnings outputted when localization fails - -### named - -**Signature:** - -```typescript -named?: NamedValue; -``` - -**Details** - -Named interpolation - -### plural - -**Signature:** - -```typescript -plural?: number; -``` - -**Details** - -Plulralzation choice number - -### resolvedMessage - -**Signature:** - -```typescript -resolvedMessage?: boolean; -``` - -**Details** - -Whether the message has been resolved From 93f1aa901cc9168ece303d1e1a8d03f5ad594704 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Tue, 17 Jun 2025 00:36:20 +0900 Subject: [PATCH 4/4] fix --- packages/vue-i18n-core/src/i18n.ts | 2 +- packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap | 2 -- packages/vue-i18n-core/test/i18n.test.ts | 4 ++-- 3 files changed, 3 insertions(+), 5 deletions(-) diff --git a/packages/vue-i18n-core/src/i18n.ts b/packages/vue-i18n-core/src/i18n.ts index 13e44194b..75cb6e39f 100644 --- a/packages/vue-i18n-core/src/i18n.ts +++ b/packages/vue-i18n-core/src/i18n.ts @@ -773,7 +773,7 @@ export function useI18n< i18nInternal.__setInstance(instance, composer) } else { - if (scope === 'local') { + if (__DEV__ && scope === 'local') { throw createI18nError(I18nErrorCodes.DUPLICATE_USE_I18N_CALLING) } } diff --git a/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap b/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap index f7712a7da..d2ba3da67 100644 --- a/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap +++ b/packages/vue-i18n-core/test/__snapshots__/i18n.test.ts.snap @@ -7,5 +7,3 @@ exports[`slot reactivity > composable > ja 1`] = `"

Root

hello!

Child

hello!

Sub Child

hello!

$t inside of slot

hello!

i18n-t inside of slot

hello!

"`; exports[`slot reactivity > legacy > ja 1`] = `"

Root

こんにちは!

Child

こんにちは!

Sub Child

こんにちは!

$t inside of slot

こんにちは!

i18n-t inside of slot

こんにちは!

"`; - -exports[`useI18n > Duplicate \`useI18n\` calling by local scope. Please don't call it on local scope 1`] = `"

Root

hi!

Duplicate \`useI18n\` calling by local scope. Please don't call it on local scope

"`; diff --git a/packages/vue-i18n-core/test/i18n.test.ts b/packages/vue-i18n-core/test/i18n.test.ts index f69ddbe47..9707cb07f 100644 --- a/packages/vue-i18n-core/test/i18n.test.ts +++ b/packages/vue-i18n-core/test/i18n.test.ts @@ -679,8 +679,8 @@ describe('useI18n', () => {

{{ error }}

` }) - const { html } = await mount(App, i18n as any) // eslint-disable-line @typescript-eslint/no-explicit-any - expect(html()).toMatchSnapshot() + await mount(App, i18n as any) // eslint-disable-line @typescript-eslint/no-explicit-any + expect(error).toBe(errorMessages[I18nErrorCodes.DUPLICATE_USE_I18N_CALLING]) }) })