组合式 API

Composer

Composer 接口

签名:

typescript

export interface Composer<Messages extends Record<string, any> = {}, DateTimeFormats extends Record<string, any> = {}, NumberFormats extends Record<string, any> = {}, OptionLocale = Locale, ResourceLocales = PickupLocales<NonNullable<Messages>> | PickupLocales<NonNullable<DateTimeFormats>> | PickupLocales<NonNullable<NumberFormats>>, Locales = Locale extends GeneratedLocale ? GeneratedLocale : OptionLocale extends Locale ? IsNever<ResourceLocales> extends true ? Locale : ResourceLocales : OptionLocale | ResourceLocales> extends ComposerCustom

详情

这是用于 Vue 3 组合式 API 的接口。

availableLocales

签名:

typescript

readonly availableLocales: ComputedRef<Locales[]>;

详情

messages 中可用语言环境的列表，按字母顺序排列。

d

日期时间格式化

签名:

typescript

d: ComposerDateTimeFormatting<DateTimeFormats, Locales, RemoveIndexSignature<{
        [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K];
    }>>;

详情

关于详细函数，请参见 ComposerDateTimeFormatting

datetimeFormats

签名:

typescript

readonly datetimeFormats: ComputedRef<{
        [K in keyof DateTimeFormats]: DateTimeFormats[K];
    }>;

详情

本地化的日期时间格式。

请参见:

日期时间格式化

escapeParameter

签名:

typescript

escapeParameter: boolean;

详情

是否在翻译消息前转义插值参数。

请参见:

HTML 消息

fallbackFormat

签名:

typescript

fallbackFormat: boolean;

详情

当回退到 fallbackLocale 或根目录时是否抑制警告。

请参见:

回退机制

fallbackLocale

签名:

typescript

fallbackLocale: WritableComputedRef<FallbackLocales<Locales>>;

详情

此 Composer 实例正在使用的当前回退语言环境。

请参见:

回退机制

fallbackRoot

签名:

typescript

fallbackRoot: boolean;

详情

当本地化失败时是否回退到根级别（全局作用域）本地化。

请参见:

回退机制

fallbackWarn

签名:

typescript

fallbackWarn: boolean | RegExp;

详情

当本地化失败时是否抑制回退警告。

请参见:

回退机制

id

签名:

typescript

id: number;

详情

实例 ID。

inheritLocale

签名:

typescript

inheritLocale: boolean;

详情

是否继承根级语言环境到组件本地化语言环境。

请参见:

局部作用域

isGlobal

签名:

typescript

readonly isGlobal: boolean;

详情

此 composer 实例是否为全局的

locale

签名:

typescript

locale: WritableComputedRef<Locales>;

详情

此 Composer 实例正在使用的当前语言环境。

如果语言环境包含地区和方言，则该语言环境包含隐式回退。

请参见:

作用域和语言环境更改

messages

签名:

typescript

readonly messages: ComputedRef<{
        [K in keyof Messages]: Messages[K];
    }>;

详情

本地化的语言环境消息。

请参见:

入门指南

missingWarn

签名:

typescript

missingWarn: boolean | RegExp;

详情

当本地化失败时是否抑制警告输出。

请参见:

回退机制

modifiers

签名:

typescript

readonly modifiers: LinkedModifiers<VueMessageType>;

详情

链接消息的自定义修饰符。

请参见:

自定义修饰符

n

数字格式化

签名:

typescript

n: ComposerNumberFormatting<NumberFormats, Locales, RemoveIndexSignature<{
        [K in keyof DefineNumberFormat]: DefineNumberFormat[K];
    }>>;

详情

关于详细函数，请参见 ComposerNumberFormatting

numberFormats

签名:

typescript

readonly numberFormats: ComputedRef<{
        [K in keyof NumberFormats]: NumberFormats[K];
    }>;

详情

本地化的数字格式。

请参见:

数字格式化

pluralRules

签名:

typescript

readonly pluralRules: PluralizationRules;

详情

单词复数规则集

请参见:

自定义复数

rt

解析语言环境消息翻译

签名:

typescript

rt: ComposerResolveLocaleMessageTranslation<Locales>;

详情

关于详细函数，请参见 ComposerResolveLocaleMessageTranslation

t

语言环境消息翻译

签名:

typescript

t: ComposerTranslation<Messages, Locales, RemoveIndexSignature<{
        [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K];
    }>>;

详情

关于详细函数，请参见 ComposerTranslation

warnHtmlMessage

签名:

typescript

warnHtmlMessage: boolean;

详情

是否允许使用 HTML 格式的语言环境消息。

如果设置了 false，将检查 Composer 实例中的语言环境消息。

如果设置了 true，将在控制台输出警告。

请参见:

getDateTimeFormat(locale)

获取日期时间格式

签名:

typescript

getDateTimeFormat<DateTimeSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<DateTimeFormats>> = PickupLocales<NonNullable<DateTimeFormats>>, Return = IsNever<DateTimeSchema> extends true ? IsEmptyObject<DateTimeFormats> extends true ? RemoveIndexSignature<{
        [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K];
    }> : NonNullable<DateTimeFormats>[Locale] : DateTimeSchema>(locale: LocaleSchema | Locale): Return;

