Composition API ​

Composer ​

Composer interfaces

Signature:

export interface Composer<Messages = {}, DateTimeFormats = {}, NumberFormats = {}, Message = VueMessageType>

Details

This is the interface for being used for Vue 3 Composition API.

availableLocales ​

Signature:

readonly availableLocales: Locale[];

Details

The list of available locales in messages in lexical order.

datetimeFormats ​

Signature:

readonly datetimeFormats: ComputedRef<DateTimeFormats>;

Details

The datetime formats of localization.

See Also

• Datetime Formatting

escapeParameter ​

Signature:

escapeParameter: boolean;

Details

Whether interpolation parameters are escaped before the message is translated.

See Also

• HTML Message

fallbackFormat ​

Signature:

fallbackFormat: boolean;

Details

Whether suppress warnings when falling back to either fallbackLocale or root.

See Also

• Fallbacking

fallbackLocale ​

Signature:

fallbackLocale: WritableComputedRef<FallbackLocale>;

Details

The current fallback locales this Composer instance is using.

See Also

• Fallbacking

fallbackRoot ​

Signature:

fallbackRoot: boolean;

Details

Whether to fall back to root level (global scope) localization when localization fails.

See Also

• Fallbacking

fallbackWarn ​

Signature:

fallbackWarn: boolean | RegExp;

Details

Whether suppress fall back warnings when localization fails.

See Also

• Fallbacking

id ​

Signature:

id: number;

Details

Instance ID.

inheritLocale ​

Signature:

inheritLocale: boolean;

Details

Whether inherit the root level locale to the component localization locale.

See Also

• Local Scope

isGlobal ​

Signature:

readonly isGlobal: boolean;

Details

Whether this composer instance is global or not

locale ​

Signature:

locale: WritableComputedRef<Locale>;

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

messages ​

Signature:

readonly messages: ComputedRef<Messages>;

Details

The locale messages of localization.

See Also

• Getting Started

missingWarn ​

Signature:

missingWarn: boolean | RegExp;

Details

Whether suppress warnings outputted when localization fails.

See Also

• Fallbacking

modifiers ​

Signature:

readonly modifiers: LinkedModifiers<Message>;

Details

Custom Modifiers for linked messages.

See Also

• Custom Modifiers

numberFormats ​

Signature:

readonly numberFormats: ComputedRef<NumberFormats>;

Details

The number formats of localization.

See Also

• Number Formatting

pluralRules ​

Signature:

readonly pluralRules: PluralizationRules;

Details

A set of rules for word pluralization

See Also

• Custom Pluralization

warnHtmlMessage ​

Signature:

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
• Change warnHtmlInMessage option default value

d(value) ​

Datetime formatting

Signature:

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

Details

If this is used in a reactive context, it will re-evaluate once the locale changes.

If UseI18nScope 'local' or Some 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

Parameters ​

Returns ​

Formatted value

d(value, key) ​

Datetime formatting

Signature:

d(value: number | Date | string, key: string): string;

Details

Overloaded d. About details, see the d details.

In this overloaded d, format in datetime format for a key registered in datetime formats.

Parameters ​

Returns ​

Formatted value

d(value, key, locale) ​

Datetime formatting

Signature:

d(value: number | Date | string, key: string, locale: Locale): string;

Details

Overloaded d. About details, see the d details.

In this overloaded d, format in datetime format for a key registered in datetime formats at target locale

Parameters ​

Returns ​

Formatted value

d(value, options) ​

Datetime formatting

Signature:

d(value: number | Date | string, options: DateTimeOptions): string;

Details

Overloaded d. About details, see the d details.

You can also suppress the warning, when the formatting missing according to the options.

About details of options, see the .

Parameters ​

Returns ​

Formatted value

getDateTimeFormat(locale) ​

Get datetime format

Signature:

getDateTimeFormat(locale: Locale): DateTimeFormat;

Details

get datetime format from Composer instance datetimeFormats.

Parameters ​

Returns ​

Datetime format

getLocaleMessage(locale) ​

Get locale message

Signature:

getLocaleMessage(locale: Locale): LocaleMessageDictionary<Message>;

Details

get locale message from Composer instance messages.

Parameters ​

Returns ​

Locale messages

getMissingHandler() ​

Get missing handler

Signature:

getMissingHandler(): MissingHandler | null;

See Also

• missing

Parameters ​

Returns ​

MissingHandler

getNumberFormat(locale) ​

Get number format

Signature:

getNumberFormat(locale: Locale): NumberFormat;

Details

get number format from Composer instance numberFormats.

Parameters ​

Returns ​

Number format

getPostTranslationHandler() ​

Get post translation handler

Signature:

getPostTranslationHandler(): PostTranslationHandler<Message> | null;

See Also

• missing

Parameters ​

Returns ​

mergeDateTimeFormat(locale, format) ​

Merge datetime format

Signature:

mergeDateTimeFormat(locale: Locale, format: DateTimeFormat): void;

Details

Merge datetime format to Composer instance datetimeFormats.

Parameters ​

