vue-i18n / general / ComposerOptions

Interface: ComposerOptions<Schema, Locales, MessagesLocales, DateTimeFormatsLocales, NumberFormatsLocales, MessageSchema, DateTimeSchema, NumberSchema, _Messages, _DateTimeFormats, _NumberFormats>

Vue I18n Composition

Composer Options

Remarks

This is options to create composer.

Type Parameters

Type Parameter	Default type
Schema extends object	object
Locales extends | { datetimeFormats: unknown; messages: unknown; numberFormats: unknown; } | string	Locale
MessagesLocales	Locales extends object ? M : Locales extends string ? Locales : Locale
DateTimeFormatsLocales	Locales extends object ? D : Locales extends string ? Locales : Locale
NumberFormatsLocales	Locales extends object ? N : Locales extends string ? Locales : Locale
MessageSchema	Schema extends object ? M : DefaultLocaleMessageSchema
DateTimeSchema	Schema extends object ? D : DefaultDateTimeFormatSchema
NumberSchema	Schema extends object ? N : DefaultNumberFormatSchema
_Messages extends LocaleMessages<MessageSchema, MessagesLocales, VueMessageType>	LocaleMessages<MessageSchema, MessagesLocales, VueMessageType>
_DateTimeFormats extends IntlDateTimeFormats<DateTimeSchema, DateTimeFormatsLocales>	IntlDateTimeFormats<DateTimeSchema, DateTimeFormatsLocales>
_NumberFormats extends IntlNumberFormats<NumberSchema, NumberFormatsLocales>	IntlNumberFormats<NumberSchema, NumberFormatsLocales>

Properties

datetimeFormats?

optional datetimeFormats: { [K in string | number | symbol]: DateTimeSchema };

Remarks

The datetime formats of localization.

See about:

• Datetime Formatting

Default

{}

---

escapeParameter?

optional escapeParameter: boolean;

Remarks

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.

See about:

• HTML Message

Default

false

---

fallbackFormat?

optional fallbackFormat: boolean;

Remarks

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.

See about:

• Fallbacking

Default

false

---

fallbackLocale?

optional fallbackLocale: FallbackLocale;

Remarks

The locale of fallback localization.

For more complex fallback definitions see fallback.

See about:

• Fallbacking

Default

The default 'en-US' for the locale if it's not specified, or it's locale value

---

fallbackRoot?

optional fallbackRoot: boolean;

Remarks

In the component localization, whether to fallback to root level (global scope) localization when localization fails.

If false, it's not fallback to root.

See about:

• Fallbacking

Default

true

---

fallbackWarn?

optional fallbackWarn: boolean | RegExp;

Remarks

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

See about:

• Fallbacking

Default

true

---

flatJson?

optional flatJson: boolean;

Remarks

Allow use flat json messages or not

Default

false

---

inheritLocale?

optional inheritLocale: boolean;

Remarks

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

If false, regardless of the root level locale, localize for each component locale.

See about:

• Local Scope

Default

true

---

locale?

optional locale: string;

Remarks

The locale of localization.

If the locale contains a territory and a dialect, this locale contains an implicit fallback.

See about:

• Scope and Locale Changing

Default

'en-US'

---

messageCompiler?

optional messageCompiler: MessageCompiler;

Remarks

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

Example

Here is an example of how to custom message compiler with intl-messageformat

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

TIP

🆕 v9.3+

WARNING

The Custom Message Format is an experimental feature. It may receive breaking changes or be removed in the future.

See about:

• Custom Message Format

Default

undefined

---

messageResolver?

optional messageResolver: MessageResolver;

Remarks

A message resolver to resolve 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 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 is enabled, so the message will need to be resolved as well.

The message resolver is called indirectly by the following APIs:

• t
• te
• tm
• Translation component

Example

Here is an example of how to set it up using your createI18n:

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

TIP

🆕 v9.2+

WARNING

If you use the message resolver, the Composer#flatJson setting will be ignored. That is, you need to resolve the flat JSON by yourself.

See about:

• Fallbacking

Default

undefined

---

messages?

optional messages: { [K in string | number | symbol]: MessageSchema };

Remarks

The locale messages of localization.

See about:

• Getting Started

Default

{}

---

missing?

optional missing: MissingHandler;

Remarks

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

null

---

missingWarn?

optional missingWarn: boolean | RegExp;

Remarks

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

See about:

• Fallbacking

Default

true

---

modifiers?

optional modifiers: LinkedModifiers<VueMessageType>;

Remarks

Custom Modifiers for linked messages.

See about:

• Custom Modifiers

---

numberFormats?

optional numberFormats: { [K in string | number | symbol]: NumberSchema };

Remarks

The number formats of localization.

See about:

• Number Formatting

Default

{}

---

pluralRules?

optional pluralRules: PluralizationRules;

Remarks

A set of rules for word pluralization

See about:

• Custom Pluralization

Default

{}

---

postTranslation?

optional postTranslation: PostTranslationHandler<VueMessageType>;

Remarks

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

null

---

warnHtmlMessage?

optional warnHtmlMessage: boolean;

Remarks

Whether to allow the use locale messages of HTML formatting.

See the warnHtmlMessage property.

See about:

• HTML Message
• Change warnHtmlInMessage option default value

Default

true