类型参数

参数	描述
DateTimeSchema	日期时间格式模式，默认为 `never`

详情

从 Composer 实例获取日期时间格式。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境

返回值

日期时间格式

getLocaleMessage(locale)

获取语言环境消息

签名:

typescript

getLocaleMessage<MessageSchema extends LocaleMessage<VueMessageType> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<Messages>> = PickupLocales<NonNullable<Messages>>, Return = IsNever<MessageSchema> extends true ? IsEmptyObject<Messages> extends true ? RemoveIndexSignature<{
        [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K];
    }> : NonNullable<Messages>[Locale] : MessageSchema>(locale: LocaleSchema | Locale): Return;

类型参数

参数	描述
MessageSchema	语言环境消息模式，默认为 `never`

详情

从 Composer 实例获取语言环境消息。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境

返回值

语言环境消息

getMissingHandler()

获取缺失处理程序

签名:

typescript

getMissingHandler(): MissingHandler | null;

参数

参数	类型	描述

返回值

MissingHandler

getNumberFormat(locale)

获取数字格式

签名:

typescript

getNumberFormat<NumberSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<NumberFormats>> = PickupLocales<NonNullable<NumberFormats>>, Return = IsNever<NumberSchema> extends true ? IsEmptyObject<NumberFormats> extends true ? RemoveIndexSignature<{
        [K in keyof DefineNumberFormat]: DefineNumberFormat[K];
    }> : NonNullable<NumberFormats>[Locale] : NumberSchema>(locale: LocaleSchema | Locale): Return;

类型参数

参数	描述
NumberSchema	数字格式模式，默认为 `never`

详情

从 Composer 实例获取数字格式。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境

返回值

数字格式

getPostTranslationHandler()

获取后翻译处理程序

签名:

typescript

getPostTranslationHandler(): PostTranslationHandler<VueMessageType> | null;

参数

参数	类型	描述

返回值

mergeDateTimeFormat(locale, format)

合并日期时间格式

签名:

typescript

mergeDateTimeFormat<DateTimeSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<DateTimeFormats>> = PickupLocales<NonNullable<DateTimeFormats>>, Formats = IsNever<DateTimeSchema> extends true ? Record<string, any> : DateTimeSchema>(locale: LocaleSchema | Locale, format: Formats): void;

类型参数

参数	描述
DateTimeSchema	日期时间格式模式，默认为 `never`

详情

合并日期时间格式到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
format	Formats	目标日期时间格式

mergeLocaleMessage(locale, message)

合并语言环境消息

签名:

typescript

mergeLocaleMessage<MessageSchema extends LocaleMessage<VueMessageType> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<Messages>> = PickupLocales<NonNullable<Messages>>, Message = IsNever<MessageSchema> extends true ? Record<string, any> : MessageSchema>(locale: LocaleSchema | Locale, message: Message): void;

类型参数

参数	描述
MessageSchema	语言环境消息模式，默认为 `never`

详情

合并语言环境消息到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
message	Message	消息

mergeNumberFormat(locale, format)

合并数字格式

签名:

typescript

mergeNumberFormat<NumberSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<NumberFormats>> = PickupLocales<NonNullable<NumberFormats>>, Formats = IsNever<NumberSchema> extends true ? Record<string, any> : NumberSchema>(locale: LocaleSchema | Locale, format: Formats): void;

类型参数

参数	描述
NumberSchema	数字格式模式，默认为 `never`

详情

合并数字格式到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
format	Formats	目标数字格式

setDateTimeFormat(locale, format)

设置日期时间格式

签名:

typescript

setDateTimeFormat<DateTimeSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<DateTimeFormats>> = PickupLocales<NonNullable<DateTimeFormats>>, FormatsType = IsNever<DateTimeSchema> extends true ? IsEmptyObject<DateTimeFormats> extends true ? RemoveIndexSignature<{
        [K in keyof DefineDateTimeFormat]: DefineDateTimeFormat[K];
    }> : NonNullable<DateTimeFormats>[Locale] : DateTimeSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void;

类型参数

参数	描述
DateTimeSchema	日期时间格式模式，默认为 `never`

详情

将日期时间格式设置到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
format	Formats	目标日期时间格式

setLocaleMessage(locale, message)

设置语言环境消息

签名:

typescript

setLocaleMessage<MessageSchema extends LocaleMessage<VueMessageType> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<Messages>> = PickupLocales<NonNullable<Messages>>, MessageType = IsNever<MessageSchema> extends true ? IsEmptyObject<Messages> extends true ? RemoveIndexSignature<{
        [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K];
    }> : NonNullable<Messages>[Locale] : MessageSchema, Message extends MessageType = MessageType>(locale: LocaleSchema | Locale, message: Message): void;

类型参数

参数	描述
MessageSchema	语言环境消息模式，默认为 `never`

详情

将语言环境消息设置到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
message	Message	消息

setMissingHandler(handler)