mergeLocaleMessage(locale, message) ​

Merge locale message

Signature:

mergeLocaleMessage(locale: Locale, message: LocaleMessageDictionary<Message>): void;

Details

Merge locale message to Composer instance messages.

Parameters ​

mergeNumberFormat(locale, format) ​

Merge number format

Signature:

mergeNumberFormat(locale: Locale, format: NumberFormat): void;

Details

Merge number format to Composer instance numberFormats.

Parameters ​

n(value) ​

Number Formatting

Signature:

n(value: number): string;

Details

If this is used in a reactive context, it will re-evaluate once the locale changes.

If UseI18nScope 'local' or Some 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

Parameters ​

Returns ​

Formatted value

n(value, key) ​

Number Formatting

Signature:

n(value: number, key: string): string;

Details

Overloaded n. About details, see the n details.

In this overloaded n, format in number format for a key registered in number formats.

Parameters ​

Returns ​

Formatted value

n(value, key, locale) ​

Number Formatting

Signature:

n(value: number, key: string, locale: Locale): string;

Details

Overloaded n. About details, see the n details.

In this overloaded n, format in number format for a key registered in number formats at target locale.

Parameters ​

Returns ​

Formatted value

n(value, options) ​

Number Formatting

Signature:

n(value: number, options: NumberOptions): string;

Details

Overloaded n. About details, see the n details.

You can also suppress the warning, when the formatting missing according to the options.

About details of options, see the .

Parameters ​

Returns ​

Formatted value

rt(message) ​

Resolve locale message translation

Signature:

rt(message: MessageFunction<Message> | Message): string;

Details

If this is used in a reactive context, it will re-evaluate once the locale changes.

If UseI18nScope 'local' or Some 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

Parameters ​

Returns ​

Translated message

rt(message, plural, options) ​

Resolve locale message translation for plurals

Signature:

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

Details

Overloaded rt. About details, see the rt details.

In this overloaded rt, return a pluralized translation message.

See Also

• Pluralization

Parameters ​

Returns ​

Translated message

rt(message, list, options) ​

Resolve locale message translation for list interpolations

Signature:

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

Details

Overloaded rt. About details, see the rt details.

In this overloaded rt, return a pluralized translation message.

See Also

• List interpolation

Parameters ​

Returns ​

Translated message

rt(message, named, options) ​

Resolve locale message translation for named interpolations

Signature:

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

Details

Overloaded rt. About details, see the rt details.

In this overloaded rt, for each placeholder x, the locale messages should contain a {x} token.

See Also

• Named interpolation

Parameters ​

Returns ​

Translated message

setDateTimeFormat(locale, format) ​

Set datetime format

Signature:

setDateTimeFormat(locale: Locale, format: DateTimeFormat): void;

Details

Set datetime format to Composer instance datetimeFormats.

Parameters ​

setLocaleMessage(locale, message) ​

Set locale message

Signature:

setLocaleMessage(locale: Locale, message: LocaleMessageDictionary<Message>): void;

Details

Set locale message to Composer instance messages.

Parameters ​

setMissingHandler(handler) ​

Set missing handler

Signature:

setMissingHandler(handler: MissingHandler | null): void;

See Also

• missing

Parameters ​

setNumberFormat(locale, format) ​

Set number format

Signature:

setNumberFormat(locale: Locale, format: NumberFormat): void;

Details

Set number format to Composer instance numberFormats.

Parameters ​

setPostTranslationHandler(handler) ​

Set post translation handler

Signature:

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

See Also

• missing

Parameters ​

t(key) ​

Locale message translation

Signature:

t(key: Path | number): string;

Details

If this is used in a reactive context, it will re-evaluate once the locale changes.

If UseI18nScope 'local' or Some 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

Parameters ​

Returns ​

Translated message

t(key, plural, options) ​

Locale message translation for plurals

Signature:

t(key: Path | number, plural: number, options?: TranslateOptions): string;

Details

Overloaded t. About details, see the t 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

Parameters ​

Returns ​

Translated message

t(key, defaultMsg, options) ​

Locale message translation for missing default message

Signature:

t(key: Path | number, defaultMsg: string, options?: TranslateOptions): string;

Details

Overloaded t. About details, see the t 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 ​

Returns ​

Translated message

t(key, list, options) ​

Locale message translation for list interpolations

Signature:

t(key: Path | number, list: unknown[], options?: TranslateOptions): string;

Details

Overloaded t. About details, see the t 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

Parameters ​

Returns ​

Translated message

t(key, list, plural) ​

Locale message translation for list interpolations and plurals

Signature:

t(key: Path | number, list: unknown[], plural: number): string;

Details

Overloaded t. About details, see the t 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
• List interpolation

Parameters ​

Returns ​

Translated message

t(key, list, defaultMsg) ​

Locale message translation for list interpolations and missing default message

Signature:

t(key: Path | number, list: unknown[], defaultMsg: string): string;

Details

Overloaded t. About details, see the t 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

Parameters ​

Returns ​

Translated message