设置缺失处理程序

签名:

typescript

setMissingHandler(handler: MissingHandler | null): void;

参数

参数	类型	描述
handler	MissingHandler \| null	一个 MissingHandler

setNumberFormat(locale, format)

设置数字格式

签名:

typescript

setNumberFormat<NumberSchema extends Record<string, any> = never, LocaleSchema extends string = string, Locale extends PickupLocales<NonNullable<NumberFormats>> = PickupLocales<NonNullable<NumberFormats>>, FormatsType = IsNever<NumberSchema> extends true ? IsEmptyObject<NumberFormats> extends true ? RemoveIndexSignature<{
        [K in keyof DefineNumberFormat]: DefineNumberFormat[K];
    }> : NonNullable<NumberFormats>[Locale] : NumberSchema, Formats extends FormatsType = FormatsType>(locale: LocaleSchema | Locale, format: Formats): void;

类型参数

参数	描述
NumberSchema	数字格式模式，默认为 `never`

详情

将数字格式设置到 Composer 实例。

参数

参数	类型	描述
locale	LocaleSchema \| Locale	目标语言环境
format	Formats	目标数字格式

setPostTranslationHandler(handler)

设置后翻译处理程序

签名:

typescript

setPostTranslationHandler(handler: PostTranslationHandler<VueMessageType> | null): void;

参数

参数	类型	描述
handler	PostTranslationHandler<VueMessageType> \| null	一个

te(key, locale)

翻译语言环境消息存在

签名:

typescript

te<Str extends string, Key extends PickupKeys<Messages> = PickupKeys<Messages>>(key: Str | Key, locale?: Locales): boolean;

详情

检查 Composer 实例中是否存在语言环境消息。

如果指定了 locale，则检查 locale 的语言环境消息。

参数

参数	类型	描述
key	Str \| Key	目标语言环境消息键
locale	Locales	将用于覆盖全局作用域或局部作用域的语言环境

返回值

如果找到语言环境消息返回 true，否则返回 false。注意即使键值存在但不可翻译也会返回 false，但如果设置了 translateExistCompatible 为 true，即使键值不可翻译也会返回 true。

tm(key)

语言环境消息获取器

签名:

typescript

tm<Key extends string, ResourceKeys extends PickupKeys<Messages> = PickupKeys<Messages>, Locale extends PickupLocales<NonNullable<Messages>> = PickupLocales<NonNullable<Messages>>, Target = IsEmptyObject<Messages> extends false ? NonNullable<Messages>[Locale] : RemoveIndexSignature<{
        [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K];
    }>, Return = ResourceKeys extends ResourcePath<Target> ? ResourceValue<Target, ResourceKeys> : Record<string, any>>(key: Key | ResourceKeys): Return;

详情

如果 I18nScope 设置为 'local' 或在 useI18n 中指定了某些 UseI18nOptions，它会优先在局部作用域语言环境消息中翻译，而不是全局作用域语言环境消息。

根据当前 locale，从 Composer 实例消息中返回语言环境消息。

如果更改了 locale，返回的语言环境消息也将对应该语言环境。

如果 Composer 实例消息中没有给定 key 的语言环境消息，则会通过回退机制进行回退。

[!WARNING] 需要使用 rt 处理 tm 返回的语言环境消息。请参见 rt 的详细信息。

参数

参数	类型	描述
key	Key \| ResourceKeys	目标语言环境消息键

返回值

语言环境消息

示例

模板块:

html

<div class="container">
  <template v-for="content in tm('contents')">
    <h2>{{ rt(content.title) }}</h2>
    <p v-for="paragraph in content.paragraphs">
     {{ rt(paragraph) }}
    </p>
  </template>
</div>

脚本块:

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

useI18n 的 Composer 额外选项

签名:

typescript

export interface ComposerAdditionalOptions

详情

ComposerAdditionalOptions 扩展自 ComposerOptions，因此你可以指定这些选项。

useScope

ComposerCustom

Composer 的类型自定义定义

签名:

typescript

export interface ComposerCustom

详情

可以扩展 Composer 的接口。

由第三方定义的类型（如 nuxt/i18n）

示例

// vue-i18n.d.ts (应用中的 `.d.ts` 文件)

declare module 'vue-i18n' {
  interface ComposerCustom {
    localeCodes: string[]
  }
}

ComposerDateTimeFormatting

日期时间格式化函数

签名:

typescript

export interface ComposerDateTimeFormatting<DateTimeFormats extends Record<string, any> = {}, Locales = 'en-US', DefinedDateTimeFormat extends RemovedIndexResources<DefineDateTimeFormat> = RemovedIndexResources<DefineDateTimeFormat>, C = IsEmptyObject<DefinedDateTimeFormat> extends false ? PickupFormatPathKeys<{
    [K in keyof DefinedDateTimeFormat]: DefinedDateTimeFormat[K];
}> : never, M = IsEmptyObject<DateTimeFormats> extends false ? PickupFormatKeys<DateTimeFormats> : never, ResourceKeys extends C | M = IsNever<C> extends false ? IsNever<M> extends false ? C | M : C : IsNever<M> extends false ? M : never>

详情

这是 Composer 的接口

(value: number | Date | string): string;

日期时间格式化

签名:

typescript

(value: number | Date | string): string;

详情

如果在响应式上下文中使用，当语言环境更改时将重新评估。

如果在 useI18n 中指定了 'local' 或某些 UseI18nOptions，它会在优先局部作用域日期时间格式中翻译，而不是全局作用域日期时间格式。

如果没有，则使用全局作用域日期时间格式。

请参见:

日期时间格式化

参数

参数	类型	描述
value	number \| Date \| string	值，时间戳数字或 `Date` 实例或 ISO 8601 字符串

返回值

格式化后的值

(value: Value, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;

日期时间格式化

签名:

typescript

<Value extends number | Date | string = number, Key extends string = string, OptionsType extends Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> = Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>>(value: Value, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;

详情

重载的 d。

在此重载的 d 中，使用注册的日期时间格式进行格式化。

参数

参数	类型	描述
value	Value	值，时间戳数字或 `Date` 实例或 ISO 8601 字符串
keyOrOptions	OptionsType	日期时间格式的键，或用于日期时间格式化的附加参数

返回值

格式化后的值

(value: Value, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;

日期时间格式化

签名:

typescript

<Value extends number | Date | string = number, Key extends string = string, OptionsType extends Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales> = Key | ResourceKeys | DateTimeOptions<Key | ResourceKeys, Locales>>(value: Value, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;

详情

重载的 d。

在此重载的 d 中，在目标语言环境中使用注册的日期时间格式进行格式化。

参数

参数	类型	描述
value	Value	值，时间戳数字或 `Date` 实例或 ISO 8601 字符串
keyOrOptions	OptionsType	日期时间格式的键，或用于日期时间格式化的附加参数
locale	Locales	将用于覆盖全局作用域或局部作用域的语言环境。

返回值

格式化后的值

ComposerNumberFormatting

数字格式化函数

签名:

typescript

export interface ComposerNumberFormatting<NumberFormats extends Record<string, any> = {}, Locales = 'en-US', DefinedNumberFormat extends RemovedIndexResources<DefineNumberFormat> = RemovedIndexResources<DefineNumberFormat>, C = IsEmptyObject<DefinedNumberFormat> extends false ? PickupFormatPathKeys<{
    [K in keyof DefinedNumberFormat]: DefinedNumberFormat[K];
}> : never, M = IsEmptyObject<NumberFormats> extends false ? PickupFormatKeys<NumberFormats> : never, ResourceKeys extends C | M = IsNever<C> extends false ? IsNever<M> extends false ? C | M : C : IsNever<M> extends false ? M : never>

详情

这是 Composer 的接口

(value: number): string;

数字格式化

签名:

typescript

(value: number): string;

详情

如果在响应式上下文中使用，当语言环境更改时将重新评估。

如果在 useI18n 中指定了 'local' 或某些 UseI18nOptions，它会在优先局部作用域数字格式中翻译，而不是全局作用域数字格式。

如果没有，则使用全局作用域数字格式。

请参见:

数字格式化

参数

参数	类型	描述
value	number	数字值

返回值

格式化后的值

(value: number, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.NumberFormatPart[] : string;

数字格式化

签名:

typescript

<Key extends string = string, OptionsType extends Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> = Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>>(value: number, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.NumberFormatPart[] : string;

详情

重载的 n。

在此重载的 n 中，使用注册的数字格式进行格式化。

参数

参数	类型	描述
value	number	数字值
keyOrOptions	OptionsType	数字格式的键，或用于数字格式化的附加参数

返回值

格式化后的值

(value: number, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.NumberFormatPart[] : string;

数字格式化

签名:

typescript

<Key extends string = string, OptionsType extends Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales> = Key | ResourceKeys | NumberOptions<Key | ResourceKeys, Locales>>(value: number, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.NumberFormatPart[] : string;

详情

重载的 n。

在此重载的 n 中，在目标语言环境中使用注册的数字格式进行格式化。

参数

参数	类型	描述
value	number	数字值
keyOrOptions	OptionsType	数字格式的键，或用于数字格式化的附加参数
locale	Locales	将用于覆盖全局作用域或局部作用域的语言环境。

返回值

格式化后的值

ComposerOptions

Composer 选项

签名:

typescript

export interface ComposerOptions<Schema extends {
    message?: unknown;
    datetime?: unknown;
    number?: unknown;
} = {
    message: DefaultLocaleMessageSchema;
    datetime: DefaultDateTimeFormatSchema;
    number: DefaultNumberFormatSchema;
}, Locales extends {
    messages: unknown;
    datetimeFormats: unknown;
    numberFormats: unknown;
} | string = Locale, MessagesLocales = Locales extends {
    messages: infer M;
} ? M : Locales extends string ? Locales : Locale, DateTimeFormatsLocales = Locales extends {
    datetimeFormats: infer D;
} ? D : Locales extends string ? Locales : Locale, NumberFormatsLocales = Locales extends {
    numberFormats: infer N;
} ? N : Locales extends string ? Locales : Locale, MessageSchema = Schema extends {
    message: infer M;
} ? M : DefaultLocaleMessageSchema, DateTimeSchema = Schema extends {
    datetime: infer D;
} ? D : DefaultDateTimeFormatSchema, NumberSchema = Schema extends {
    number: infer N;
} ? N : DefaultNumberFormatSchema, _Messages extends LocaleMessages<MessageSchema, MessagesLocales, VueMessageType> = LocaleMessages<MessageSchema, MessagesLocales, VueMessageType>, _DateTimeFormats extends DateTimeFormatsType<DateTimeSchema, DateTimeFormatsLocales> = DateTimeFormatsType<DateTimeSchema, DateTimeFormatsLocales>, _NumberFormats extends NumberFormatsType<NumberSchema, NumberFormatsLocales> = NumberFormatsType<NumberSchema, NumberFormatsLocales>>

详情

这是创建 composer 的选项。

datetime

datetimeFormats

escapeParameter

签名:

typescript

escapeParameter?: boolean;

详情

如果配置 escapeParameter 为 true，则在翻译消息前转义插值参数。

当翻译输出用于 v-html 并且翻译资源包含 HTML 标记（例如围绕用户提供的值）时，这很有用。

这种使用模式主要出现在将预计算的文本字符串传递给 UI 组件时。

转义过程涉及将以下符号替换为其相应的 HTML 字符实体：<、>、"、'。

将 escapeParameter 设置为 true 不会破坏现有功能，但提供了一种防范轻微 XSS 攻击向量的安全保障。

请参见:

HTML 消息

默认值: false

fallbackFormat

签名:

typescript

fallbackFormat?: boolean;

详情

当你的语言缺少某个键的翻译时，是否对翻译键进行模板插值。

如果设置为 true，则无需为你的"基础"语言编写模板；键即为模板。

请参见:

回退机制

默认值: false

fallbackLocale

签名:

typescript

fallbackLocale?: FallbackLocale;

详情

回退本地化的语言环境。

有关更复杂的回退定义，请参见 fallback。

请参见:

回退机制

默认值: 如果未指定 locale 则为 'en-US'，否则为 locale 值

fallbackRoot

签名:

typescript

fallbackRoot?: boolean;

详情

在组件本地化中，当本地化失败时是否回退到根级别（全局作用域）本地化。

如果为 false，则不回退到根级别。

请参见:

回退机制

默认值: true

fallbackWarn

签名:

typescript

fallbackWarn?: boolean | RegExp;

详情

当回退到 fallbackLocale 或根级别时是否抑制警告。

如果为 false，则抑制回退警告。

如果你使用正则表达式，可以抑制与翻译键（例如 t）匹配的回退警告。

请参见:

回退机制

默认值: true

flatJson

签名:

typescript

flatJson?: boolean;

详情

是否允许使用扁平化 JSON 消息

默认值: false

inheritLocale

签名:

typescript

inheritLocale?: boolean;

详情

是否继承根级语言环境到组件本地化语言环境。

如果为 false，则无论根级语言环境如何，都针对每个组件语言环境进行本地化。

请参见:

局部作用域

默认值: true

locale

签名:

typescript

locale?: Locale;

详情

本地化的语言环境。

如果语言环境包含地区和方言，此语言环境包含隐式回退。

请参见:

作用域和语言环境更改

默认值: 'en-US'

message

messageCompiler

签名:

typescript

messageCompiler?: MessageCompiler;

详情

自定义消息格式编译器。

如果不指定，则使用 vue-i18n 默认消息编译器。

你需要实现自己的消息编译器，返回消息函数。

示例

以下是使用 intl-messageformat 自定义消息编译器的示例:

import { createI18n } from 'vue-i18n'
import IntlMessageFormat from 'intl-messageformat'

function messageCompiler(message, { locale, key, onError }) {
  if (typeof message === 'string') {
    // 你可以在缓存策略或这里也使用记忆化来优化你的消息编译器性能
    const formatter = new IntlMessageFormat(message, locale)
    return ctx => formatter.format(ctx.values)
  } else {
    // 如果你想支持它用于 AST，
    // 你需要使用捆绑插件将 `json`、`yaml` 等转换为消息。
    onError && onError(new Error('not support for AST'))
    return () => key // 返回默认的 `key`
  }
}

// 使用 I18n 选项调用
const i18n = createI18n({
  locale: 'ja',
  messageCompiler, // 设置你的消息编译器
  messages: {
    en: {
      hello: 'hello world!',
      greeting: 'hi, {name}!',
      // ICU 消息格式
      photo: `You have {numPhotos, plural,
        =0 {no photos.}
        =1 {one photo.}
        other {# photos.}
      }`
    },
  }
})

// 下面是你的一些操作...
// ...

[!TIP] 🆕 v9.3+

[!WARNING] 自定义消息格式是实验性功能。它可能会接收破坏性变更或在未来被移除。

请参见:

自定义消息格式

默认值: undefined

messageResolver

签名:

typescript

messageResolver?: MessageResolver;

详情

消息解析器以解析。

如果不指定，则默认使用 vue-i18n 内部消息解析器。

你需要实现自己的消息解析器，满足以下要求:

使用作为第一个参数传入的消息解析器和第二个参数传入的路径来解析消息。
如果无法解析消息，需要返回 null。
如果返回了 null，消息解析器还会在启用回退的情况下调用，因此需要解决消息。

消息解析器间接由以下 API 调用:

示例

以下是使用 createI18n 设置它的示例:

import { createI18n } from 'vue-i18n'

// 你的消息解析器
function messageResolver(obj, path) {
  // 简单的消息解析!
  const msg = obj[path]
  return msg != null ? msg : null
}

// 使用 I18n 选项调用
const i18n = createI18n({
  locale: 'ja',
  messageResolver, // 设置你的消息解析器
  messages: {
    en: { ... },
    ja: { ... }
  }
})

// 下面是你的一些操作...
// ...

[!TIP] 🆕 v9.2+

[!WARNING] 如果使用了消息解析器，将忽略 flatJson 设置。也就是说，你需要自己解析扁平化 JSON。

请参见:

回退机制

默认值: undefined

messages

missing

签名:

typescript

missing?: MissingHandler;

详情

本地化缺失处理程序。

该处理程序在本地化目标语言环境、本地化路径键、Vue 实例和值上调用。

如果分配了缺失处理程序，并且发生了本地化缺失，则不会发出警告。

默认值: null

missingWarn

签名:

typescript

missingWarn?: boolean | RegExp;

详情

当本地化失败时是否抑制警告输出。

如果为 false，则抑制本地化失败警告。

如果你使用正则表达式，可以抑制与翻译键（例如 t）匹配的本地化失败警告。

请参见:

回退机制

默认值: true

modifiers

签名:

typescript

modifiers?: LinkedModifiers<VueMessageType>;

详情

链接消息的自定义修饰符。

请参见:

自定义修饰符

number

numberFormats

pluralRules

签名:

typescript

pluralRules?: PluralizationRules;

详情

单词复数规则集

请参见:

自定义复数

默认值: {}

postTranslation

签名:

typescript

postTranslation?: PostTranslationHandler<VueMessageType>;

详情

后翻译处理程序。

在 t 调用之后调用该处理程序。

这个处理程序对于过滤翻译文本很有用，比如空格修剪。

默认值: null

warnHtmlMessage

签名:

typescript

warnHtmlMessage?: boolean;

详情

是否允许使用 HTML 格式的语言环境消息。

请参见 warnHtmlMessage 属性。

请参见:

默认值: true

ComposerResolveLocaleMessageTranslation

解析语言环境消息翻译函数

签名:

typescript

export interface ComposerResolveLocaleMessageTranslation<Locales = 'en-US'>

详情

这是 Composer 的接口

(message: MessageFunction<VueMessageType> | VueMessageType): string;

解析语言环境消息翻译

签名:

typescript

(message: MessageFunction<VueMessageType> | VueMessageType): string;

详情

如果在响应式上下文中使用，当语言环境更改时将重新评估。

如果在 useI18n 中指定了 'local' 或某些 UseI18nOptions，它会在优先局部作用域语言环境消息中翻译，而不是全局作用域语言环境消息。

如果没有，则使用全局作用域语言环境消息。

[!TIP] rt 的用例是使用 tm、v-for、javascript for 循环进行程序化语言环境消息翻译。

[!WARNING] rt 与 t 不同之处在于它直接处理语言环境消息，而不是语言环境消息的键。rt 中没有内部回退。你需要理解并使用 tm 返回的语言环境消息结构。

请参见:

作用域和语言环境更改

参数

参数	类型	描述
message	MessageFunction<VueMessageType> \| VueMessageType	目标语言环境消息。你需要指定 `tm` 返回的语言环境消息。

返回值

翻译后的消息

(message: MessageFunction<VueMessageType> | VueMessageType, plural: number, options?: TranslateOptions<Locales>): string;

解析语言环境消息翻译用于复数

签名:

typescript

(message: MessageFunction<VueMessageType> | VueMessageType, plural: number, options?: TranslateOptions<Locales>): string;

详情

重载的 rt。

在此重载的 rt 中，返回复数化翻译消息。

[!TIP] rt 的用例是使用 tm、v-for、javascript for 循环进行程序化语言环境消息翻译。

请参见:

复数

参数

参数	类型	描述
message	MessageFunction<VueMessageType> \| VueMessageType	目标语言环境消息。你需要指定 `tm` 返回的语言环境消息。
plural	number	获取哪个复数字符串。1 返回第一个。
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

(message: MessageFunction<VueMessageType> | VueMessageType, list: unknown[], options?: TranslateOptions<Locales>): string;

解析语言环境消息翻译用于列表插值

签名:

typescript

(message: MessageFunction<VueMessageType> | VueMessageType, list: unknown[], options?: TranslateOptions<Locales>): string;

详情

重载的 rt。

在此重载的 rt 中，返回复数化翻译消息。

[!TIP] rt 的用例是使用 tm、v-for、javascript for 循环进行程序化语言环境消息翻译。

请参见:

列表插值

参数

参数	类型	描述
message	MessageFunction<VueMessageType> \| VueMessageType	目标语言环境消息。你需要指定 `tm` 返回的语言环境消息。
list	unknown[]	列表插值的值。
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

(message: MessageFunction<VueMessageType> | VueMessageType, named: NamedValue, options?: TranslateOptions<Locales>): string;

解析语言环境消息翻译用于命名插值

签名:

typescript

(message: MessageFunction<VueMessageType> | VueMessageType, named: NamedValue, options?: TranslateOptions<Locales>): string;

详情

重载的 rt。

在此重载的 rt 中，对于每个占位符 x，语言环境消息应包含 {x} 令牌。

[!TIP] rt 的用例是使用 tm、v-for、javascript for 循环进行程序化语言环境消息翻译。

请参见:

命名插值

参数

参数	类型	描述
message	MessageFunction<VueMessageType> \| VueMessageType	目标语言环境消息。你需要指定 `tm` 返回的语言环境消息。
named	NamedValue	命名插值的值。
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

ComposerTranslation

语言环境消息翻译函数

签名:

typescript

export interface ComposerTranslation<Messages extends Record<string, any> = {}, Locales = 'en-US', DefinedLocaleMessage extends RemovedIndexResources<DefineLocaleMessage> = RemovedIndexResources<DefineLocaleMessage>, C = IsEmptyObject<DefinedLocaleMessage> extends false ? JsonPaths<{
    [K in keyof DefinedLocaleMessage]: DefinedLocaleMessage[K];
}> : never, M = IsEmptyObject<Messages> extends false ? TranslationsPaths<Messages> : never, ResourceKeys extends C | M = IsNever<C> extends false ? IsNever<M> extends false ? C | M : C : IsNever<M> extends false ? M : never>

详情

这是 Composer 的接口

(key: Key | ResourceKeys | number): string;

语言环境消息翻译

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number): string;

详情

如果在响应式上下文中使用，当语言环境更改时将重新评估。

如果在 useI18n 中指定了 I18nScope 'local' 或某些 UseI18nOptions，它会在优先局部作用域语言环境消息中翻译，而不是全局作用域语言环境消息。

如果没有，则使用全局作用域语言环境消息。

请参见:

作用域和语言环境更改

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键

返回值

翻译后的消息

(key: Key | ResourceKeys | number, named: NamedValue): string;

语言环境消息翻译用于命名插值

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, named: NamedValue): string;

详情

重载的 t。

在此重载的 t 中，对于每个占位符 x，语言环境消息应包含 {x} 令牌。

你也可以根据选项抑制翻译缺失警告。

请参见:

命名插值

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
named	NamedValue	命名插值的值

返回值

翻译后的消息

(key: Key | ResourceKeys | number, named: NamedValue, plural: number): string;

语言环境消息翻译用于命名插值和复数

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, named: NamedValue, plural: number): string;

详情

重载的 t。

在此重载的 t 中，对于每个占位符 x，语言环境消息应包含 {x} 令牌，并返回复数化翻译消息。

请参见:

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
named	NamedValue	命名插值的值
plural	number	获取哪个复数字符串。1 返回第一个。

返回值

翻译后的消息

(key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string;

语言环境消息翻译用于命名插值和复数

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, named: NamedValue, defaultMsg: string): string;

详情

重载的 t。

在此重载的 t 中，对于每个占位符 x，语言环境消息应包含 {x} 令牌，如果没有找到翻译，则返回默认消息。

请参见:

命名插值

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
named	NamedValue	命名插值的值
defaultMsg	string	如果找不到翻译则返回的默认消息

返回值

翻译后的消息

(key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions<Locales>): string;

语言环境消息翻译用于命名插值

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions<Locales>): string;

详情

重载的 t。

在此重载的 t 中，对于每个占位符 x，语言环境消息应包含 {x} 令牌。

你也可以根据选项抑制翻译缺失警告。

关于选项的详细信息，请参见。

有关使用方法的详细信息:

命名插值

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
named	NamedValue	命名插值的值
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

(key: Key | ResourceKeys | number, plural: number): string;

语言环境消息翻译用于复数

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, plural: number): string;

详情

重载的 t。

在此重载的 t 中，返回复数化翻译消息。

你也可以根据选项抑制翻译缺失警告。

请参见:

复数

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
plural	number	获取哪个复数字符串。1 返回第一个。

返回值

翻译后的消息

(key: Key | ResourceKeys | number, plural: number, options: TranslateOptions<Locales>): string;

语言环境消息翻译用于复数

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, plural: number, options: TranslateOptions<Locales>): string;

详情

重载的 t。

在此重载的 t 中，返回复数化翻译消息。

你也可以根据选项抑制翻译缺失警告。

关于选项的详细信息，请参见。

请参见:

复数

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
plural	number	获取哪个复数字符串。1 返回第一个。
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

(key: Key | ResourceKeys | number, defaultMsg: string): string;

语言环境消息翻译用于缺失默认消息

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, defaultMsg: string): string;

详情

重载的 t。

在此重载的 t 中，如果没有找到翻译，则返回默认消息。

你也可以根据选项抑制翻译缺失警告。

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
defaultMsg	string	如果找不到翻译则返回的默认消息

返回值

翻译后的消息

(key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions<Locales>): string;

语言环境消息翻译用于缺失默认消息

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions<Locales>): string;