t(key, named, options) ​

Locale message translation for named interpolations

Signature:

t(key: Path | number, named: NamedValue, options?: TranslateOptions): string;

Details

Overloaded t. About details, see the t 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

Parameters ​

Returns ​

Translated message

t(key, named, plural) ​

Locale message translation for named interpolations and plurals

Signature:

t(key: Path | number, named: NamedValue, plural: number): string;

Details

Overloaded t. About details, see the t 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
• Named interpolation

Parameters ​

Returns ​

Translated message

t(key, named, defaultMsg) ​

Locale message translation for named interpolations and plurals

Signature:

t(key: Path | number, named: NamedValue, defaultMsg: string): string;

Details

Overloaded t. About details, see the t 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

Parameters ​

Returns ​

Translated message

te(key, locale) ​

Translation locale message exist

Signature:

te(key: Path, locale?: Locale): boolean;

Details

whether do exist locale message on Composer instance messages.

If you specified locale, check the locale messages of locale.

Parameters ​

Returns ​

If found locale message, true, else false

tm(key) ​

Locale messages getter

Signature:

tm(key: Path): LocaleMessageValue<Message> | {};

Details

If UseI18nScope 'local' or Some 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.

Parameters ​

Locale messages |

Examples

template block:

<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>

script block:

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:

export interface ComposerAdditionalOptions

Details

ComposerAdditionalOptions is extend for ComposerOptions, so you can specify these options.

See Also

• useI18n

useScope ​

ComposerOptions ​

Composer Options

Signature:

export interface ComposerOptions<Message = VueMessageType>

Details

This is options to create composer.

datetimeFormats ​

Signature:

datetimeFormats?: DateTimeFormatsType;

Details

The datetime formats of localization.

Default Value

{}

See Also

• Datetime Formatting

escapeParameter ​

Signature:

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

fallbackFormat ​

Signature:

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

fallbackLocale ​

Signature:

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

fallbackRoot ​

Signature:

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

fallbackWarn ​

Signature:

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

flatJson ​

Signature:

flatJson?: boolean;

Details

Allow use flat json messages or not

Default Value

false

inheritLocale ​

Signature:

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

locale ​

Signature:

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

messages ​

Signature:

messages?: LocaleMessages<Message>;

Details

The locale messages of localization.

Default Value

{}

See Also

• Getting Started

missing ​

Signature:

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:

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

modifiers ​

Signature:

modifiers?: LinkedModifiers<Message>;

Details

Custom Modifiers for linked messages.

See Also

• Custom Modifiers

numberFormats ​

Signature:

numberFormats?: NumberFormatsType;

Details

The number formats of localization.

Default Value

{}

See Also

• Number Formatting

pluralRules ​

Signature:

pluralRules?: PluralizationRules;

Details

A set of rules for word pluralization

Default Value

{}

See Also

• Custom Pluralization

postTranslation ​

Signature:

postTranslation?: PostTranslationHandler<Message>;

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:

warnHtmlMessage?: boolean;

Details

Whether to allow the use locale messages of HTML formatting.

See the warnHtmlMessage property.

Default Value

'off'

See Also

• HTML Message
• Change warnHtmlInMessage option default value

MissingHandler ​

Signature:

export declare type MissingHandler = (locale: Locale, key: Path, insttance?: ComponentInternalInstance, type?: string) => string | void;

useI18n ​

Use Composition API for Vue I18n

Signature:

export declare function useI18n<Options extends UseI18nOptions = object, Messages extends Record<keyof Options['messages'], LocaleMessageDictionary<VueMessageType>> = Record<keyof Options['messages'], LocaleMessageDictionary<VueMessageType>>, DateTimeFormats extends Record<keyof Options['datetimeFormats'], DateTimeFormat> = Record<keyof Options['datetimeFormats'], DateTimeFormat>, NumberFormats extends Record<keyof Options['numberFormats'], NumberFormat> = Record<keyof Options['numberFormats'], NumberFormat>>(options?: Options): Composer<Options['messages'], Options['datetimeFormats'], Options['numberFormats']>;

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 ​

Returns ​

Composer instance

Examples

case: Component resource base localization

<template>
  <form>
    <label>{{ t('language') }}</label>
    <select v-model="locale">
      <option value="en">en</option>
      <option value="ja">ja</option>
    </select>
  </form>
  <p>message: {{ t('hello') }}</p>
</template>

<script>
import { useI18n } from 'vue-i18n'

export default {
 setup() {
   const { t, locale } = useI18n({
     locale: 'ja',
     messages: {
       en: { ... },
       ja: { ... }
     }
   })
   // Something to do ...

   return { ..., t, locale }
 }
}
</script>

UseI18nOptions ​

I18n Options for useI18n

Signature:

export declare type UseI18nOptions = ComposerAdditionalOptions & ComposerOptions;

Details

UseI18nOptions is inherited ComposerAdditionalOptions and ComposerOptions, so you can specify these options.

See Also

• useI18n

VueMessageType ​

Signature:

export declare type VueMessageType = string | VNode;