详情

重载的 t。

在此重载的 t 中，如果没有找到翻译，则返回默认消息。

你也可以根据选项抑制翻译缺失警告。

关于选项的详细信息，请参见。

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
defaultMsg	string	如果找不到翻译则返回的默认消息
options	TranslateOptions<Locales>	翻译的附加参数

返回值

翻译后的消息

(key: Key | ResourceKeys | number, list: unknown[]): string;

语言环境消息翻译用于列表插值

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, list: unknown[]): string;

详情

重载的 t。

在此重载的 t 中，语言环境消息应包含 {0}、{1}、…等每个占位符。

你也可以根据选项抑制翻译缺失警告。

请参见:

列表插值

参数

参数	类型	描述
key	Key \| ResourceKeys \| number	目标语言环境消息键
list	unknown[]	列表插值的值

返回值

翻译后的消息

(key: Key | ResourceKeys | number, list: unknown[], plural: number): string;

语言环境消息翻译用于列表插值和复数

签名:

typescript

<Key extends string>(key: Key | ResourceKeys | number, list: unknown[], plural: number): string;

详情

重载的 t。

在此重载的 t 中，语言环境消息应包含 {0}、{1}、…等每个占位符，并返回复数化翻译消息。

请参见:

复数

组合式 API ​

Composer ​

availableLocales ​

d ​

datetimeFormats ​

escapeParameter ​

fallbackFormat ​

fallbackLocale ​

fallbackRoot ​

fallbackWarn ​

id ​

inheritLocale ​

isGlobal ​

locale ​

messages ​

missingWarn ​

modifiers ​

n ​

numberFormats ​

pluralRules ​

rt ​

t ​

warnHtmlMessage ​

getDateTimeFormat(locale) ​

类型参数 ​

参数 ​

返回值 ​

getLocaleMessage(locale) ​

类型参数 ​

参数 ​

返回值 ​

getMissingHandler() ​

参数 ​

返回值 ​

getNumberFormat(locale) ​

类型参数 ​

参数 ​

返回值 ​

getPostTranslationHandler() ​

参数 ​

返回值 ​

mergeDateTimeFormat(locale, format) ​

类型参数 ​

参数 ​

mergeLocaleMessage(locale, message) ​

类型参数 ​

参数 ​

mergeNumberFormat(locale, format) ​

类型参数 ​

参数 ​

setDateTimeFormat(locale, format) ​

类型参数 ​

参数 ​

setLocaleMessage(locale, message) ​

类型参数 ​

参数 ​

setMissingHandler(handler) ​

参数 ​

setNumberFormat(locale, format) ​

类型参数 ​

参数 ​

setPostTranslationHandler(handler) ​

参数 ​

te(key, locale) ​

参数 ​

返回值 ​

tm(key) ​

参数 ​

返回值 ​

ComposerAdditionalOptions ​

useScope ​

ComposerCustom ​

ComposerDateTimeFormatting ​

(value: number | Date | string): string; ​

参数 ​

返回值 ​

(value: Value, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string; ​

参数 ​

返回值 ​

(value: Value, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string; ​

组合式 API

Composer

availableLocales

d

datetimeFormats

escapeParameter

fallbackFormat

fallbackLocale

fallbackRoot

fallbackWarn

id

inheritLocale

isGlobal

locale

messages

missingWarn

modifiers

n

numberFormats

pluralRules

rt

t

warnHtmlMessage

getDateTimeFormat(locale)

类型参数

参数

返回值

getLocaleMessage(locale)

类型参数

参数

返回值

getMissingHandler()

参数

返回值

getNumberFormat(locale)

类型参数

参数

返回值

getPostTranslationHandler()

参数

返回值

mergeDateTimeFormat(locale, format)

类型参数

参数

mergeLocaleMessage(locale, message)

类型参数

参数

mergeNumberFormat(locale, format)

类型参数

参数

setDateTimeFormat(locale, format)

类型参数

参数

setLocaleMessage(locale, message)

类型参数

参数

setMissingHandler(handler)

参数

setNumberFormat(locale, format)

类型参数

参数

setPostTranslationHandler(handler)

参数

te(key, locale)

参数

返回值

tm(key)

参数

返回值

ComposerAdditionalOptions

useScope

ComposerCustom

ComposerDateTimeFormatting

(value: number | Date | string): string;

参数

返回值

(value: Value, keyOrOptions: OptionsType): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;

参数

返回值

(value: Value, keyOrOptions: OptionsType, locale: Locales): IsPart<OptionsType> extends true ? Intl.DateTimeFormatPart[] : string;