---
url: /guide/migration/breaking10.md
---
# Breaking Changes in v10

## Default enable for JIT compilation

**Reason**: CSP problems can be solved and dynamic resources can be supported

JIT compilation was introduced in v9.3. It was not enabled by default.

Nuxt I18n, which integrates vue-i18n, already has this feature enabled and stable by default.
https://i18n.nuxtjs.org/docs/options/compilation#jit

To use this feature in Vue I18n, we had to use bundler and `@intlify/unplugin-vue-i18n` to enable the `__INTLIFY_JIT_COMPILATION__` flag.
By default in the JIT compilation, this flag is no longer needed starting with v10.

If you would not still using the JIT compilation and would be moving up to v10 or later, **you will need to rebuild your application once**.

About JIT compilation details, See "[Optimization](../advanced/optimization.md)".

## Change `$t` and `t` overloaded signature for Legacy API mode

In Vue I18n v9, it has a different interface from the Composition API mode and Legacy API mode of `$t` and `t` overloaded signature.

Especially, `$t` and `t` signature in Legacy API mode has fewer overloaded signatures than in Composition API mode, as shown below:

| `$t` and `t` overloaded signatures                                                      | Legacy API v9 | Legacy API v10 | Composition API v9 & v10 |
| --------------------------------------------------------------------------------------- | ------------- | -------------- | ------------------------ |
| `$t(key: Key): TranslateResult;`                                                        | ✅            | ✅             | ✅                       |
| `$t(key: Key, locale: Locale): TranslateResult;`                                        | ✅            | -              | -                        |
| `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`                       | ✅            | -              | -                        |
| `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;`                     | ✅            | -              | -                        |
| `$t(key: Key, plural: number): TranslateResult;`                                        | -             | ✅             | ✅                       |
| `$t(key: Key, plural: number, options: TranslateOptions): TranslateResult;`             | -             | ✅             | ✅                       |
| `$t(key: Key, defaultMsg: string): TranslateResult;`                                    | -             | ✅             | ✅                       |
| `$t(key: Key, defaultMsg: string, options: TranslateOptions): TranslateResult;`         | -             | ✅             | ✅                       |
| `$t(key: Key, list: unknown[]): TranslateResult;`                                       | ✅            | ✅             | ✅                       |
| `$t(key: Key, list: unknown[], plural: number): TranslateResult;`                       | -             | ✅             | ✅                       |
| `$t(key: Key, list: unknown[], defaultMsg: string): TranslateResult;`                   | -             | ✅             | ✅                       |
| `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;`            | -             | ✅             | ✅                       |
| `$t(key: Key, named: Record<string, unknown>): TranslateResult;`                        | ✅            | ✅             | ✅                       |
| `$t(key: Key, named: NamedValue, plural: number): TranslateResult;`                     | -             | ✅             | ✅                       |
| `$t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult;`                 | -             | ✅             | ✅                       |
| `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;`          | -             | ✅             | ✅                       |
| `t(key: Key): TranslateResult;`                                                         | ✅            | ✅             | ✅                       |
| `t(key: Key, locale: Locale): TranslateResult;`                                         | ✅            | -              | -                        |
| `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`                        | ✅            | -              | -                        |
| `t(key: Key, locale: Locale, named: Record<string, unknown>): TranslateResult;`         | ✅            | -              | -                        |
| `t(key: Key, plural: number): TranslateResult; `                                        | -             | ✅             | ✅                       |
| `t(key: Key, plural: number, options: TranslateOptions<Locales>): TranslateResult; `    | -             | ✅             | ✅                       |
| `t(key: Key, defaultMsg: string): TranslateResult;`                                     | -             | ✅             | ✅                       |
| `t(key: Key, defaultMsg: string, options: TranslateOptions<Locales>): TranslateResult;` | -             | ✅             | ✅                       |
| `t(key: Key, list: unknown[]): TranslateResult;`                                        | ✅            | ✅             | ✅                       |
| `t(key: Key, list: unknown[], plural: number): TranslateResult;`                        | -             | ✅             | ✅                       |
| `t(key: Key, list: unknown[], defaultMsg: string): TranslateResult;`                    | -             | ✅             | ✅                       |
| `t(key: Key, list: unknown[], options: TranslateOptions<Locales>): TranslateResult;`    | -             | ✅             | ✅                       |
| `t(key: Key, named: Record<string, unknown>): TranslateResult;`                         | ✅            | ✅             | ✅                       |
| `t(key: Key, named: NamedValue, plural: number): TranslateResult;`                      | -             | ✅             | ✅                       |
| `t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult;`                  | -             | ✅             | ✅                       |
| `t(key: Key, named: NamedValue, options: TranslateOptions<Locales>): TranslateResult;`  | -             | ✅             | ✅                       |

Starting from v10, Legacy API mode can use the same `$t` and `t` overload signature as Composition API mode.

**Reason**: After that migration, when migrating to Composition API mode, we sometimes fall into a pitfall due to the different signature.

If you are using the following APIs in Legacy API mode, you must change to another signature because of the breaking changes:

* `$t(key: Key, locale: Locale): TranslateResult;`
* `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`
* `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;`
* `t(key: Key, locale: Locale): TranslateResult;`
* `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`
* `t(key: Key, locale: Locale, named: NamedValue): TranslateResult;`

### `$t(key: Key, locale: Locale): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $t('message.hello', 'ja') }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` or `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;`

```vue
<template>
  <p>{{ $t('message.hello', {}, { locale: 'ja' }) }}</p>
</template>
```

### `$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $t('message.hello', 'ja', ['dio']) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;`

```vue
<template>
  <p>{{ $t('message.hello', ['dio'], { locale: 'ja' }) }}</p>
</template>
```

### `$t(key: Key, locale: Locale, named: NamedValue): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $t('message.hello', 'ja', { name: 'dio' }) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;`

```vue
<template>
  <p>{{ $t('message.hello', { name: 'dio' }, { locale: 'ja' }) }}</p>
</template>
```

### `t(key: Key, locale: Locale): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', 'ja'))
```

Vue I18n v10 or later:

use `t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;` or `t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', {}, { locale: 'ja' })
```

### `t(key: Key, locale: Locale, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', 'ja', ['dio']))
```

Vue I18n v10 or later:

use `t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', ['dio'], { locale: 'ja' }))
```

### `t(key: Key, locale: Locale, named: NamedValue): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', 'ja', { name: 'dio' }))
```

Vue I18n v10 or later:

use `t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})

console.log(i18n.global.t('message.hello', { name: 'dio' }, { locale: 'ja' }))
```

## Deprecate `tc` and `$tc` for Legacy API mode

The following APIs are deprecated in v10:

* `tc(key: Key | ResourceKeys): TranslateResult;`
* `tc(key: Key | ResourceKeys, locale: Locales | Locale): TranslateResult;`
* `tc(key: Key | ResourceKeys, list: unknown[]): TranslateResult;`
* `tc(key: Key | ResourceKeys, named: Record<string, unknown>): TranslateResult;`
* `tc(key: Key | ResourceKeys, choice: number): TranslateResult;`
* `tc(key: Key | ResourceKeys, choice: number, locale: Locales | Locale): TranslateResult;`
* `tc(key: Key | ResourceKeys, choice: number, list: unknown[]): TranslateResult;`
* `tc(key: Key | ResourceKeys, choice: number, named: Record<string, unknown>): TranslateResult;`
* `$tc(key: Key): TranslateResult;`
* `$tc(key: Key, locale: Locale): TranslateResult;`
* `$tc(key: Key, list: unknown[]): TranslateResult;`
* `$tc(key: Key, named: Record<string, unknown>): TranslateResult;`
* `$tc(key: Key, choice: number): TranslateResult;`
* `$tc(key: Key, choice: number, locale: Locale): TranslateResult;`
* `$tc(key: Key, choice: number, list: unknown[]): TranslateResult;`
* `$tc(key: Key, choice: number, named: Record<string, unknown>): TranslateResult;`

**Reason**: Legacy API mode has `t` and `$t` support plural interfaces, so they can be replaced.

In v10, `tc` and `$tc` still exist to give benefit migration. These will be dropped completely in v11.

If you will use them, Vue I18n will output the console warning in your application.

### `tc(key: Key | ResourceKeys): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana'))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', 1))
```

### `tc(key: Key | ResourceKeys, locale: Locales | Locale): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', 'ja'))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, plural: number, options: TranslateOptions<Locales>): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', 1, { locale: 'ja' }))
```

### `tc(key: Key | ResourceKeys, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', ['dio']))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, list: unknown[], plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', ['dio'], 1))
```

### `tc(key: Key | ResourceKeys, named: Record<string, unknown>): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', { name: 'dio' }))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, named: NamedValue, plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', { name: 'dio' }, 1))
```

### `tc(key: Key | ResourceKeys, choice: number): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', 2))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', 2))
```

### `tc(key: Key | ResourceKeys, choice: number, locale: Locales | Locale): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', 2, 'ja'))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, plural: number, options: TranslateOptions<Locales>): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', 2, { locale: 'ja' }))
```

### `tc(key: Key | ResourceKeys, choice: number, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', 2, ['dio']))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, list: unknown[], plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', ['dio'], 2))
```

### `tc(key: Key | ResourceKeys, choice: number, named: Record<string, unknown>): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.tc('banana', 2, { name: 'dio' }))
```

Vue I18n v10 or later:

use `t(key: Key | ResourceKeys, named: NamedValue, plural: number): TranslateResult;`

```ts
const i18n = createI18n({
  legacy: true,
  // something options ...
})
console.log(i18n.global.t('banana', { name: 'dio' }, 2))
```

### `$tc(key: Key): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana') }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', 1) }}</p>
</template>
```

### `$tc(key: Key, locale: Locale): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', 'ja') }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, plural: number, options: TranslateOptions): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', 1, { locale: 'ja' }) }}</p>
</template>
```

### `$tc(key: Key, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', ['dio']) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, list: unknown[], plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', ['dio'], 1) }}</p>
</template>
```

### `$tc(key: Key, named: Record<string, unknown>): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', { name: 'dio' }) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, named: NamedValue, plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', { name: 'dio' }, 1) }}</p>
</template>
```

### `$tc(key: Key, choice: number): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', 2) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', 2) }}</p>
</template>
```

### `$tc(key: Key, choice: number, locale: Locale): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', 2, 'ja') }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, plural: number, options: TranslateOptions): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', 2, { locale: 'ja' }) }}</p>
</template>
```

### `$tc(key: Key, choice: number, list: unknown[]): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', 2, ['dio']) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, list: unknown[], plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', ['dio'], 2) }}</p>
</template>
```

### `$tc(key: Key, choice: number, named: Record<string, unknown>): TranslateResult;`

Vue I18n v9.x:

```vue
<template>
  <p>{{ $tc('banana', 2,  { name: 'dio' }) }}</p>
</template>
```

Vue I18n v10 or later:

use `$t(key: Key, named: NamedValue, plural: number): TranslateResult;`

```vue
<template>
  <p>{{ $t('banana', { name: 'dio' }, 2) }}</p>
</template>
```

## Drop modulo `%` syntax

Named interpolation using modulo `%` is no longer supported in v10.

**Reason**: module syntax has already deprecated in v9 with a warning.

### for migration

You can use `eslint-plugin-vue-i18n`.

`eslint-plugin-vue-i18n` has `@intlify/vue-i18n/no-deprecated-modulo-syntax` rule.
https://eslint-plugin-vue-i18n.intlify.dev/rules/no-deprecated-modulo-syntax.html

You can fixed with using `eslint --fix`

You must have migrated with eslint before upgrading to vue-i18n v10

## Drop `vue-i18n-bridge`

**Reason**: vue-i18n-bridge is a bridge library for migrating vue-i18n from Vue 2 to Vue 3, and Vue 2 is no longer past EOL.

## Drop `allowComposition` option

**Reason**: This option already deprecated in warning about being dropped in v10. docs says, https://vue-i18n.intlify.dev/guide/migration/vue3.html#about-supporting

This option was added to support the migration from the Legacy API to the composition API on v9.

## Drop `formatter` option on Legacy API

**Reason**: This option was deprecated in warning on v9.

## Drop `preserveDirectiveContent` option on Legacy API

**Reason**: This option was deprecated in warning on v9.

## Drop `preserve` modifier codes on `v-t` directive

**Reason**: This option was deprecated in warning on v9.

## Drop `getChoiceIndex` on Legacy API

**Reason**: This option was deprecated in warning on v9.

## Drop translation component `<i18n>` v8.x compatibility

**Reason**: This option was deprecated in warning on v9.

## Drop `te` behavior v8.x compatibility

**Reason**: This option was deprecated in warning on v9.

This option was introduced in this issue for supporting te behavior v8.x compatibility on v9

---

---
url: /guide/migration/breaking11.md
---
# Breaking Changes in v11

## Deprecate Legacy API mode

### Reason

The Legacy API mode was the API mode compatible with v8 for Vue 2. When v9 was released, the Legacy API was provided to smooth the migration from v8 to v9.

Legacy API mode will be deprecated in v11, as previous vue-i18n releases have already provided the following to support migration to Composition API mode

* Migration from Legacy API mode to Composition API mode: https://vue-i18n.intlify.dev/guide/migration/vue3.html
* Composition API usage: https://vue-i18n.intlify.dev/guide/advanced/composition.html

For compatibility, Legacy API mode still works in v11, but will be removed entirely in v12, so Legacy API mode will not work after that version.

## Deprecate Custom Directive `v-t`

### Reason

The advantage of `v-t` was that it could optimize performance using the vue compiler transform and the pre-translation of `vue-i18n-extension`.

This feature was supported from Vue 2.
About details see the blog article: https://medium.com/@kazu\_pon/performance-optimization-of-vue-i18n-83099eb45c2d

In Vue 3, due to the Composition API, the pre-translation of `vue-i18n-extension` is now limited only for global scope.

In addition, Vue 3 Virtual DOM optimization has been introduced, and the optimization provided by `vue-i18n-extension` is no longer very effective. We need to require settings for SSR, the benefits of using `v-t` have disappeared. And DX of templates using `v-t` is not good. Custom directives do not work with key completion in editors (e.g. vscode).

For compatibility, `v-t` mode still works in v11, but will be removed entirely in v12, so `v-t` will not work after that version.

### for migration

You can use `eslint-plugin-vue-i18n`.

`eslint-plugin-vue-i18n` has `@intlify/vue-i18n/no-deprecated-v-t` rule. https://eslint-plugin-vue-i18n.intlify.dev/rules/no-deprecated-v-t.html

You must have migrated with eslint before upgrading to vue-i18n v11

## Drop `tc` and `$tc` for Legacy API mode

**Reason**: These APIs had already deprecated in warning about being dropped in v11. docs says, https://vue-i18n.intlify.dev/guide/migration/breaking10.html#deprecate-tc-and-tc-for-legacy-api-mode

---

---
url: /guide/migration/breaking.md
---
# Breaking Changes in v9

Most of the APIs offered in Vue I18n v9 (for Vue 3) strive to maintain compatibility, to ease the pain of migration from v8 (for Vue 2). But there are still a few breaking changes that you might encounter while migrating your application. This guide is how to adapt your application to make it work with Vue I18n v9.

## APIs

### `new VueI18n` becomes `createI18n`

Vue I18n is no longer a class but a set of functions. Instead of writing `new VueI18n()`, you now have to call `createI18n`:

Vue I18n v8.x:

```js{2,4,6-8,11}
import Vue from 'vue'
import VueI18n from 'vue-i18n'

Vue.use(VueI18n)

const i18n = new VueI18n({
  // ...
})

new Vue({
  i18n,
  // ...
})
```

Vue I18n v9 or later:

```js{2,4-6,11}
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  // ...
})

const app = createApp({
  // ...
})
app.use(i18n)
```

**Reason**: Vue 3 [Global API changes](https://v3-migration.vuejs.org/breaking-changes/global-api.html), and Vue 3 API architecture changes related for component instances.

### Rename to `datetimeFormats` from `dateTimeFormats`

Vue I18n v8.x:

```js{3-5}
const i18n = new VueI18n({
  // ...
  dateTimeFormats: {
    // ...
  }
})
```

Vue I18n v9 or later:

```js{3-5}
const i18n = createI18n({
  // ...
  datetimeFormats: {
    // ...
  }
})
```

### Translation API return value

The translation API like `$t` and `t` function that return **string** only. Object and array values are no longer returned.

Vue I18n v8.x:

```js{24}
// e.g. Array structure locale messages
const i18n = new VueI18n({
  messages: {
    en: {
      errors: [
        'invalid argument',
        // ...
        'unexpected errors'
      ]
    }
  }
})

// e.g. Error Component
const ErrorMessage = {
  props: {
    code: {
      type: Number,
      required: true
    }
  },
  template: `<p class="error">{{ getErrorMessage(code) }}</p>`,
  methods: {
    getErrorMessage(code) {
      return this.$t('errors')[code]
    }
  }
}
```

In Vue I18n v9 and later, it changed to getting locale messages with `$tm` / `tm`, and to resolve locale messages with `$rt` or `rt`. The following Composition API example:

```js{24}
// e.g. Array structure locale messages
const i18n = createI18n({
  messages: {
    en: {
      errors: [
        'invalid argument',
        // ...
        'unexpected errors'
      ]
    }
  }
})

// e.g. Error Component
const ErrorMessage = {
  props: {
    code: {
      type: Number,
      required: true
    }
  },
  template: `<p class="error">{{ errors(code) }}</p>`,
  setup() {
    const { tm, rt } = useI18n()
    const errors = (code) => rt(tm('errors')[code])
    return { errors }
  }
}
```

**Reason**: To make **simple obligation** to return the translation results, and it’s also to support TypeScript types.

### Pluralization API return value

Similar to *[Translation API return value](#translation-api-return-value)*, the pluralization API like `$tc` and `tc` function that return **string** only. Object and array values are no longer returned.

**Reason**: To make **simple obligation** to return the translation results, and it’s also to support TypeScript types.

### Remove `getChoiceIndex`

> \[!CAUTION]
> `getChoiceIndex` option implementation code is be going to fully remove in v10.

To customize the pluralization rules, Vue I18n v8.x extends `getChoiceIndex` of VueI18n class.

Vue I18n v8.x:

```js
VueI18n.prototype.getChoiceIndex = function (choice, choicesLength) {
  // this === VueI18n instance, so the locale property exists
  if (this.locale !== 'ru') {
    // proceed to the default implementation
  }

  if (choice === 0) {
    return 0;
  }

  const teen = choice > 10 && choice < 20;
  const endsWithOne = choice % 10 === 1;

  if (!teen && endsWithOne) {
    return 1;
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2;
  }
  return (choicesLength < 4) ? 2 : 3;
}
```

In Vue I18n v9 and later, you can customize it with the following options:

Legacy API mode:

```js{21-24}
import { createI18n } from 'vue-i18n'

function customRule(choice, choicesLength, orgRule) {
  if (choice === 0) {
    return 0
  }

  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 === 1
  if (!teen && endsWithOne) {
    return 1
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2
  }

  return choicesLength < 4 ? 2 : 3
}

const i18n = createI18n({
  // ...
  pluralizationRules: {
    ru: customRule,
    // ...
  },
  // ...
})
```

Composition API mode:

```js{23-26}
import { useI18n } from 'vue-i18n'

function customRule(choice, choicesLength, orgRule) {
  if (choice === 0) {
    return 0
  }

  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 === 1
  if (!teen && endsWithOne) {
    return 1
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2
  }

  return choicesLength < 4 ? 2 : 3
}

const MyComp = {
  setup() {
    const { t } = useI18n({
      // ...
      pluralRules: {
        ru: customRule,
        // ...
      },
      // ...
    })

    // ...
  }
}
```

**Reason**: VueI18n class has been removed.

### Change `warnHtmlInMessage` option default value

In Vue I18n v8.x, the value of `warnHtmlInMessage` was `"off"`. Therefore, by default, no warning is output to the console even if the message contains HTML.

In Vue I18n v9 and later, change the default values as follows:

* Legacy API mode: `warnHtmlInMessage` property: `"warn"`
* Composition API mode: `warnHtmlMessage` boolean property, default `true`

In development mode, unless you change this value, you will **receive the warning to the console by default**.

In production mode, it does not detect if the message contains HTML to maximize performance.

**Reason**: to make stronger security for locale messages

### Version info

Version information is now accessible in import syntax instead of the VueI18n class static property.

Vue I18n v8.x:

```js
import VueI18n from 'vue-i18n'

console.log(VueI18n.version)
```

Vue I18n v9 or later:

```js
import { VERSION } from 'vue-i18n'

console.log(VERSION)
```

**Reason**: Tree shaking optimization, and VueI18n class has been removed.

### Remove Intl availability

Removed as major browsers now support the [ECMAScript Internationalization API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

Vue I18n v8.x:

```js
import VueI18n from 'vue-i18n'

console.log(VueI18n.availability)
```

**Reason**: IE9 end of life, and VueI18n class has been removed.

### Remove Custom formatter

> \[!CAUTION]
> `formatter` option implementation code is be going to fully remove in v10.
> As an alternative, vue-i18n has the [custome message format](../advanced/format.md) as an experimental feature.

**Reason**: Due to hard to provide custom formats in the new compiler and runtime APIs. We are planning to support it in the next major version to support in these APIs. If you would like to use ICU message format, you can use the [@formatjs/vue-intl](https://formatjs.io/docs/vue-intl/)

### Remove `preserveDirectiveContent` option

> \[!CAUTION]
> `preserveDirectiveContent` option implementation code is be going to fully remove in v10.

The `v-t` directive for Vue 3 now preserves the default content. Therefore, this option and its properties have been removed from the VueI18n instance.

Vue I18n v8.x:

```js
import VueI18n from 'vue-i18n'

const i18n = new VueI18n({
  // ...
  preserveDirectiveContent: true,
  // ...
})
```

**Reason**: Keep the content to element with `v-t` directive

## Message Format Syntax

### Remove array-like object for List interpolation

In Vue I18n v8.x, List interpolation could use an array-like object as a parameter, such as the following:

```js
import VueI18n from 'vue-i18n'

const i18n = new VueI18n({
  // ...
  messages: {
    en: {
      greeting: 'hello, {0}!'
    }
  },
  // ...
})
```

```html
<p>{{ $t('greeting', { '0': 'kazupon' }) }}</p>
```

In Vue I18n v9 and later, you can’t use array-like objects for list interpolation, you have to use array:

```html
<p>{{ $t('greeting', ['kazupon']) }}</p>
```

**Reason**: provide a Translation API with a consistent argument I/F

### Special character handling

The messages that can be translated by Vue I18n can be highly translated using message format syntax, such as the following:

```
@.caml:{'no apples'} | {0} apple | {n}　apples
```

The message format syntax can be expressed using the following special characters that are used:

* `{`, `}`, `@`, `$`, `|`

Since Vue I18n v9 and later, message format syntax is now handled by the message format compiler, if you use these special characters as part of a message, the message will occur error at compile. If you want to use these special characters, you **have to use literal interpolation**.

```
// e.g. `@` use-case for mail address
{emailIdentity}{'@'}{emailDomain}
```

**Reason**: In order for the message format compiler to correctly handle the special characters of the syntax used in the message format syntax, it is necessary to limit them.

### Remove brackets grouping for Linked messages

In Vue I18n v8.x, the distinction was made between key references in Linked messages and messages using brackets `()` to distinguish between them.

Vue I18n v8.x:

```js{5}
const messages = {
  en: {
    message: {
      dio: 'DIO',
      linked: 'There\'s a reason, you lost, @:(message.dio).'
    }
  }
}
```

In Vue I18n v9 and later, brackets are no longer needed as the message format compiler allows you to handle **named, list, and literal interpolations**.

Vue I18n v9 or later:

```js
const messages = {
  en: {
    message: {
      dio: 'DIO',
      linked: "There\'s a reason, you lost, @:{'message.dio'}."
    }
  }
}
```

## `v-t` directive

### Remove `preserve` modifier

> \[!CAUTION]
> `preserve` modifier implementation code is be going to fully remove in v10.

Similar to *[Remove `preserveDirectiveContent` option](#remove-preservedirectivecontent-option)*, the `v-t` directive for Vue 3 now preserves the default content. Therefore, `preserve` modifier and it’s have been removed from `v-t` directive.

Vue I18n v8.x:

```html
<p v-t.preserve="'hello'"></p>
```

**Reason**: Keep the content to element with `v-t` directive

## Translation component

### Rename to `i18n-t`from `i18n`

The tag name of the translation component (called *i18n functional component* in Vue I18n v8.x) has been changed.

Vue I18n v8.x:

```html
<i18n path="message.greeting" />
```

Vue I18n v9 or later:

```html
<i18n-t keypath="message.greeting" />
```

**Reason**: tag name same i18n custom blocks `<i18n>`, so it’s confusing with the block names and prone to mistakes in SFC.

### `tag` prop is optional

In Vue I18n v8.x, `tag` prop could be used to render child elements without the root element by specifying a tag name and the `Boolean` value `false`.

Vue I18n v8.x:

```html{1,3}
<i18n :tag="false" path="message.greeting">
  <span>hello!</span>
</i18n>
```

Since Vue I18n v9 or later, you can do the same by omitting the `tag` prop.

Vue I18n v9 or later:

```html{1,3}
<i18n-t keypath="message.greeting">
  <span>hello!</span>
</i18n-t>
```

**Reason**: Since Vue 3 now supports Fragments

### Rename to `keypath` prop from `path` prop

Vue I18n v8.x:

```html
<i18n path="message.greeting" />
```

Vue I18n v9 or later:

```html
<i18n-t keypath="message.greeting" />
```

### Remove place syntax with `place` attr and `places` prop

In Vue I18n v9 and later, the `place` attr and `places` prop have been removed from component interpolation.

Vue I18n v8.x:

```html
<i18n path="info" tag="p" :places="{ limit: refundLimit }">
  <span place="limit">{{ refundLimit }}</span>
  <a place="action" :href="refundUrl">{{ $t('refund') }}</a>
</i18n>
```

Vue I18n v9 or later:

```html
<i18n-t keypath="info" tag="p">
  <template #limit>
    <span>{{ refundLimit }}</span>
  <template>
  <template #action>
    <a :href="refundUrl">{{ $t('refund') }}</a>
  <template>
</i18n-t>
```

**Reason**: Since be able to do the same thing with slots

## NumberFormat component

### `tag` prop is optional

Similar to *[Translation component section](#tag-prop-is-optional)*, In NumberFormat component (called *i18n-n functional component* in Vue I18n v8.x) `tag` prop could be used to render child elements without the root element by specifying a tag name and the `Boolean` value `false`.

Vue I18n v8.x:

```html
<i18n-n :tag="false" :value="100" format="currency">
  <span v-slot:integer="slotProps" styles="font-weight: bold">{{ slotProps.integer }}</span>
</i18n-n>
```

Since Vue I18n v9 or later, you can do the same by omitting the `tag` prop.

Vue I18n v9 or later:

```html
<i18n-n :value="100" format="currency">
  <span v-slot:integer="slotProps" styles="font-weight: bold">{{ slotProps.integer }}</span>
</i18n-n>
```

**Reason**: Since Vue 3 now supports Fragments

---

---
url: /api/injection.md
---
# Component Injections

## ComponentCustomOptions

Component Custom Properties for Vue I18n

**Signature:**

```typescript
export interface ComponentCustomOptions;
```

### i18n

Vue I18n options for Component

**Signature:**

```typescript
i18n?: VueI18nOptions;
```

**See Also**

* [VueI18nOptions](legacy#vuei18noptions)

## ComponentCustomProperties

Component Custom Options for Vue I18n

**Signature:**

```typescript
export interface ComponentCustomProperties;
```

**Details**

These properties are injected into every child component

### $i18n

Exported Global Composer instance, or global VueI18n instance.

**Signature:**

```typescript
$i18n: VueI18n | ExportedGlobalComposer;
```

**Details**

You can get the [exported composer instance](general#exportedglobalcomposer) which are exported from global [composer](composition#composer) instance created with [createI18n](general#createi18n), or global [VueI18n](legacy#vuei18n) instance.

You can get the exported composer instance in [Composition API mode](general#mode), or the Vuei18n instance in [Legacy API mode](general#mode), which is the instance you can refer to with this property.

The locales, locale messages, and other resources managed by the instance referenced by this property are valid as global scope.

If the `i18n` component option is not specified, it’s the same as the VueI18n instance that can be referenced by the i18n instance [global](general#global).

**See Also**

* [Scope and Locale Changing](../guide/essentials/scope)
* [Composition API](../guide/advanced/composition)

### $t(key)

Locale message translation

**Signature:**

```typescript
$t(key: Key): TranslateResult;
```

**Details**

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

In [Composition API mode](general#mode), the `$t` is injected by `app.config.globalProperties`. The input / output is the same as for Composer, and it works on **global scope**. About that details, see [Composer#t](composition#t-key).

In [Legacy API mode](general#mode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#t](legacy#t-key).

**See Also**

* [Scope and Locale Changing](../guide/essentials/scope)
* [Composition API](../guide/advanced/composition)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |

#### Returns

Translation message

### $t(key, locale)

:::danger NOTICE
**This API signature is available in Legacy API mode only and is supported until v9**.
:::

Locale message translation

**Signature:**

```typescript
$t(key: Key, locale: Locale): TranslateResult;
```

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| locale | Locale | A locale, override locale that global scope or local scope |

#### Returns

Translation message

### $t(key, locale, list)

:::danger NOTICE
**This API signature is available in Legacy API mode only and is supported until v9**.
:::

Locale message translation

**Signature:**

```typescript
$t(key: Key, locale: Locale, list: unknown[]): TranslateResult;
```

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| locale | Locale | A locale, override locale that global scope or local scope |
| list | unknown\[] | A values of list interpolation |

#### Returns

Translation message

### $t(key, locale, named)

:::danger NOTICE
**This API signature is available in Legacy API mode only and is supported until v9**.
:::

Locale message translation

**Signature:**

```typescript
$t(key: Key, locale: Locale, named: object): TranslateResult;
```

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| locale | Locale | A locale, override locale that global scope or local scope |
| named | object | A values of named interpolation |

#### Returns

Translation message

### $t(key, plural)

Locale message translation

**Signature:**

```typescript
$t(key: Key, plural: number): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| plural | number | A choice number of plural |

#### Returns

Translation message

### $t(key, plural, options)

Locale message translation

**Signature:**

```typescript
$t(key: Key, plural: number, options: TranslateOptions): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| plural | number | A choice number of plural |
| options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $t(key, defaultMsg)

Locale message translation

**Signature:**

```typescript
$t(key: Key, defaultMsg: string): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| defaultMsg | string | A default message to return if no translation was found |

#### Returns

Translation message

### $t(key, defaultMsg, options)

Locale message translation

**Signature:**

```typescript
$t(key: Key, defaultMsg: string, options: TranslateOptions): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| defaultMsg | string | A default message to return if no translation was found |
| options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $t(key, list)

Locale message translation

**Signature:**

```typescript
$t(key: Key, list: unknown[]): TranslateResult;
```

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| list | unknown\[] | A values of list interpolation |

#### Returns

Translation message

### $t(key, list, plural)

Locale message translation

**Signature:**

```typescript
$t(key: Key, list: unknown[], plural: number): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| list | unknown\[] | A values of list interpolation |
| plural | number | A choice number of plural |

#### Returns

Translation message

### $t(key, list, defaultMsg)

Locale message translation

**Signature:**

```typescript
$t(key: Key, list: unknown[], defaultMsg: string): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| list | unknown\[] | A values of list interpolation |
| defaultMsg | string | A default message to return if no translation was found |

#### Returns

Translation message

### $t(key, list, options)

Locale message translation

**Signature:**

```typescript
$t(key: Key, list: unknown[], options: TranslateOptions): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| list | unknown\[] | A values of list interpolation |
| options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $t(key, named)

Locale message translation

**Signature:**

```typescript
$t(key: Key, named: NamedValue): TranslateResult;
```

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| named | NamedValue | A values of named interpolation |

#### Returns

Translation message

### $t(key, named, plural)

Locale message translation

**Signature:**

```typescript
$t(key: Key, named: NamedValue, plural: number): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| named | NamedValue | A values of named interpolation |
| plural | number | A choice number of plural |

#### Returns

Translation message

### $t(key, named, defaultMsg)

Locale message translation

**Signature:**

```typescript
$t(key: Key, named: NamedValue, defaultMsg: string): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| named | NamedValue | A values of named interpolation |
| defaultMsg | string | A default message to return if no translation was found |

#### Returns

Translation message

### $t(key, named, options)

Locale message translation

**Signature:**

```typescript
$t(key: Key, named: NamedValue, options: TranslateOptions): TranslateResult;
```

:::tip NOTE
Supported for **Composition API mode only until v9. v10 or later can also be used in Legacy API mode**.
:::

**Details**

Overloaded `$t`. About details, see the [$t](injection#t-key) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| named | NamedValue | A values of named interpolation |
| options | TranslateOptions | An options, see the [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $rt(message)

Resolve locale message translation

**Signature:**

```typescript
$rt(message: MessageFunction<VueMessageType> | VueMessageType): string;
```

**Details**

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

In [Composition API mode](general#mode), the `$rt` is injected by `app.config.globalProperties`. The input / output is the same as for Composer, and it works on **global scope**. About that details, see [Composer#rt](composition#rt-message).

In [Legacy API mode](general#mode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#rt](legacy#rt-message).

**See Also**

* [Scope and Locale Changing](../guide/essentials/scope)
* [Composition API](../guide/advanced/composition)

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

Translation message

### $rt(message, plural, options)

Resolve locale message translation for plurals

**Signature:**

```typescript
$rt(message: MessageFunction<VueMessageType> | VueMessageType, plural: number, options?: TranslationOptions): string;
```

**Details**

Overloaded `$rt`. About details, see the [$rt](injection#rt-message) remarks.

#### 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 | Additional [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $rt(message, list, options)

Resolve locale message translation for list interpolations

**Signature:**

```typescript
$rt(message: MessageFunction<VueMessageType> | VueMessageType, list: unknown[], options?: TranslationOptions): string;
```

**Details**

Overloaded `$rt`. About details, see the [$rt](injection#rt-message) remarks.

#### 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 | Additional [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $rt(message, named, options)

Resolve locale message translation for named interpolations

**Signature:**

```typescript
$rt(message: MessageFunction<VueMessageType> | VueMessageType, named: NamedValue, options?: TranslationOptions): string;
```

**Details**

Overloaded `$rt`. About details, see the [$rt](injection#rt-message) remarks.

#### 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 | Additional [TranslateOptions](general#translateoptions) |

#### Returns

Translation message

### $te(key, locale)

Translation message exist

**Signature:**

```typescript
$te(key: Key, locale?: Locale): boolean;
```

**Details**

About that details, see [VueI18n#te](legacy#te-key-locale)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |
| locale | Locale | Optional, A locale, override locale that global scope or local scope |

#### Returns

If found locale message, `true`, else `false`.

### $tm(key)

Locale messages getter

**Signature:**

```typescript
$tm(key: Key): LocaleMessageValue<VueMessageType> | {}
```

**Details**

If [i18n component options](injection#i18n) is specified, it’s get in preferentially local scope locale messages than global scope locale messages.

If [i18n component options](injection#i18n) isn’t specified, it’s get with 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).

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | A target locale message key |

#### Returns

Locale messages

:::warning NOTE
You need to use `$rt` for the locale message returned by `$tm`.
:::

### $d(value)

Datetime formatting

**Signature:**

```typescript
$d(value: number | Date): DateTimeFormatResult | string;
```

**Details**

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

In [Composition API mode](general#i18nmode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#d](legacy#d-value).

In [Composition API mode](general#i18nmode), the `$d` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it works on **global scope**. About that details, see [Composer#d](composition#d-value).

**See Also**

* [Datetime Formatting](../guide/essentials/datetime)
* [Scope and Locale Changing](../guide/essentials/scope)
* [Composition API](../guide/advanced/composition#datetime-formatting)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |

#### Returns

Formatted value

### $d(value, key)

Datetime formatting

**Signature:**

```typescript
$d(value: number | Date, key: string): DateTimeFormatResult | string;
```

**Details**

Overloaded `$d`. About details, see the [$d](injection#d-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |
| key | string | A key of datetime formats |

#### Returns

Formatted value

### $d(value, key, locale)

Datetime formatting

**Signature:**

```typescript
$d(value: number | Date, key: string, locale: Locale): DateTimeFormatResult | string;
```

**Details**

Overloaded `$d`. About details, see the [$d](injection#d-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |
| key | string | A key of datetime formats |
| locale | Locale | A locale, override locale that global scope or local scope |

#### Returns

Formatted value

### $d(value, args)

Datetime formatting

**Signature:**

```typescript
$d(value: number | Date, args: { [key: string]: string | boolean | number }): DateTimeFormatResult;
```

**Details**

Overloaded `$d`. About details, see the [$d](injection#d-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |
| args | { \[key: string]: string } | An argument values |

#### Returns

Formatted value

### $d(value, options)

Datetime formatting

**Signature:**

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

**Details**

Overloaded `$d`. About details, see the [$d](injection#d-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |
| options | DateTimeOptions | An options, see the [DateTimeOptions](general#datetimeoptions) |

#### Returns

Formatted value

### $n(value)

Number formatting

**Signature:**

```typescript
$n(value: number): NumberFormatResult | string;
```

**Details**

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

In [Legacy API mode](general#i18nmode), the input / output is the same as for VueI18n instance. About details, see [VueI18n#n](legacy#n-value).

In [Composition API mode](general#i18nmode), the `$n` is injected by `app.config.globalProperties`. The input / output is the same as for Composer instance, and it works on **global scope**. About that details, see [Composer#n](composition#n-value).

**See Also**

* [Number Formatting](../guide/essentials/number)
* [Scope and Locale Changing](../guide/essentials/scope)
* [Composition API](../guide/advanced/composition#number-formatting)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |

#### Returns

Formatted value

### $n(value, key)

Number formatting

**Signature:**

```typescript
$n(value: number, key: string): NumberFormatResult | string;
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | string | A key of number formats |

#### Returns

Formatted value

### $n(value, key, locale)

Number formatting

**Signature:**

```typescript
$n(value: number, key: string, locale: Locale): NumberFormatResult | string;
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | string | A key of number formats |
| locale | Locale | A locale, override locale that global scope or local scope |

#### Returns

Formatted value

### $n(value, args)

Number formatting

**Signature:**

```typescript
$n(value: number, args: { [key: string]: string | boolean | number }): NumberFormatResult;
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| args | { \[key: string]: string } | An argument values |

#### Returns

Formatted value

### $n(value, key, args)

Number formatting

**Signature:**

```typescript
$n(value: number, key: string, args: { [key: string]: string | boolean | number }): NumberFormatResult
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | string | A key of number formats |
| args | { \[key: string]: string } | An argument values |

#### Returns

Formatted value

### $n(value, key, locale, args)

Number formatting

**Signature:**

```typescript
$n(value: number, key: string, locale: Locale, args: { [key: string]: string | boolean | number }): NumberFormatResult
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | string | A key of number formats |
| locale | Locale | A locale, override locale that global scope or local scope |
| args | { \[key: string]: string } | An argument values |

#### Returns

Formatted value

### $n(value, options)

Number formatting

**Signature:**

```typescript
$n(value: number, options: NumberOptions): string;
```

**Details**

Overloaded `$n`. About details, see the [$n](injection#n-value) remarks.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| options | NumberOptions | An options, see the [NumberOptions](general#numberoptions) |

#### Returns

Formatted value

---

---
url: /guide/advanced/component.md
---
# Component Interpolation

## Basic Usage

Sometimes, we need to localize with a locale message that was included in a HTML tag or component. For example:

```html
<p>I accept xxx <a href="/term">Terms of Service Agreement</a></p>
```

In the above message, if you use `$t`, you will probably try to compose the following locale messages:

```js
const messages = {
  en: {
    term1: 'I Accept xxx\'s',
    term2: 'Terms of Service Agreement'
  }
}
```

And your localized template may look like this:

```html
<p>{{ $t('term1') }}<a href="/term">{{ $t('term2') }}</a></p>
```

Output:

```html
<p>I accept xxx <a href="/term">Terms of Service Agreement</a></p>
```

This is very cumbersome, and if you configure the `<a>` tag in a locale message, there is a possibility of XSS vulnerabilities due to localizing with `v-html="$t('term')"`.

You can avoid it using the Translation component (`i18n-t`). For example the below.

Template:

```html
<div id="app">
  <!-- ... -->
  <i18n-t keypath="term" tag="label" for="tos">
    <a :href="url" target="_blank">{{ $t('tos') }}</a>
  </i18n-t>
  <!-- ... -->
</div>
```

JavaScript:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      tos: 'Term of Service',
      term: 'I accept xxx {0}.'
    },
    ja: {
      tos: '利用規約',
      term: '私は xxx の{0}に同意します。'
    }
  }
})

const app = createApp({
  data: () => ({ url: '/term' })
})

app.use(i18n)
app.mount('#app')
```

The following output:

```html
<div id="app">
  <!-- ... -->
  <label for="tos">
    I accept xxx <a href="/term" target="_blank">Term of Service</a>.
  </label>
  <!-- ... -->
</div>
```

About the above example, see the [example](https://github.com/intlify/vue-i18n/blob/master/examples/legacy/components/translation.html)

The children of translation component are interpolated with locale message of `keypath` prop. In the above example,

:::v-pre
`<a :href="url" target="_blank">{{ $t('tos') }}</a>`
:::

Is interpolated with `term` locale message.

In the above example, the component interpolation follows the **list interpolation**. The children of translation component are interpolated by their order of appearance.

You can choose the root node element type by specifying a `tag` prop. If omitted, it defaults to [Fragments](https://v3-migration.vuejs.org/new/fragments.html).

## Slots syntax usage

It’s more convenient to use the named slots syntax. For example the below:

Template:

```html
<div id="app">
  <!-- ... -->
  <i18n-t keypath="info" tag="p">
    <template v-slot:limit>
      <span>{{ changeLimit }}</span>
    </template>
    <template v-slot:action>
      <a :href="changeUrl">{{ $t('change') }}</a>
    </template>
  </i18n-t>
  <!-- ... -->
</div>
```

JavaScript:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      info: 'You can {action} until {limit} minutes from departure.',
      change: 'change your flight',
      refund: 'refund the ticket'
    }
  }
})

const app = createApp({
  data: () => ({
    changeUrl: '/change',
    refundUrl: '/refund',
    changeLimit: 15,
    refundLimit: 30
  })
})

app.use(i18n)
app.mount('#app')
```

Outputs:

```html
<div id="app">
  <!-- ... -->
  <p>
    You can <a href="/change">change your flight</a> until <span>15</span> minutes from departure.
  </p>
  <!-- ... -->
</div>
```

You can also use the following slots shorthand in templates:

```html
<div id="app">
  <!-- ... -->
  <i18n-t keypath="info" tag="p">
    <template #limit>
      <span>{{ changeLimit }}</span>
    </template>
    <template #action>
      <a :href="changeUrl">{{ $t('change') }}</a>
    </template>
  </i18n-t>
  <!-- ... -->
</div>
```

:::warning LIMITATION
:warning: In translation component, slots props are not supported.
:::

### Pluralization Usage

You can use pluralization in Component interpolation by use `plural` prop. For example the below.

Template:

```html
<div id="app">
  <!-- ... -->
  <i18n-t keypath="message.plural" locale="en" :plural="count">
    <template #n>
      <b>{{ count }}</b>
    </template>
  </i18n-t>
  <!-- ... -->
</div>
```

JavaScript:

```js
const { createApp, ref } = Vue
const { createI18n } = VueI18n

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  messages: {
    en: {
      message: {
        plural: 'no bananas | {n} banana | {n} bananas'
      }
    }
  }
})

const app = createApp({
  setup() {
    const count = ref(2)
    return { count }
  }
})
app.use(i18n)
app.mount('#app')
```

The following output:

```html
<div id="app" data-v-app="">
  <!-- ... -->
  <b>2</b> bananas
  <!-- ... -->
</div>
```

## Scope resolving

The [Scope](../essentials/scope.md) resolving of Translation component is `parent` as default.

It means that Translation component uses the scope that is enabled in the parent component that uses it.

If the parent component has `useI18n` in `useScope: 'global'`, it will use Global Scope, else if `useScope: 'local'`, it will use the Local Scope of the parent component.

However, You sometimes meet the warning message on your browser console the following:

```
[intlify] Not found parent scope. use the global scope.
```

This message is displayed in the case that you have not run `useI18n` in the parent component that uses the Translation component.

In that situation, the Scope of the Translation Component will be fallback to the global scope as said the warning message.

A workaround to suppress this warning is to specify `global` as the `scope` property of Translation component.

```html
<i18n-t keypath="message.foo" scope="global">
  ...
</i18n-t>
```

:::tip NOTE
This warning is not output to the browser console in production builds.
:::

:::warning NOTE
This is not available in petite-vue-i18n
:::

---

---
url: /api/component.md
---
# Components

## BaseFormatProps

BaseFormat Props for Components that is offered Vue I18n

**Signature:**

```typescript
export interface BaseFormatProps 
```

**Details**

The interface definitions of the underlying props of components such as Translation, DatetimeFormat, and NumberFormat.

### i18n

**Signature:**

```typescript
i18n?: Composer;
```

**Details**

A composer instance with an existing scope.

This option takes precedence over the `scope` option.

### locale

**Signature:**

```typescript
locale?: Locale;
```

**Details**

Specifies the locale to be used for the component.

If specified, the global scope or the locale of the parent scope of the target component will not be overridden and the specified locale will be used.

### scope

**Signature:**

```typescript
scope?: ComponentI18nScope;
```

**Details**

Specifies the scope to be used in the target component.

You can specify either `global` or `parent`.

If `global` is specified, global scope is used, else then `parent` is specified, the scope of the parent of the target component is used.

If the parent is a global scope, the global scope is used, if it's a local scope, the local scope is used.

### tag

**Signature:**

```typescript
tag?: string | object;
```

**Details**

Used to wrap the content that is distribute in the slot. If omitted, the slot content is treated as Fragments.

You can specify a string-based tag name, such as `p`, or the object for which the component is defined.

## DatetimeFormat

Datetime Format Component

**Signature:**

```typescript
DatetimeFormat: {
    new (): {
        $props: VNodeProps & DatetimeFormatProps & BaseFormatProps;
    };
}
```

**Details**

See the following items for property about details

:::danger
Not supported IE, due to no support `Intl.DateTimeFormat#formatToParts` in [IE](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/formatToParts)

If you want to use it, you need to use [polyfill](https://github.com/formatjs/formatjs/tree/main/packages/intl-datetimeformat)
:::

**See Also**

* [FormattableProps](component#formattableprops)
* [BaseFormatProps](component#baseformatprops)
* [Custom Formatting](../guide/essentials/datetime#custom-formatting)

## DatetimeFormatProps

DatetimeFormat Component Props

**Signature:**

```typescript
export type DatetimeFormatProps = FormattableProps<number | Date, Intl.DateTimeFormatOptions>;
```

## FormattableProps

Formattable Props

**Signature:**

```typescript
export interface FormattableProps<Value, Format> extends BaseFormatProps 
```

**Details**

The props used in DatetimeFormat, or NumberFormat component

### format

**Signature:**

```typescript
format?: string | Format;
```

**Details**

The format to use in the target component.

Specify the format key string or the format as defined by the Intl API in ECMA 402.

### value

**Signature:**

```typescript
value: Value;
```

**Details**

The value specified for the target component

## NumberFormat

Number Format Component

**Signature:**

```typescript
NumberFormat: {
    new (): {
        $props: VNodeProps & NumberFormatProps & BaseFormatProps;
    };
}
```

**Details**

See the following items for property about details

:::danger
Not supported IE, due to no support `Intl.NumberFormat#formatToParts` in [IE](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts)

If you want to use it, you need to use [polyfill](https://github.com/formatjs/formatjs/tree/main/packages/intl-numberformat)
:::

**See Also**

* [FormattableProps](component#formattableprops)
* [BaseFormatProps](component#baseformatprops)
* [Custom Formatting](../guide/essentials/number#custom-formatting)

## NumberFormatProps

NumberFormat Component Props

**Signature:**

```typescript
export type NumberFormatProps = FormattableProps<number, Intl.NumberFormatOptions>;
```

## Translation

Translation Component

**Signature:**

```typescript
Translation: {
    new (): {
        $props: VNodeProps & TranslationProps;
    };
}
```

**Details**

See the following items for property about details

**See Also**

* [TranslationProps](component#translationprops)
* [BaseFormatProps](component#baseformatprops)
* [Component Interpolation](../guide/advanced/component)

**Examples**

```html
<div id="app">
  <!-- ... -->
  <i18n keypath="term" tag="label" for="tos">
    <a :href="url" target="_blank">{{ $t('tos') }}</a>
  </i18n>
  <!-- ... -->
</div>
```

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const messages = {
  en: {
    tos: 'Term of Service',
    term: 'I accept xxx {0}.'
  },
  ja: {
    tos: '利用規約',
    term: '私は xxx の{0}に同意します。'
  }
}

const i18n = createI18n({
  locale: 'en',
  messages
})

const app = createApp({
  data: {
    url: '/term'
  }
}).use(i18n).mount('#app')
```

## TranslationProps

Translation Component Props

**Signature:**

```typescript
export interface TranslationProps extends BaseFormatProps 
```

### keypath

**Signature:**

```typescript
keypath: string;
```

**Details**

The locale message key can be specified prop

### plural

**Signature:**

```typescript
plural?: number | string;
```

**Details**

The Plural Choosing the message number prop

---

---
url: /guide/advanced/composition.md
---
# Composition API

The introduction of `setup` and Vue’s [Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html) opens up new possibilities. But to be able to get the full potential out of Vue I18n, we will need to use a few new functions to replace access to `this`.

We have been describing the features of Vue I18n using the Legacy API, which is compatible with vue-i18n v8.x. Now let’s take a look at Vue I18n `useI18n` for Composition API.

## Basic Usage

Let’s look at the basic usage of Vue I18n Composition API! Here we will learn the basic usage by modifying the code in [Getting Started](../../guide/essentials/started) to learn the basic usage.

To compose with `useI18n` in `setup` of Vue 3, there is one thing you need to do, you need set the `legacy` option of the `createI18n` function to `false`.

The following is an example of adding the `legacy` option to `createI18n`:

```js{4}
// ...

const i18n = VueI18n.createI18n({
  legacy: false, // you must set `false`, to use Composition API // [!code ++]
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: {
      message: {
        hello: 'hello world'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、世界'
      }
    }
  }
})

// ...
```

You can set `legacy: false` to allow Vue I18n to switch the API mode, from Legacy API mode to Composition API mode.

:::tip NOTE
The following properties of i18n instance created by `createI18n` change its behavior:

* `mode` property: `"legacy"` to `"composition"`
* `global` property: VueI18n instance to Composer instance
  :::

You are now ready to use `useI18n` in the `App.vue` component. The code looks like this:

```vue
<script setup> // [!code ++]
import { useI18n } from 'vue-i18n' // [!code ++]
const { t } = useI18n() // [!code ++]
</script> // [!code ++]

<template>
  <h1>{{ $t("message.hello") }}</h1>
</template>
```

You must call `useI18n` at top of the `<script setup>`.

The `useI18n` returns a Composer instance. The Composer instance provides a translation API such as the `t` function, as well as properties such as `locale` and `fallbackLocale`, just like the VueI18n instance. For more information on the Composer instance, see the [API Reference](../../api/composition#composer).

In the above example, there are no options for `useI18n`, so it returns a Composer instance that works with the global scope. As such, it returns a Composer instance that works with the global scope, which means that the localized message referenced by the spread `t` function here is the one specified in `createI18n`.

you can use `t` in the components template:

```vue
<script setup>
import { useI18n } from 'vue-i18n'
const { t } = useI18n()
</script>

<template>
  <h1>{{ $t("message.hello") }}</h1> // [!code --]
  <h1>{{ t("message.hello") }}</h1> // [!code ++]
</template>
```

The output follows:

```vue
<div id="app">
  <h1>こんにちは、世界</h1>
</div>
```

## Message Translation

In the Legacy API mode, the messages were translated using either `$t` or the VueI18n instance of `t`.

In the Composition API mode, the Message Format Syntax remains the same as in the Legacy API mode. You can use the Composer instance `t` to translate a message as follows:

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

const { t } = useI18n({
  locale: 'en',
  messages: {
    en: {
      msg: 'hello',
      named: '{msg} world!',
      list: '{0} world!',
      literal: "{'hello'} world!",
      the_world: 'the world',
      dio: 'DIO:',
      linked: '@:dio @:the_world !!!!'
    },
    ja: {
      msg: 'こんにちは',
      named: '{msg} 世界！',
      list: '{0} 世界！',
      literal: "{'こんにちは'} 世界！",
      the_world: 'ザ・ワールド！',
      dio: 'ディオ:',
      linked: '@:dio @:the_world ！！！！'
    }
  }
})

const msg = computed(() => t('msg'))
</script>

<template>
  <p>{{ t('named', { msg }) }}</p>
  <p>{{ t('list', [msg]) }}</p>
  <p>{{ t('literal') }}</p>
  <p>{{ t('linked') }}</p>
</template>

```

For more details of `t`, see the [API Reference](../../api/composition#t-key).

## Pluralization

In the Composition API mode, the plural form of the message is left in syntax as in the Legacy API mode, but is translated using the `t` of the Composer instance:

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

const { t } = useI18n({
  locale: 'en',
  messages: {
    en: {
      car: 'car | cars',
      apple: 'no apples | one apple | {count} apples',
      banana: 'no bananas | {n} banana | {n} bananas'
    }
  }
})
</script>

<template>
  <h2>Car:</h2>
  <p>{{ t('car', 1) }}</p>
  <p>{{ t('car', 2) }}</p>
  <h2>Apple:</h2>
  <p>{{ t('apple', 0) }}</p>
  <p>{{ t('apple', 1) }}</p>
  <p>{{ t('apple', { count: 10 }, 10) }}</p>
  <p>{{ t('apple', 10) }}</p>
  <h2>Banana:</h2>
  <p>{{ t('banana', { n: 1 }, 1) }}</p>
  <p>{{ t('banana', 1) }}</p>
  <p>{{ t('banana', { n: 'too many' }, 100) }}</p>
</template>
```

:::tip NOTE
In the Composition API mode, plural translations have been integrated into `t`.
:::

## Datetime Formatting

In the Legacy API mode, Datetime value was formatted using `$d` or the VueI18n instance of `d`.

In the Composition API mode, it uses the `d` of the Composer instance to format:

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

const { t, d } = useI18n({
  locale: 'en-US',
  messages: {
    'en-US': {
      current: 'Current Datetime'
    }
  },
  datetimeFormats: {
    'en-US': {
      long: {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit'
      }
    }
  }
})

const now = ref(new Date())
</script>

<template>
  <p>{{ t('current') }}: {{ d(now, 'long') }}</p>
</template>

```

For more details of `d`, see the [API Reference](../../api/composition#d-value).

## Number Formatting

In the Legacy API mode, Number value is formatted using `$n` or the `n` of the VueI18n instance.

In the Composition API mode, it is formatted using the `n` of the Composer instance:

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

const { t, n } = useI18n({
  locale: 'en-US',
  messages: {
    'en-US': {
      money: 'Money'
    }
  },
  numberFormats: {
    'en-US': {
      currency: {
        style: 'currency',
        currency: 'USD'
      }
    }
  }
})

const money = ref(1000)
</script>

<template>
  <p>{{ t('money') }}: {{ n(money, 'currency') }}</p>
</template>
```

For more details of `n`, see the [API Reference](../../api/composition#n-value).

## Global scope

A global scope in the Composition API mode is created when an i18n instance is created with `createI18n`, similar to the Legacy API mode.

While the Legacy API mode `global` property of the i18n instance is the VueI18n instance, the Composition API mode allows you to reference the Composer instance.

There are two ways to refer the global scope Composer instance at the component.

### Explicit with `useI18n`

As we have explained, in `useI18n` is a way.

```ts
import { useI18n } from 'vue-i18n'

const { t } = useI18n({ useScope: 'global' })

// Something to do here ...
```

The above code sets the `useI18n` option to `useScope: 'global'`, which allows `useI18n` to return a Composer instance that can be accessed by the i18n instance `global` property. The Composer instance is a global scope.

Then you can compose using the functions and properties exposed from the Composer instance.

:::tip NOTE
If you set `useI18n` to `messages`, `datetimeFormats`, and `numberFormats` together `useScope: 'global’`, **they will be merged into global scope**. That is, they will be managed by `messages`, `datetimeFormasts`, and `numberFormats` of the global scope Composer instance.

And also, if [`global` is specified in i18n custom blocks](../advanced/sfc#define-locale-messages-for-global-scope) (e.g. `<i18n global>{ … }</i18n>`), the locale messages defined in the blocks are merged with the global scope.
:::

### Implicit with injected properties and functions

Another way to refer a global scope Composer instance is through properties and functions implicitly injected into the component.

You need to specify **`globalInjection: true`** together with `legacy: false` as an option for `createI18n`, because disabled by default.

:::tip NOTE
vue-i18n v9.2-beta.34 or later, `globalInjection` is `true` by default.
:::

This allows Vue I18n to inject the following properties and functions into the components:

* `$i18n`: An object wrapped with the following global scope Composer instance properties
  * `locale`
  * `fallbackLocale`
  * `availableLocales`
* `$t`: `t` function of Composer that is global scope
* `$rt`: `rt` function of Composer that is global scope
* `$d`: `d` function of Composer that is global scope
* `$n`: `n` function of Composer that is global scope
* `$tm`: `tm` function of Composer that is global scope

The Vue 3 runtime globally injects components with what is set in `app.config.globalProperties`. Thus, the ones listed above are injected by the Vue 3 runtime and can therefore be used implicitly in template.

:::warning NOTICE

* The `setup` does not allow to see these properties and functions injected into the component
* In Legacy API mode, some Vue I18n APIs prefixed with `$` were injected, but the properties and functions prefixing components with `$` and injected in Composition API mode are different from the Legacy API mode.
  :::

You’ve noticed that the ones listed above are prefixed with `$`. The reason for prefixing them with `$` is that they are:

* The `setup` does not conflict with the properties and functions returned by render context
* Global scope accessible identifier for Vue I18n Composition API mode

By doing so, the user is made aware that they are special properties and functions.

:::warning NOTICE
If your Vue application doesn't use local scope and does everything i18n in global scope, this is very useful as it does not need to run `useI18n` in the `setup` for each component. However, this way has the problem with global variables of the same nature. You should be used with caution, especially for large Vue applications.

If you use it once and stop using it, you must change all the properties or functions used in the templates to those of the setup context returned with the `setup` using the `useI18n` with `useScope: 'global'` option.
:::

## Local scope

In Legacy API mode, VueI18n instance is created by specifying the `i18n` component option for each component. This enables resources such as local messages managed by VueI18n instance to be local scopes that could be referenced only by the target component.

To enable local scope in the Composition API mode, you need to set an option to `useI18n`, which will create a new instance of Composer based on the given locale, locale messages, etc. When the option is given, `useI18n` creates and returns a new Composer instance based on the locale, locale messages, and other resources specified by the option.

:::tip NOTE
You can explicit specify `useScope: ‘local’` option.
:::

The following example codes:

```js
import { useI18n } from 'vue-i18n'

const { t, d, n, tm, locale } = useI18n({
  locale: 'ja-JP',
  fallbackLocale: 'en-US',
  messages: {
    'en-US': {
      // ....
    },
    'ja-JP': {
      // ...
    }
  },
  datetimeFormats: {
    'en-US': {
      // ....
    },
    'ja-JP': {
      // ...
    }
  },
  numberFormats: {
    'en-US': {
      // ....
    },
    'ja-JP': {
      // ...
    }
  }
})

// Something to do here ...
```

### Implicit `useScope` Resolution

When using `useI18n`, the `useScope` option has implicit resolution behavior that you should be aware of:

:::info Default Behavior
If you don't explicitly specify `useScope`, Vue I18n will implicitly determine the scope based on whether the component has an i18n block:

* **With i18n block**: Defaults to `local` scope
* **Without i18n block**: Defaults to `global` scope
  :::

```js
// In a component WITH i18n block

// This implicitly uses local scope
const { t } = useI18n() // same as useI18n({ useScope: 'local' })


// In a component WITHOUT i18n block (e.g., composables, stores)

// This implicitly uses global scope
const { t } = useI18n() // same as useI18n({ useScope: 'global' })
```

This explicit approach prevents unexpected behavior and makes your code more maintainable.

### Avoiding Multiple useI18n Calls

:::warning IMPORTANT
**Do not call `useI18n` with local scope multiple times within the same component.** When you call `useI18n` with local scope more than once in the same component, it will not work properly and Vue I18n will emit a warning.
:::

#### Bad: Multiple calls to useI18n with local scope

```js
export default {
  setup() {
    // First call - creates a new Composer instance
    const { t } = useI18n({
      locale: 'en',
      messages: {
        en: { hello: 'Hello' },
        ja: { hello: 'こんにちは' }
      }
    })

    // Second call - creates another Composer instance (triggers warning)
    const { locale } = useI18n({
      locale: 'en',
      messages: {
        en: { world: 'World' },
        ja: { world: '世界' }
      }
    })

    // These instances are not synchronized!
    return { t, locale }
  }
}
```

#### Good: Single call to useI18n

```js
export default {
  setup() {
    // Destructure all needed properties from a single call
    const { t, locale, tm, d, n } = useI18n({
      locale: 'en',
      messages: {
        en: {
          hello: 'Hello',
          world: 'World'
        },
        ja: {
          hello: 'こんにちは',
          world: '世界'
        }
      }
    })

    return { t, locale }
  }
}
```

When you violate this rule, you'll see the following warning in development mode:

```
[Vue I18n warn]: Duplicate `useI18n` calling by local scope. Please don't call it on local scope, due to it does not work properly in component.
```

If you need to use i18n features in multiple places within your component, destructure all the needed properties from a single `useI18n` call or store the returned object and access its properties as needed.

### Locale messages

If you use i18n custom blocks in SFC as i18n resource of locale messages, it will be merged with the locale messages specified by the `messages` option of `useI18n`.

The following is an example of using i18n custom blocks and `useI18n` options:

```vue
<script setup>
import { useI18n } from 'vue-i18n'
import en from './en.json'

const { t, availableLocales, getLocaleMessages } = useI18n({
  locale: 'en',
  messages: {
    en
  }
})

availableLocales.forEach(locale => {
  console.log(`${locale} locale messages`, getLocaleMessages(locale))
})
</script>

<i18n locale="ja">
{
  "hello": "こんにちは！"
}
</i18n>
```

:::tip NOTE
In this example, the definition of resources is separated from i18n custom blocks and the `messages` option of `useI18n`, but in local scope, resource messages are specified in the `messages` option in a lump sum for administrative purposes in resource messages or define all resource messages in the i18n custom blocks, which is preferable.
:::

### Shared locale messages for components

In Legacy API mode, shared locale messages are used in components with the `sharedMessages` option.

In composition API mode, use `mergeLocaleMessage` exported by `useI18n`.

Common locale messages example:

```js
export default {
  en: {
    buttons: {
      save: "Save",
      // ...
    }
  },
  ja: {
    buttons: {
      save: "保存",
      // ...
    }
  }
}
```

use `mergeLocaleMessage` on Components:

```vue
<script setup>
import { useI18n } from 'vue-i18n'
import commonMessages from './locales/common'

const { t, mergeLocaleMessage } = useI18n({
  locale: 'en',
  messages: {
    en: {
      hello: 'Hello!'
    },
    ja: {
      hello: 'こんにちは！'
    }
  }
})

for (const locale of ['en', 'ja']) {
  mergeLocaleMessage(locale, commonMessages[locale])
}
</script>
```

## Locale Changing

### Global Scope

You want to change the locale with `<script setup>`, just get a global Composer with `useI18n` and change it using the `locale` property of the instance.

```vue
<script setup>
const { t, locale } = useI18n({ useScope: 'global' })

locale.value = 'en' // change!
</script>
```

And you can also use the setup context in the template, which can be changed as follows:

```vue
<select v-model="locale">
  <option value="en">en</option>
  <option value="ja">ja</option>
</select>
```

When you change the locale of the global scope, components that depend on the global scope, such as `t` translation API can work reactively and switch the display messages to those of the target locale.

If you are using the [implicit way](composition#implicit-with-injected-properties-and-functions), you can also change it in template with `$i18n.locale`, as follows:

```vue
<select v-model="$i18n.locale">
  <option value="en">en</option>
  <option value="ja">ja</option>
</select>
```

### Local Scope

The local scope locales, that is, the  Composer instance `locale` property returned by `useI18n`, are inherited from the global scope, as is the Legacy API. Therefore, when you change the locale at global scope, the inherited local scope locale is also changed. If you want to switch the locale for the whole application, you can use the `locale` returned by `useI18n({ useScope: 'global' })` or, if you use [implicit way](composition#implicit-with-injected-properties-and-functions), you can use `$i18n.locale`.

:::tip NOTE
If you do not want to inherit the locale from the global scope, the `inheritLocale` option of `useI18n` must be `false`.
:::

:::warning NOTICE
Changes to the `locale` at the local scope have **no effect on the global scope locale, but only within the local scope**.
:::

## Isolated scope

:::tip NOTE
Isolated scope is supported from v11.4 onwards. Available in **Composition API mode only** (`legacy: false`).
:::

The isolated scope creates an independent Composer instance that is **not tied to the component**. This is useful when you want to use `useI18n` inside a composable with its own translation messages, without conflicting with the component's local scope.

### Why isolated scope?

When a component and a composable both call `useI18n` with local scope, the second call conflicts with the first because only one local scope per component is allowed. The isolated scope solves this by creating a Composer that:

* Is **not registered** with the component (no duplicate detection)
* Does **not propagate** to child components
* Does **not merge** SFC i18n custom blocks
* **Inherits locale** from the parent/global scope (by default)
* **Falls back** to the parent/global scope for missing translation keys

### Usage in composables

```ts
// useProjectStatus.ts
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'

export function useProjectStatus(project) {
  const { t } = useI18n({
    useScope: 'isolated',
    messages: {
      en: { active: 'Active', inactive: 'Inactive' },
      ja: { active: '稼働中', inactive: '停止中' }
    }
  })

  return computed(() => project.isActive ? t('active') : t('inactive'))
}
```

```vue
<!-- MyComponent.vue -->
<script setup>
import { useI18n } from 'vue-i18n'
import { useProjectStatus } from './useProjectStatus'

// Local scope for the component
const { t } = useI18n({
  messages: {
    en: { title: 'Project Dashboard' },
    ja: { title: 'プロジェクトダッシュボード' }
  }
})

// Composable with isolated scope — no conflict!
const status = useProjectStatus(project)
</script>

<template>
  <h1>{{ t('title') }}</h1>
  <p>{{ status }}</p>
</template>
```

:::tip NOTE
The isolated scope inherits locale from the global scope by default. When the global locale changes, the isolated scope's locale is automatically updated. You can disable this behavior by setting `inheritLocale: false`.
:::

:::warning NOTICE
Isolated scope requires Composition API mode (`legacy: false`). Calling `useI18n({ useScope: 'isolated' })` in Legacy API mode throws an error.
:::

## Mapping between VueI18n instance and Composer instance

The API offered by the Composer instance in the Composition API is very similar interface to the API provided by the VueI18n instance.

:::tip MEMO
Internally, the VueI18n instance of the Legacy API mode works by wrapping the Composer instance.
For this reason, the performance overhead is less in the Composition API mode than in the Legacy API mode.
:::

Below is the mapping table:

| VueI18n instance  | Composer instance       |
| ----------------- | ----------------------- |
| `id` | `id` |
| `locale` | `locale` |
| `fallbackLocale` | `fallbackLocale` |
| `availableLocales` | `availableLocales` |
| `messages` | `messages` |
| `datetimeFormats` | `datetimeFormats` |
| `numberFormats` | `numberFormats` |
| `modifiers` | `modifiers` |
| `missing` | `getMissingHandler` / `setMissingHandler` |
| `postTranslation` | `getPostTranslationHandler` / `setPostTranslationHandler`|
| `silentTranslationWarn` | `missingWarn` |
| `silentFallbackWarn` | `fallbackWarn` |
| `formatFallbackMessages` | `fallbackFormat` |
| `sync` | `inheritLocale` |
| `warnHtmlInMessage` | `warnHtmlMessage` |
| `escapeParameterHtml` | `escapeParameter` |
| `t` | `t` |
| `tc` | `t` |
| `te` | `te` |
| `tm` | `tm` |
| `getLocaleMessage` | `getLocaleMessage` |
| `setLocaleMessage` | `setLocaleMessage`|
| `mergeLocaleMessage` | `mergeLocaleMessage` |
| `d` | `d` |
| `getDateTimeFormat` | `getDateTimeFormat` |
| `setDateTimeFormat` | `setDateTimeFormat` |
| `mergeDateTimeFormat` | `mergeDateTimeFormat` |
| `n` | `n` |
| `getNumberFormat` | `getNumberFormat` |
| `setNumberFormat` | `setNumberFormat` |
| `mergeNumberFormat` | `mergeNumberFormat` |

---

---
url: /api/composition.md
---
# Composition API

## Composer

Composer interfaces

**Signature:**

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

**Details**

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

### availableLocales

**Signature:**

```typescript
readonly availableLocales: Locales[];
```

**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<FallbackLocales<Locales>>;
```

**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<Locales>;
```

**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<VueMessageType>;
```

**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<Locales>;
```

**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<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;
```

#### 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<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;
```

#### 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<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;
```

#### 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<VueMessageType> | null;
```

**See Also**

* [missing](composition#posttranslation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |

#### Returns

### mergeDateTimeFormat(locale, format)

Merge datetime format

**Signature:**

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

#### 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<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;
```

#### 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<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;
```

#### 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<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;
```

#### 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<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;
```

#### 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<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;
```

#### 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<VueMessageType> | 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<Str extends string, Key extends PickupKeys<Messages> = PickupKeys<Messages>>(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`, but not those of its fallback locales.

If you did not specify `locale`, check the locale messages of the current `locale` and then those of its fallback locales, as `t` does (see [fallbacking](../guide/essentials/fallback)).

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

### tm(key)

Locale messages getter

**Signature:**

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

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

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

**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: OptionsType): IsPart\<OptionsType> extends true ? Intl.DateTimeFormatPart\[] : string;

Datetime formatting

**Signature:**

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

**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 | OptionsType | A key of datetime formats, or additional  for datetime formatting |

#### Returns

Formatted value

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

Datetime formatting

**Signature:**

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

**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 | OptionsType | 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<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> 
```

**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: OptionsType): IsPart\<OptionsType> extends true ? Intl.NumberFormatPart\[] : string;

Number Formatting

**Signature:**

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

**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 | OptionsType | A key of number formats, or additional  for number formatting |

#### Returns

Formatted value

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

Number Formatting

**Signature:**

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

**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 | OptionsType | 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<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>> 
```

**Details**

This is options to create composer.

### datetime

### datetimeFormats

### escapeParameter

**Signature:**

```typescript
escapeParameter?: boolean;
```

**Details**

Whether to escape parameters for list or named interpolation values. When enabled, this option: - Escapes HTML special characters (`<`, `>`, `"`, `'`, `&`, `/`, `=`) in interpolation parameters - Sanitizes the final translated HTML to prevent XSS attacks by: - Escaping dangerous characters in HTML attribute values - Neutralizing event handler attributes (onclick, onerror, etc.) - Disabling javascript: URLs in href, src, action, formaction, and style attributes

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.

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 - Using the escapeParameter option](../guide/essentials/syntax#using-the-escapeparameter-option)

### 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({
  legacy: false,
  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({
  legacy: false,
  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<VueMessageType>;
```

**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<VueMessageType>;
```

**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<Locales = 'en-US'> 
```

**Details**

This is the interface for [Composer](composition#composer)

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

Resolve locale message translation

**Signature:**

```typescript
(message: MessageFunction<VueMessageType> | 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> | VueMessageType, plural: number, options?: TranslateOptions<Locales>): 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> | VueMessageType, list: unknown[], options?: TranslateOptions<Locales>): 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> | VueMessageType, named: NamedValue, options?: TranslateOptions<Locales>): 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<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> 
```

**Details**

This is the interface for [Composer](composition#composer)

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

Locale message translation

**Signature:**

```typescript
<Key extends string>(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 extends string>(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 extends string>(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 extends string>(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 extends string>(key: Key | ResourceKeys | number, named: NamedValue, options: TranslateOptions<Locales>): 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 extends string>(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 extends string>(key: Key | ResourceKeys | number, plural: number, options: TranslateOptions<Locales>): 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 extends string>(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 extends string>(key: Key | ResourceKeys | number, defaultMsg: string, options: TranslateOptions<Locales>): 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 extends string>(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 extends string>(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 extends string>(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 extends string>(key: Key | ResourceKeys | number, list: unknown[], options: TranslateOptions<Locales>): 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 | GenericComponentInstance, 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<Schema, VueMessageType>, LocaleParams<Locales>> = UseI18nOptions<SchemaParams<Schema, VueMessageType>, LocaleParams<Locales>>>(options?: Options): Composer<NonNullable<Options['messages']>, NonNullable<Options['datetimeFormats']>, NonNullable<Options['numberFormats']>, NonNullable<Options['locale']>>;
```

### 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
<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:**

```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<Schema, Locales> = 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;
```

---

---
url: /guide/advanced/directive.md
---
# Custom Directive

:::danger NOTE
`v-t` will be deprecated at v11, and will be dropped at v12. This section is for those who are still using v10.
:::

You can translate not only with `$t`, but also with the `v-t` custom directive.

## String syntax

You can pass the keypath of locale messages with string syntax.

Javascript:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: { hello: 'hi there!' },
    ja: { hello: 'こんにちは！' }
  }
})

const app = createApp({
  data: () => ({ path: 'hello' })
})
app.use(i18n)
app.mount('#app')
```

Templates:

```html
<div id="string-syntax">
  <!-- string literal -->
  <p v-t="'hello'"></p>
  <!-- keypath binding via data -->
  <p v-t="path"></p>
</div>
```

Outputs:

```html
<div id="string-syntax">
  <p>hi there!</p>
  <p>hi there!</p>
</div>
```

## Object syntax

You can use object syntax.

Javascript:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hi: 'Hi, {name}!',
        bye: 'good bye!',
        apple: 'no apples | one apple | {count} apples'
      }
    },
    ja: {
      message: {
        hi: 'こんにちは、 {name}！',
        bye: 'さようなら！',
        apple: 'リンゴはありません | 一つのりんご | {count} りんご'
      }
    }
  }
})

const app = createApp({
  data() {
    return {
      byePath: 'message.bye',
      appleCount: 7,
    }
  }
})
app.use(i18n)
app.mount('#object-syntax')
```

Templates:

```html
<div id="object-syntax">
  <!-- literal -->
  <p v-t="{ path: 'message.hi', args: { name: 'kazupon' } }"></p>
  <!-- data binding via data -->
  <p v-t="{ path: byePath, locale: 'en' }"></p>
  <!-- pluralization -->
  <p v-t="{ path: 'message.apple', plural: appleCount }"></p>
</div>
```

Outputs:

```html
<div id="object-syntax">
  <p>こんにちは、 kazupon！</p>
  <p>good bye!</p>
  <p>7 りんご</p>
</div>
```

## scoping

As mentioned in [the scope section](../essentials/scope.md), vue-i18n has a global scope and a local scope.

The scope under which `v-t` is also affected by scope when it works.

* local scope: using the i18n option in Legacy API style or using `useScope: ‘local'` in `useI18n`.
* global scope: all cases other than the above.

## `$t` vs `v-t`

### `$t`

`$t` is function of VueI18n instance. It has the following pros and cons:

#### Pros

You can **flexibly** use mustache syntax `{}` in templates and also computed props and methods in Vue component instance.

#### Cons

`$t` is executed **every time** when re-render occurs, so it does have translation costs.

### `v-t`

`v-t` is a custom directive. It has the following pros and cons:

#### Pros

`v-t` has **better performance** than the `$t` function due to its pre-translation is possible with the Vue compiler module which was provided by [vue-i18n-extensions](https://github.com/intlify/vue-i18n-extensions).

Therefore it’s possible to make **more performance optimizations**.

#### Cons

`v-t` cannot be flexibly used like `$t`, it’s rather **complex**. The translated content with `v-t` is inserted into the `textContent` of the element. Also, when you use server-side rendering, you need to set the [custom transform](https://github.com/intlify/vue-i18n-extensions#server-side-rendering-for-v-t-custom-directive) to `directiveTransforms` option of the `compile` function of `@vue/compiler-ssr`.

---

---
url: /guide/advanced/format.md
---
# Custom Message Format

:::tip Supported Versions
:new: 9.3+
:::

[As described in the message format syntax](../essentials/syntax), Vue I18n message format is original.

If you want to use a message format like ICU Message Format, you can use a custom format by implementing the message compiler yourself.

:::warning
This topic requires understanding Vue I18n message format compilation and how formats are resolved.
:::

:::warning
The feature is experimental. It may receive breaking changes or be removed in the future.
:::

## Message Compiler implementation

You can make a message compiler by implementing functions with the following interfaces.

The following is a TypeScript type definition:

```js
export declare type MessageCompiler<Message = string, MessageSource = string | ResourceNode> = (message: MessageSource, context: MessageCompilerContext) => MessageFunction<Message>;
```

The following is an example of a message compiler implementation that uses [`intl-messageformat`](https://formatjs.io/docs/intl-messageformat/) to support the ICU Message format.

```ts
import IntlMessageFormat from 'intl-messageformat'

import type { MessageCompiler, CompileError, MessageContext } from 'vue-i18n'

export const messageCompiler: 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: MessageContext) => {
      return formatter.format(ctx.values)
    }
  } else {
    /**
     * for AST.
     * If you would like to support it,
     * You need to transform locale messages such as `json`, `yaml`, etc. with the bundle plugin.
     */
    onError && onError(new Error('not support for AST') as CompileError)
    return () => key
  }
}
```

## Message compiler registration

After implementing message compiler, set the `messageCompiler` option of `createI18n` as follows, and you can use your message format for the `messages` option:

```ts
import { createI18n } from 'vue-i18n'
import { messageCompiler } from './compilation'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  messageCompiler,
  messages: {
    en: {
      hello: 'hello world!',
      greeting: 'hi, {name}!',
      photo: `You have {numPhotos, plural,
        =0 {no photos.}
        =1 {one photo.}
        other {# photos.}
      }`
    }
  }
})

// the below your something to do ...
// ...
```

## Reference

In implementing the message compiler, we recommend you would read and understand the [compilation codes](https://github.com/intlify/vue-i18n/blob/master/packages/core-base/src/compilation.ts)

:::info
You can get the code for the tutorial below on [examples/message-format](https://github.com/intlify/vue-i18n/tree/master/examples/message-format).
:::

---

---
url: /guide/essentials/datetime.md
---
# Datetime Formatting

## Basic Usage

You can localize the datetime with your definition formats.

Datetime formats the below:

```js
const datetimeFormats = {
  'en-US': {
    short: {
      year: 'numeric', month: 'short', day: 'numeric'
    },
    long: {
      year: 'numeric', month: 'short', day: 'numeric',
      weekday: 'short', hour: 'numeric', minute: 'numeric'
    }
  },
  'ja-JP': {
    short: {
      year: 'numeric', month: 'short', day: 'numeric'
    },
    long: {
      year: 'numeric', month: 'short', day: 'numeric',
      weekday: 'short', hour: 'numeric', minute: 'numeric', hour12: true
    }
  }
}
```

As seen above, you can define named datetime format (e.g. `short`, `long`, etc), and you need to use [the options with ECMA-402 Intl.DateTimeFormat](https://tc39.es/ecma402/#datetimeformat-objects)

After that, when using the locale messages, you need to specify the `datetimeFormats` option of `createI18n`:

```js
const i18n = createI18n({
  datetimeFormats
})
```

To localize DateTime value with Vue I18n, use the `$d`.

:::warning NOTICE
Note that the option name is **`datetimeFormats`** in VueI18n v9, not `dateTimeFormats`. about see details [here](../../guide/migration/breaking#rename-to-datetimeformats-from-datetimeformats)
:::

:::tip NOTE
`$d` has some overloads. About these overloads, see the [API Reference](../../api/injection#d-value)
:::

:::tip NOTE
Some ways to support localize are:

* `$d` (for Legacy API mode & Composition API mode)
* built-in DatetimeFormat component (`i18n-d`)
* exported `d` from `useI18n` (for Composition API mode)
  :::

The following is an example of the use of `$d` in a template:

```html
<p>{{ $d(new Date(), 'short') }}</p>
<p>{{ $d(new Date(), 'long', 'ja-JP') }}</p>
```

The first argument is datetime able value (e.g. `Date`, timestamp) as a parameter, and the second argument is datetime format name as a parameter. The last argument locale value as a parameter.

As result the below:

```html
<p>Apr 19, 2017</p>
<p>2017年4月19日(水) 午前2:19</p>
```

## Custom Formatting

`$d` returns resulting string with fully formatted datetime, which can only be used as a whole. In situations when you need to style some part of the formatted datetime (like fraction digits), `$d` is not enough. In such cases DatetimeFormat component (`i18n-d`) will be of help.

With a minimum set of properties, `i18n-d` generates the same output as `$d`, wrapped into configured DOM element.

The following template:

```html
<i18n-d tag="p" :value="new Date()"></i18n-d>
<i18n-d tag="p" :value="new Date()" format="long"></i18n-d>
<i18n-d tag="p" :value="new Date()" format="long" locale="ja-JP-u-ca-japanese"></i18n-d>
```

DatetimeFormat component has some props.

The `tag` is the property to set the tag.

The `value` prop is a property to set the datetime able value to be formatted.

The `format` prop is a property to which the format defined by the `datetimeFormats` option of `createI18n` can be set.

The `locale` prop is a property to set the locale. It's localized with the locale specified by this prop instead of the one specified with the `locale` option of `createI18n`.

Will produce the below output:

```html
<p>11/3/2020</p>
<p>11/03/2020, 02:35:31 AM</p>
<p>令和2年11月3日火曜日 午前2:35:31 日本標準時</p>
```

But the real power of this component comes into play when it is used with [scoped slots](https://v3.vuejs.org/guide/component-slots.html#scoped-slots).

Let’s say there is a requirement to render the era part of the datetime with a bolder font. This can be achieved by specifying `era` scoped slot element:

```html
<i18n-d tag="span" :value="new Date()" locale="ja-JP-u-ca-japanese" :format="{ key: 'long', era: 'narrow' }">
  <template #era="props">
    <span style="color: green">{{ props.era }}</span>
  </template>
</i18n-d>
```

Template above will result in the following HTML:

```html
<span><span style="color: green;">R</span>2年11月3日火曜日 午前2:35:31 日本標準時</span>
```

It is possible to specify multiple scoped slots at the same time:

```html
<i18n-d tag="span" :value="new Date()" locale="ja-JP-u-ca-japanese" :format="{ key: 'long', era: 'narrow' }">
  <template #era="props">
    <span style="color: green">{{ props.era }}</span>
  </template>
  <template #literal="props">
    <span style="color: green">{{ props.literal }}</span>
  </template>
</i18n-d>
```

(this resulting HTML was formatted for better readability)

```html
<span>
  <span style="color: green;">R</span>2
  <span style="color: green;">年</span>11
  <span style="color: green;">月</span>3
  <span style="color: green;">日</span>火曜日
  <span style="color: green;"> </span>午前3
  <span style="color: green;">:</span>09
  <span style="color: green;">:</span>56
  <span style="color: green;"> </span>日本標準時
</span>
```

:::tip NOTE
Full list of the supported scoped slots as well as other `i18n-d`, properties can be found on [API Reference](../../api/component.html#datetimeformat).
:::

## Scope resolving

The Scope resolving of DatetimeFormat component is same as Translation component.

See the [here](../advanced/component.md#scope-resolving)

---

---
url: /guide/extra/dist.md
---
# Different Distribution files

In the [dist/ directory of the npm package](https://cdn.jsdelivr.net/npm/vue-i18n@9.1.10/dist/) you will find many different builds of Vue I18n. Here is an overview of which dist file should be used depending on the use-case.

## From CDN or without a Bundler

* **`vue-i18n(.runtime).global(.prod).js`**:
  * For direct use via `<script src="...">` in the browser. Exposes the `VueI18n` global
  * In-browser message format compilation:
    * `vue-i18n.global.js` is the "full" build that includes both the compiler and the runtime so it supports compiling message formats on the fly
    * `vue-i18n.runtime.global.js` contains only the runtime and requires message formats to be pre-compiled during a build step
  * Inlines all Vue I18n core internal packages - i.e. it’s a single file with no dependencies on other files. This means you **must** import everything from this file and this file only to ensure you are getting the same instance of code
  * Contains hard-coded prod/dev branches, and the prod build is pre-minified. Use the `*.prod.js` files for production

:::tip NOTE
Global builds are not [UMD](https://github.com/umdjs/umd) builds. They are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) and are only meant for direct use via `<script src="...">`.
:::

* **`vue-i18n(.runtime).esm-browser(.prod).js`**:
  * For usage via native ES modules imports (in browser via `<script type="module">`)
  * Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build

## With a Bundler

* **`vue-i18n(.runtime).esm-bundler.js`**:
  * For use with bundlers like `webpack`, `rollup` and `parcel`
  * Leaves prod/dev branches with `process.env``.NODE_ENV` guards (must be replaced by bundler)
  * Does not ship minified builds (to be done together with the rest of the code after bundling)
  * Imports dependencies (e.g. `@intlify/core-base`, `@intlify/message-compiler`)
    * Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@intlify/message-compiler` imports `@intlify/shared`)
    * This means you **can** install/import these deps individually without ending up with different instances of these dependencies, but you must make sure they all resolve to the same version
  * In-browser locale messages compilation:
    * **`vue-i18n.runtime.esm-bundler.js`** is runtime only, and requires all locale messages to be pre-compiled. This is the default entry for bundlers (via `module` field in `package.json`) because when using a bundler templates are typically pre-compiled (e.g. in `*.json` files)
    * **`vue-i18n.esm-bundler.js` (default)**: includes the runtime compiler. Use this if you are using a bundler but still want locale messages compilation (e.g. templates via inline JavaScript strings).  To use this build, change your import statement to: `import { createI18n } from "vue-i18n/dist/vue-i18n.esm-bundler.js";`

:::tip NOTE
If you use `vue-i18n.runtime.esm-bundler.js`, you will need to precompile all locale messages, and you can do that with `.json` (`.json5`) or `.yaml`, i18n custom blocks to manage i18n resources. Therefore, you can be going to pre-compile all locale messages with bundler and the following loader / plugin.

* [`@intlify/unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n)
  :::

## For Node.js (Server-Side)

* **`vue-i18n.cjs(.prod).js`**:
  * For CommonJS usage in Node.js
  * For use in Node.js via `require()`
  * If you bundle your app with webpack with `target: 'node'` and properly externalize `vue-i18n`, this is the build that will be loaded
  * The dev/prod files are pre-built, but the appropriate file is automatically required based on `process.env``.NODE_ENV`

:::tip Support Version
:new: 9.3+
:::

* **`vue-i18n(.runtime).node.mjs`**:
  * For ES Modules usage in Node.js
  * For use in Node.js via `import`
  * The dev/prod files are pre-built, but the appropriate file is automatically required based on `process.env``.NODE_ENV`
  * This module is proxy module of `vue-i18n(.runtime).mjs`
    * **`vue-i18n.runtime.node.mjs`**: is runtime only.
    * **`vue-i18n.node.mjs`**: includes the runtime compiler.

:::tip NOTE
ES Modules will be the future of the Node.js module system. The `vue-i18n.cjs(.prod).js` will be deprecated in the future. We recommend you would use `vue-i18n(.runtime).node.mjs`.
:::

---

---
url: /api/directive.md
---
# Directives

## TranslationDirective

Translation Directive (`v-t`)

**Signature:**

```typescript
export type TranslationDirective<T = HTMLElement> = ObjectDirective<T>;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

Update the element `textContent` that localized with locale messages.

You can use string syntax or object syntax.

String syntax can be specified as a keypath of locale messages.

If you can be used object syntax, you need to specify as the object key the following params

```
- path: required, key of locale messages
- locale: optional, locale
- args: optional, for list or named formatting
```

**Examples**

```html
<!-- string syntax: literal -->
<p v-t="'foo.bar'"></p>

<!-- string syntax: binding via data or computed props -->
<p v-t="msg"></p>

<!-- object syntax: literal -->
<p v-t="{ path: 'hi', locale: 'ja', args: { name: 'kazupon' } }"></p>

<!-- object syntax: binding via data or computed props -->
<p v-t="{ path: greeting, args: { name: fullName } }"></p>
```

---

---
url: /guide/extra/v8-docs.md
---
# Documentation for v8.x

* [Introduction](https://github.com/intlify/vue-i18n/blob/master/docs-old/introduction.md)
* [Getting started](https://github.com/intlify/vue-i18n/blob/master/docs-old/started.md)
* [Installation](https://github.com/intlify/vue-i18n/blob/master/docs-old/installation.md)
* Guide
  * [Formatting](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/formatting.md)
  * [Pluralization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/pluralization.md)
  * [DateTime localization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/datetime.md)
  * [Number localization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/number.md)
  * [Locale messages syntax](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/messages.md)
  * [Fallback localization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/fallback.md)
  * [Component based localization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/component.md)
  * [Custom directive localization](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/directive.md)
  * [Component interpolation](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/interpolation.md)
  * [Single file components](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/sfc.md)
  * [Hot reloading](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/hot-reload.md)
  * [Locale changing](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/locale.md)
  * [Lazy loading translations](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/lazy-loading.md)
  * [Tooling](https://github.com/intlify/vue-i18n/blob/master/docs-old/guide/tooling.md)
* [API references](https://github.com/intlify/vue-i18n/blob/master/docs-old/api/README.md)

---

---
url: /guide/essentials/fallback.md
---
# Fallbacking

`fallbackLocale: '<lang>'` to choose which language to use when your preferred language lacks a translation.

## Implicit fallback using locales

If a `locale` is given containing a territory and an optional dialect, the implicit fallback is activated automatically.

For example `de-DE-bavarian` would fallback

1. `de-DE-bavarian`
2. `de-DE`
3. `de`

Vue I18n splits the locale at `-`, so specify it as a BCP 47 language tag. For example, `pt_BR` does not fall back to `pt`.

To suppress the automatic fallback, add the postfix exclamation mark `!`, for example `de-DE!`

## Explicit fallback with one locale

Sometimes some items will not be translated into some languages. In this example, the item `hello` is available in English but not Japanese:

```js
const messages = {
  en: {
    hello: 'Hello, world!'
  },
  ja: {
  }
}
```

If you want to use (say) `en` items when an item is not available in your desired locale, set the `fallbackLocale` option in the `createI18n`:

```js
const i18n = createI18n({
  locale: 'ja',
  fallbackLocale: 'en',
  messages
})
```

Template:

```html
<p>{{ $t('hello') }}</p>
```

Output:

```html
<p>Hello, world!</p>
```

By default, falling back to `fallbackLocale` generates two console warnings:

```
[intlify] Not found 'hello' key in 'ja' locale messages.
[intlify] Fall back to translate 'hello' key with 'en' locale.
```

The first warning message is printed the key, due to  given to the translation function `$t` is not in the `ja` locale messages and the second warning message that comes out when you fall back to resolve localized messages from `en` locale messages. These warning messages are output to support debugging using Vue I18n.

:::tip NOTE
These warning messages are only warned in development mode (`process.env``.NODE_ENV !== 'production'`) by default, not for production.
:::

To suppress the first warning(`Not found key...`), set `silentTranslationWarn: true` in Legacy API mode or set `missingWarn: false` in Composition API mode when initializing the `createI18n`.

To suppress the second warning(`Fall back to...`), set `silentFallbackWarn: true` in Legacy API mode or set `fallbackWarn: false` in Composition API mode when initializing the `createI18n`.

## Explicit fallback with an array of locales

It is possible to set more than one fallback locale by using an array of locales. For example

```javascript
fallbackLocale: [ 'fr', 'en' ],
```

## Explicit fallback with decision maps

If more complex decision maps for fallback locales are required, it is possible to define decision maps with according fallback locales.

Using the following decision map:

```javascript
fallbackLocale: {
  /* 1 */ 'de-CH':   ['fr', 'it'],
  /* 2 */ 'zh-Hant': ['zh-Hans'],
  /* 3 */ 'es-CL':   ['es-AR'],
  /* 4 */ 'es':      ['en-GB'],
  /* 5 */ 'pt':      ['es-AR'],
  /* 6 */ 'default': ['en', 'da']
},
```

Will result in the following fallback chains:

| locale | fallback chains |
|--------|-----------------|
| `'de-CH'`   | de-CH > fr > it > en > da |
| `'de'`      | de > en > da |
| `'zh-Hant'` | zh-Hant > zh-Hans > zh > en > da |
| `'es-SP'`   | es-SP > es > en-GB > en > da |
| `'es-SP!'`  | es-SP > en > da |
| `'fr'`      | fr > en > da |
| `'pt-BR'`   | pt-BR > pt > es-AR > es > en-GB > en > da |
| `'es-CL'`   | es-CL > es-AR > es > en-GB > en > da |

## Fallback interpolation

Set `formatFallbackMessages: true` to do template interpolation on translation keys when your language lacks a translation for a key.

Since the keys to the translations are strings, you can use a user-readable message (for a particular language) as a key.
E.g.

```javascript
const messages = {
  ja: {
    'Hello, world!': 'こんにちは、世界!'
  }
}
```

This is useful because you don’t have to specify a translation for the string "Hello, world!" into English.

In fact, you can even include template parameters in a key. Together with `formatFallbackMessages: true`, this lets you skip writing templates for your "base" language; the keys *are* your templates.

```javascript
const messages = {
  ru: {
    'Hello {name}': 'Здравствуйте {name}'
  }
}

const i18n = createI18n({
  locale: 'ru',
  fallbackLocale: 'en',
  formatFallbackMessages: true,
  messages
})
```

When the template is as below:

```html
<p>{{ $t('Hello {name}', { name: 'John' }) }}</p>
<p>{{ $t('The weather today is {condition}!', { condition: 'sunny' }) }}</p>
```

The following will be output:

```html
<p>Здравствуйте, John</p>
<p>The weather today is sunny!</p>
```

---

---
url: /api/general.md
---
# General

## createI18n

Vue I18n factory

**Signature:**

```typescript
export declare function createI18n<Schema extends object = DefaultLocaleMessageSchema, Locales extends string | object = 'en-US', Legacy extends boolean = true, Options extends I18nOptions<SchemaParams<Schema, VueMessageType>, LocaleParams<Locales>> = I18nOptions<SchemaParams<Schema, VueMessageType>, LocaleParams<Locales>>, Messages extends Record<string, unknown> = NonNullable<Options['messages']> extends Record<string, unknown> ? NonNullable<Options['messages']> : {}, DateTimeFormats extends Record<string, unknown> = NonNullable<Options['datetimeFormats']> extends Record<string, unknown> ? NonNullable<Options['datetimeFormats']> : {}, NumberFormats extends Record<string, unknown> = NonNullable<Options['numberFormats']> extends Record<string, unknown> ? NonNullable<Options['numberFormats']> : {}, OptionLocale = Options['locale'] extends string ? Options['locale'] : Locale>(options: Options): (typeof options)['legacy'] extends true ? I18n<Messages, DateTimeFormats, NumberFormats, OptionLocale, true> : (typeof options)['legacy'] extends false ? I18n<Messages, DateTimeFormats, NumberFormats, OptionLocale, false> : I18n<Messages, DateTimeFormats, NumberFormats, OptionLocale, Legacy>;
```

### Type Parameters

| Parameter | Description |
| --- | --- |
| Schema | The i18n resources (messages, datetimeFormats, numberFormats) schema, default  |
| Locales | The locales of i18n resource schema, default `en-US` |
| Legacy | Whether legacy mode is enabled or disabled, default `true` |

**Details**

If you use Legacy API mode, you need to specify [VueI18nOptions](legacy#vuei18noptions) and `legacy: true` option.

If you use composition API mode, you need to specify [ComposerOptions](composition#composeroptions).

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

**Example 1:**

case: for Legacy API

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

// call with I18n option
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: { ... },
    ja: { ... }
  }
})

const App = {
  // ...
}

const app = createApp(App)

// install!
app.use(i18n)
app.mount('#app')
```

**Example 2:**

case: for composition API

```js
import { createApp } from 'vue'
import { createI18n, useI18n } from 'vue-i18n'

// call with I18n option
const i18n = createI18n({
  legacy: false, // you must specify 'legacy: false' option
  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<VueMessageType> 
```

**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<Messages extends Record<string, unknown> = {}, DateTimeFormats extends Record<string, unknown> = {}, NumberFormats extends Record<string, unknown> = {}, OptionLocale = Locale, Legacy = boolean> 
```

**Details**

The instance required for installation as the Vue plugin

### global

The property accessible to the global Composer instance or VueI18n instance

**Signature:**

```typescript
readonly global: Legacy extends true ? VueI18n<Messages, DateTimeFormats, NumberFormats, OptionLocale> : Legacy extends false ? Composer<Messages, DateTimeFormats, NumberFormats, OptionLocale> : unknown;
```

**Details**

If the [I18n#mode](general#mode) is `'legacy'`, then you can access to a global [VueI18n](legacy#vuei18n) instance, else then [I18n#mode](general#mode) is `'composition' `, you can access to the global [Composer](composition#composer) instance.

An instance of this property is **global scope**\*.

### mode

Vue I18n API mode

**Signature:**

```typescript
readonly mode: I18nMode;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

If you specified `legacy: true` option in `createI18n`, return `legacy`, else `composition`

**Default Value**

`'legacy'`

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

### legacy

Whether vue-i18n Legacy API mode use on your Vue App

**Signature:**

```typescript
legacy?: boolean;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

The default is to use the Legacy API mode. If you want to use the Composition API mode, you need to set it to `false`.

**Default Value**

`true`

**See Also**

* [Composition API](../guide/advanced/composition)

## I18nInjectionKey

Injection key for

**Signature:**

```typescript
I18nInjectionKey: InjectionKey<I18n> | string
```

**Details**

The global injection key for I18n instances with `useI18n`. this injection key is used in Web Components. Specify the i18n instance created by  together with `provide` function.

## I18nMode

Vue I18n API mode

**Signature:**

```typescript
export type I18nMode = 'legacy' | 'composition';
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**See Also**

* [I18n#mode](general#mode)

## 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 extends ComposerOptions<Schema, Locales> | VueI18nOptions<Schema, Locales> = ComposerOptions<Schema, Locales> | VueI18nOptions<Schema, Locales>> = I18nAdditionalOptions & Options;
```

**Details**

`I18nOptions` is inherited [I18nAdditionalOptions](general#i18nadditionaloptions), [ComposerOptions](composition#composeroptions) and [VueI18nOptions](legacy#vuei18noptions), so you can specify these 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' | 'isolated';
```

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

## VueI18nInstance

**Signature:**

```typescript
export type VueI18nInstance = IsNever<GeneratedInstanceType> extends true ? VueI18n | ExportedGlobalComposer : GeneratedInstanceType extends true ? VueI18n : ExportedGlobalComposer;
```

## DateTimeOptions

DateTime options

**Signature:**

```typescript
export interface DateTimeOptions<Key = string, Locales = Locale> extends Intl.DateTimeFormatOptions, LocaleOptions<Locales> 
```

**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<string> 
```

**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<Message = string>(ctx: CoreContext<Message>, fallback: FallbackLocale, start: Locale): Locale[];
```

**Details**

A fallback locale function implemented with a fallback chain algorithm. It's used in VueI18n as default.

Chains are cached per fallback identity. If you mutate an object or array fallback in place, pass a new object or array instead so that the chain is recomputed.

**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<Message = string>(ctx: CoreContext<Message>, fallback: FallbackLocale, start: Locale): Locale[];
```

**Details**

A fallback locale function implemented with a simple fallback algorithm.

Basically, the chain consists of `start` plus the specified fallback: for a string or array `fallbackLocale`, the value as specified in the props is used; for a map `fallbackLocale`, the map's **keys** are used and the `default` key is skipped since it is not a locale name.

### 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<T = string> = {
    [key: string]: LinkedModify<T>;
};
```

## Locale

**Signature:**

```typescript
export type Locale = IsNever<GeneratedLocale> extends true ? string : GeneratedLocale;
```

## LocaleDetector

**Signature:**

```typescript
export interface LocaleDetector<Args extends any[] = any[]> 
```

### resolvedOnce

### (...args: Args): Locale | Promise\<Locale>;

## LocaleFallbacker

The locale fallbacker

**Signature:**

```typescript
export type LocaleFallbacker = <Message = string>(ctx: CoreContext<Message>, fallback: FallbackLocale, start: Locale) => Locale[];
```

## LocaleMessage

**Signature:**

```typescript
export type LocaleMessage<Message = string> = Record<string, LocaleMessageValue<Message>>;
```

## LocaleMessageDictionary

**Signature:**

```typescript
export type LocaleMessageDictionary<T, Message = string> = {
    [K in keyof T]: LocaleMessageType<T[K], Message>;
};
```

## LocaleMessages

**Signature:**

```typescript
export type LocaleMessages<Schema, Locales = Locale, Message = string> = LocaleRecord<[Locales], Schema>;
```

## LocaleMessageType

**Signature:**

```typescript
export type LocaleMessageType<T, Message = string> = T extends string ? string : T extends () => Promise<infer P> ? LocaleMessageDictionary<P, Message> : T extends (...args: infer Arguments) => any ? (...args: Arguments) => ReturnType<T> : T extends Record<string, unknown> ? LocaleMessageDictionary<T, Message> : T extends Array<T> ? {
    [K in keyof T]: T[K];
} : T;
```

## LocaleMessageValue

**Signature:**

```typescript
export type LocaleMessageValue<Message = string> = LocaleMessageDictionary<any, Message> | string;
```

## LocaleOptions

**Signature:**

```typescript
export interface LocaleOptions<Locales = Locale> 
```

### 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<Message>;
```

## 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<T = string> 
```

### 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<string, unknown>;
```

**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
<p>{{ $t('greeting', { name: 'DIO' }) }}</p> <!-- `{ name: 'DIO' }` is message values -->
```

`@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<T>;
```

#### 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<T>;
```

#### 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<T>;
```

#### 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<T = string> = MessageFunctionCallable | MessageFunctionInternal<T>;
```

## MessageFunctionReturn

**Signature:**

```typescript
export type MessageFunctionReturn<T = string> = T extends string ? MessageType<T> : MessageType<T>[];
```

## MessageResolver

**Signature:**

```typescript
export type MessageResolver = (obj: unknown, path: Path) => PathValue;
```

## NamedValue

**Signature:**

```typescript
export type NamedValue<T = {}> = T & Record<string, unknown>;
```

## NumberOptions

Number Options

**Signature:**

```typescript
export interface NumberOptions<Key = string, Locales = Locale> extends Intl.NumberFormatOptions, LocaleOptions<Locales> 
```

**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<Message = string> = (translated: MessageFunctionReturn<Message>, key: string) => MessageFunctionReturn<Message>;
```

## 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<Locales = Locale> extends LocaleOptions<Locales> 
```

**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 to escape parameters for list or named interpolation values. When enabled, this option: - Escapes HTML special characters (`<`, `>`, `"`, `'`, `&`, `/`, `=`) in interpolation parameters - Sanitizes the final translated HTML to prevent XSS attacks by: - Escaping dangerous characters in HTML attribute values - Neutralizing event handler attributes (onclick, onerror, etc.) - Disabling javascript: URLs in href, src, action, formaction, and style attributes

**Default Value**

false

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

---

---
url: /guide/essentials/started.md
---
# Getting started

Creating a global application with Vue + Vue I18n is dead simple. With Vue.js, we are already composing our application with components. When adding Vue I18n to the mix, all we need to do is ready resource messages and simply use the localization API that are offered with Vue I18n.

:::tip NOTE
This guide will assume that you are already familiar with Vue itself. You don't need to be a Vue expert, but you may occasionally need to refer back to the [core Vue documentation](https://vuejs.org/) for more information about certain features.
:::

## An example

we're going to consider this example:

* [StackBlitz example](https://stackblitz.com/edit/vue-i18n-get-started?file=main.js)

Let's start by looking at the root component, `App.vue`.

### App.vue

```vue
<template>
  <h1>{{ $t('message.hello') }}</h1>
</template>
```

In the template, we use the `$t` translation API injected with Vue I18n, to localize. This allows Vue I18n to change the locale without rewriting the template, also to be able to support the globally application.

You will have the following output:

```vue
<h1>こんにちは、世界</h1>
```

Let's take a look at how this is achieved in JavaScript!

### Creating the i18n instance

The i18n instance is created by calling the function `createI18n`.

```js
const i18n = createI18n({
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: {
      message: {
        hello: 'hello world'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、世界'
      }
    }
  }
})
```

We can specify some options to `createI18n`.
The important options are the `locale`, `fallbackLocale`, and `messages` options.

`locale` is the language of the Vue application to be localized.

:::tip NOTE
Specify a locale as a [BCP 47 language tag](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag), such as `en`, `en-US` or `pt-BR`. Vue I18n passes the locale to the `Intl` APIs of JavaScript, and the [implicit fallback](./fallback#implicit-fallback-using-locales) splits it at `-`. With a locale that is not a language tag, such as `pt_BR`, the implicit fallback does not work, and [datetime formatting](./datetime) and [number formatting](./number) throw a `RangeError`.
:::

`fallbackLocale` is the language to fall back to if the key resource specified in the `$t` translation API is not found in the language of `locale`.

`messages` is the locale messages to translate with the `$t` translation API. The structure of the locale message is the hierarchical object structure with each locale as the top property

### Registering the i18n plugin

Once we've created our i18n instance, we need to register it as a plugin by calling `use` on our application:

```js
const app = createApp(Vue)
app.use(i18n)
app.mount('#app')
```

Like with most Vue plugins, the call to `use` needs to happen before the call to `mount`.

If you're curious about what this plugin does, some of its responsibilities include:

1. Adding the global properties and methods such as `$t`, `$i18n`
2. Enabling the `useI18n` composables
3. [Globally registering](https://vuejs.org/guide/components/registration.html#global-registration) the `i18n-t`, `i18n-d`, and `i18n-n` components.

## Conventions in this guide

### Single-File Components

Vue I18n is most commonly used in applications built using a bundler (e.g. Vite) and [SFCs](https://vuejs.org/guide/introduction.html#single-file-components) (i.e. `.vue ` files). Most of the examples in this guide will be written in that style, but Vue I18n itself doesn't require you to use build tools or SFCs.

For example, if you're using the *global builds* of [Vue](https://vuejs.org/guide/quick-start.html#using-vue-from-cdn) and [Vue I18n](../installation#Direct-Download-CDN), the libraries are exposed via global objects, rather than imports:

```js
const { createApp } = Vue
const { createI18n, useI18n } = VueI18n
```

### Component API style

Vue I18n can be used with both the Composition API and the Options API. Where relevant, the examples in this guide will show components written in both styles. Composition API examples will typically use `<script setup>`, rather than an explicit `setup` function.

If you need a refresher about the two styles, see [Vue - API Styles](https://vuejs.org/guide/introduction.html#api-styles).

Vue I18n works with both Vue composition API and Options API. Vue I18n has two APIs style like Vue, Composition API and Legacy API for options API using.

:::danger IMPORTANT
In Vue I18n v9 and later, the API offered by Vue I18n v8.x is called **Legacy API** mode.
Legacy API is deprecated Vue I18n v11, and drop Vue I18n v12. We recommend use Composition API mode.
:::

The following sections will be explained using the Legacy API.

If you would like to use it in Composition API style and already understand Vue I18n, you can step to [here](../advanced/composition).

---

---
url: /guide/installation.md
---
# Installation

## Compatibility Note

* Vue.js `3.0.0`+

## Package managers

> \[!IMPORTANT]
> When running `npm install`, v11 may appear as deprecated. **This was a mistake when deprecating v9 and v10. v11 will continue to be maintained**.

::: code-group

```sh [npm]
npm install vue-i18n@11
```

```sh [yarn]
yarn add vue-i18n@11
```

```sh [pnpm]
pnpm add vue-i18n@11
```

:::

When using with a module system, you must explicitly install the `vue-i18n`
via `app.use()`:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  // something vue-i18n options here ...
})

const app = createApp({
  // something vue options here ...
})

app.use(i18n)
app.mount('#app')
```

## Direct Download

<https://unpkg.com/vue-i18n@11>

[unpkg.com](https://unpkg.com) provides a npm-based CDN links. The above link will always point to the latest release on npm.

### Global import

```html
<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/vue-i18n@11"></script>
```

You can also use a specific version/tag via URLs like <https://unpkg.com/vue-i18n@11.0.0/dist/vue-i18n.global.js>

### ES Modules import

```html
<script type="module" src="https://unpkg.com/vue@3/dist/vue.esm-browser.js">
<script type="module" src="https://unpkg.com/vue-i18n@11/dist/vue-i18n.esm-browser.js">
```

You can also use a specific version/tag via URLs like <https://unpkg.com/vue-i18n@11.0.0/dist/vue-i18n.esm-browser.js>

---

---
url: /guide/advanced/lazy.md
---
# Lazy loading

Loading all of your localization files at once is overkill and unnecessary.

Lazy loading or asynchronously loading the localization files is really easy when using bundler.

Let´s assume we have a project directory similar to the one below:

```
├── dist
├── index.html
├── package.json
├── src
│   ├── App.vue
│   ├── components
│   ├── i18n.js
│   ├── index.css
│   ├── locales
│   │   ├── en.json
│   │   └── ja.json
│   ├── main.js
│   ├── pages
│   │   ├── About.vue
│   │   └── Home.vue
│   └── router.js
```

The `pages` folder is where our arbitrary Vue component files like the `About.vue`, router inits, i18n inits and other reside. The `locales` folder is where all of our localization files reside, and In `i18n.js`, the functions for i18n-related process are defined as follows:

```js
import { nextTick } from 'vue'
import { createI18n } from 'vue-i18n'

export const SUPPORT_LOCALES = ['en', 'ja']

export function setupI18n(options = { locale: 'en' }) {
  const i18n = createI18n(options)
  setI18nLanguage(i18n, options.locale)
  return i18n
}

export function setI18nLanguage(i18n, locale) {
  if (i18n.mode === 'legacy') {
    i18n.global.locale = locale
  } else {
    i18n.global.locale.value = locale
  }
  /**
   * NOTE:
   * If you need to specify the language setting for headers, such as the `fetch` API, set it here.
   * The following is an example for axios.
   *
   * axios.defaults.headers.common['Accept-Language'] = locale
   */
  document.querySelector('html').setAttribute('lang', locale)
}

export async function loadLocaleMessages(i18n, locale) {
  // load locale messages with dynamic import
  const messages = await import(
    /* webpackChunkName: "locale-[request]" */ `./locales/${locale}.json`
  )

  // set locale and locale message
  i18n.global.setLocaleMessage(locale, messages.default)

  return nextTick()
}
```

The following three functions are exported:

* `setupI18n`
* `setI18nLanguage`
* `loadLocaleMessages`

:::tip NOTE
This code example also shows how to handle it outside of the component using the [`global` property of i18n instance](../../api/general#global).
About i18n instance, see the [API Reference](../../api/general)
:::

The `setupI18n` function takes the same options as `createI18n`, creates an instance of i18n with those options, executes the `setI18nLanguage` function, and returns the i18n instance.

The `setI18nLanguage` function sets the language by setting the locale of the parameter `i18n` to the value of the parameter `locale`. Besides, this function has the utility of setting the `lang` attribute of the HTML document to the value of the parameter `locale`. As noted in the comments, like the HTTP client, you can also set the language

The `loadLocaleMessages` function is what we will actually use to change the languages. Loading the new files is done via the `import` function, which is generously provided by webpack and it allows us to load files dynamically, and because it uses promises we can easily wait for the loading to finish.

You can learn more about the import function in the [webpack documentation](https://webpack.js.org/guides/code-splitting/#dynamic-imports).

Using the `loadLocaleMessages` function is straightforward. A common use case is inside a vue-router beforeEach hook.

Here the code for the vue-router beforeEach hook part of `router.js`:

```js
  // navigation guards
  router.beforeEach(async (to, from, next) => {
    const paramsLocale = to.params.locale

    // use locale if paramsLocale is not in SUPPORT_LOCALES
    if (!SUPPORT_LOCALES.includes(paramsLocale)) {
      return next(`/${locale}`)
    }

    // load locale messages
    if (!i18n.global.availableLocales.includes(paramsLocale)) {
      await loadLocaleMessages(i18n, paramsLocale)
    }

    // set i18n language
    setI18nLanguage(i18n, paramsLocale)

    return next()
  })
```

---

---
url: /api/legacy.md
---
# Legacy API

## Choice

**Signature:**

```typescript
export type Choice = number;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## DateTimeFormatResult

**Signature:**

```typescript
export type DateTimeFormatResult = string;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## LocaleMessageObject

**Signature:**

```typescript
export type LocaleMessageObject<Message = string> = LocaleMessageDictionary<Message>;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## NumberFormatResult

**Signature:**

```typescript
export type NumberFormatResult = string;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## PluralizationRulesMap

**Signature:**

```typescript
export type PluralizationRulesMap = {
    [locale: string]: PluralizationRule;
};
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## TranslateResult

**Signature:**

```typescript
export type TranslateResult = string;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

## VueI18n

VueI18n legacy interfaces

**Signature:**

```typescript
export interface VueI18n<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 string ? [ResourceLocales] extends [never] ? Locale : ResourceLocales : OptionLocale | ResourceLocales, Composition extends Composer<Messages, DateTimeFormats, NumberFormats, OptionLocale> = Composer<Messages, DateTimeFormats, NumberFormats, OptionLocale>> 
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This interface is compatible with interface of `VueI18n` class (offered with Vue I18n v8.x).

### availableLocales

**Signature:**

```typescript
readonly availableLocales: Composition['availableLocales'];
```

**Details**

The list of available locales in `messages` in lexical order.

### d

Datetime formatting

**Signature:**

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

**Details**

About details functions, See the [VueI18nDateTimeFormatting](legacy#vuei18ndatetimeformatting)

### datetimeFormats

**Signature:**

```typescript
readonly datetimeFormats: {
        [K in keyof DateTimeFormats]: DateTimeFormats[K];
    };
```

**Details**

The datetime formats of localization.

**See Also**

* [Datetime Formatting](../guide/essentials/datetime)

### escapeParameterHtml

**Signature:**

```typescript
escapeParameterHtml: Composition['escapeParameter'];
```

**Details**

Whether interpolation parameters are escaped before the message is translated.

**See Also**

* [HTML Message](../guide/essentials/syntax#html-message)

### fallbackLocale

**Signature:**

```typescript
fallbackLocale: FallbackLocales<Locales>;
```

**Details**

The current fallback locales this VueI18n instance is using.

**See Also**

* [Fallbacking](../guide/essentials/fallback)

### formatFallbackMessages

**Signature:**

```typescript
formatFallbackMessages: Composition['fallbackFormat'];
```

**Details**

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

**See Also**

* [Fallbacking](../guide/essentials/fallback)

### getDateTimeFormat

Get datetime format

**Signature:**

```typescript
getDateTimeFormat: Composition['getDateTimeFormat'];
```

**Details**

get datetime format from VueI18n instance [datetimeFormats](legacy#datetimeformats).

### getLocaleMessage

Get locale message

**Signature:**

```typescript
getLocaleMessage: Composition['getLocaleMessage'];
```

**Details**

get locale message from VueI18n instance [messages](legacy#messages).

### getNumberFormat

Get number format

**Signature:**

```typescript
getNumberFormat: Composition['getNumberFormat'];
```

**Details**

get number format from VueI18n instance [numberFormats](legacy#numberFormats).

### id

**Signature:**

```typescript
id: number;
```

**Details**

Instance ID.

### locale

**Signature:**

```typescript
locale: Locales;
```

**Details**

The current locale this VueI18n 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)

### mergeDateTimeFormat

Merge datetime format

**Signature:**

```typescript
mergeDateTimeFormat: Composition['mergeDateTimeFormat'];
```

**Details**

Merge datetime format to VueI18n instance [datetimeFormats](legacy#datetimeformats).

### mergeLocaleMessage

Merge locale message

**Signature:**

```typescript
mergeLocaleMessage: Composition['mergeLocaleMessage'];
```

**Details**

Merge locale message to VueI18n instance [messages](legacy#messages).

### mergeNumberFormat

Merge number format

**Signature:**

```typescript
mergeNumberFormat: Composition['mergeNumberFormat'];
```

**Details**

Merge number format to VueI18n instance [numberFormats](legacy#numberFormats).

### messages

**Signature:**

```typescript
readonly messages: {
        [K in keyof Messages]: Messages[K];
    };
```

**Details**

The locale messages of localization.

**See Also**

* [Getting Started](../guide/essentials/started)

### missing

**Signature:**

```typescript
missing: MissingHandler | null;
```

**Details**

A handler for localization missing.

### modifiers

**Signature:**

```typescript
readonly modifiers: Composition['modifiers'];
```

**Details**

Custom Modifiers for linked messages.

**See Also**

* [Custom Modifiers](../guide/essentials/syntax#custom-modifiers)

### n

Number Formatting

**Signature:**

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

**Details**

About details functions, See the [VueI18nNumberFormatting](legacy#vuei18nnumberformatting)

### numberFormats

**Signature:**

```typescript
readonly numberFormats: {
        [K in keyof NumberFormats]: NumberFormats[K];
    };
```

**Details**

The number formats of localization.

**See Also**

* [Number Formatting](../guide/essentials/number)

### pluralizationRules

A set of rules for word pluralization

**Signature:**

```typescript
pluralizationRules: Composition['pluralRules'];
```

**See Also**

* [Custom Pluralization](../guide/essentials/pluralization#custom-pluralization)

### postTranslation

**Signature:**

```typescript
postTranslation: PostTranslationHandler<VueMessageType> | null;
```

**Details**

A handler for post processing of translation.

### rt

Resolve locale message translation

**Signature:**

```typescript
rt: VueI18nResolveLocaleMessageTranslation<Locales>;
```

**Details**

About details functions, See the [VueI18nResolveLocaleMessageTranslation](legacy#vuei18nresolvelocalemessagetranslation)

### setDateTimeFormat

Set datetime format

**Signature:**

```typescript
setDateTimeFormat: Composition['setDateTimeFormat'];
```

**Details**

Set datetime format to VueI18n instance [datetimeFormats](legacy#datetimeformats).

### setLocaleMessage

Set locale message

**Signature:**

```typescript
setLocaleMessage: Composition['setLocaleMessage'];
```

**Details**

Set locale message to VueI18n instance [messages](legacy#messages).

### setNumberFormat

Set number format

**Signature:**

```typescript
setNumberFormat: Composition['setNumberFormat'];
```

**Details**

Set number format to VueI18n instance [numberFormats](legacy#numberFormats).

### silentFallbackWarn

**Signature:**

```typescript
silentFallbackWarn: Composition['fallbackWarn'];
```

**Details**

Whether suppress fallback warnings when localization fails.

### silentTranslationWarn

**Signature:**

```typescript
silentTranslationWarn: Composition['missingWarn'];
```

**Details**

Whether suppress warnings outputted when localization fails.

**See Also**

* [Fallbacking](../guide/essentials/fallback)

### sync

**Signature:**

```typescript
sync: Composition['inheritLocale'];
```

**Details**

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

**See Also**

* [Local Scope](../guide/essentials/scope#local-scope-2)

### t

Locale message translation

**Signature:**

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

**Details**

About details functions, See the [VueI18nTranslation](legacy#vuei18ntranslation)

### tm

Locale messages getter

**Signature:**

```typescript
tm: Composition['tm'];
```

**Details**

If [i18n component options](injection#i18n) is specified, it’s get in preferentially local scope locale messages than global scope locale messages.

If [i18n component options](injection#i18n) isn't specified, it’s get with 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](legacy#rt-message) details.
:::

**Examples**

template:

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

```js
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  messages: {
    en: {
      contents: [
        {
          title: 'Title1',
          // ...
          paragraphs: [
            // ...
          ]
        }
      ]
    }
  }
  // ...
})
```

### warnHtmlInMessage

**Signature:**

```typescript
warnHtmlInMessage: WarnHtmlInMessageLevel;
```

**Details**

Whether to allow the use locale messages of HTML formatting.

If you set `warn` or` error`, will check the locale messages on the VueI18n instance.

If you are specified `warn`, a warning will be output at console.

If you are specified `error` will occurred an Error.

**See Also**

* [HTML Message](../guide/essentials/syntax#html-message)
* [Change `warnHtmlInMessage` option default value](../guide/migration/breaking#change-warnhtmlinmessage-option-default-value)

### te(key, locale)

Translation locale message exist

**Signature:**

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

**Details**

whether do exist locale message on VueI18n instance [messages](legacy#messages).

If you specified `locale`, check the locale messages of `locale`, but not those of its fallback locales.

If you did not specify `locale`, check the locale messages of the current `locale` and then those of its fallback locales, as `t` does (see [fallbacking](../guide/essentials/fallback)).

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Str | Key | A target locale message key |
| locale | Locales | A target locale |

#### Returns

If found locale message, `true`, else `false`

## VueI18nDateTimeFormatting

Datetime formatting functions for VueI18n legacy interfaces

**Signature:**

```typescript
export interface VueI18nDateTimeFormatting<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> 
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This is the interface for [VueI18n](legacy#vuei18n)

### (value: number | Date): DateTimeFormatResult;

Datetime formatting

**Signature:**

```typescript
(value: number | Date): DateTimeFormatResult;
```

**Details**

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

If [i18n component options](injection#i18n) is specified, it’s formatted in preferentially local scope datetime formats than global scope locale messages.

If [i18n component options](injection#i18n) isn't specified, it’s formatted with global scope datetime formats.

**See Also**

* [Datetime formatting](../guide/essentials/datetime)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |

#### Returns

Formatted value

### (value: Value, key: Key | ResourceKeys): DateTimeFormatResult;

Datetime formatting

**Signature:**

```typescript
<Value extends number | Date = number, Key extends string = string>(value: Value, key: Key | ResourceKeys): DateTimeFormatResult;
```

**Details**

Overloaded `d`. About details, see the [call signature](legacy#value-number-date-datetimeformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | Value | A value, timestamp number or `Date` instance |
| key | Key | ResourceKeys | A key of datetime formats |

#### Returns

Formatted value

### (value: Value, key: Key | ResourceKeys, locale: Locales): DateTimeFormatResult;

Datetime formatting

**Signature:**

```typescript
<Value extends number | Date = number, Key extends string = string>(value: Value, key: Key | ResourceKeys, locale: Locales): DateTimeFormatResult;
```

**Details**

Overloaded `d`. About details, see the [call signature](legacy#value-number-date-datetimeformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | Value | A value, timestamp number or `Date` instance |
| key | Key | ResourceKeys | A key of datetime formats |
| locale | Locales | A locale, it will be used over than global scope or local scope. |

#### Returns

Formatted value

### (value: number | Date, args: {        \[key: string]: string | boolean | number;    }): DateTimeFormatResult;

Datetime formatting

**Signature:**

```typescript
(value: number | Date, args: {
        [key: string]: string | boolean | number;
    }): DateTimeFormatResult;
```

**Details**

Overloaded `d`. About details, see the [call signature](legacy#value-number-date-datetimeformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | Date | A value, timestamp number or `Date` instance |
| args | {         \[key: string]: string | boolean | number;     } | An argument values |

#### Returns

Formatted value

## VueI18nNumberFormatting

Number formatting functions for VueI18n legacy interfaces

**Signature:**

```typescript
export interface VueI18nNumberFormatting<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> 
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This is the interface for [VueI18n](legacy#vuei18n)

### (value: number): NumberFormatResult;

Number formatting

**Signature:**

```typescript
(value: number): NumberFormatResult;
```

**Details**

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

If [i18n component options](injection#i18n) is specified, it’s formatted in preferentially local scope number formats than global scope locale messages.

If [i18n component options](injection#i18n) isn't specified, 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, key: Key | ResourceKeys): NumberFormatResult;

Number formatting

**Signature:**

```typescript
<Key extends string = string>(value: number, key: Key | ResourceKeys): NumberFormatResult;
```

**Details**

Overloaded `n`. About details, see the [call signature](legacy#value-number-numberformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | Key | ResourceKeys | A key of number formats |

#### Returns

Formatted value

### (value: number, key: Key | ResourceKeys, locale: Locales): NumberFormatResult;

Number formatting

**Signature:**

```typescript
<Key extends string = string>(value: number, key: Key | ResourceKeys, locale: Locales): NumberFormatResult;
```

**Details**

Overloaded `n`. About details, see the [call signature](legacy#value-number-numberformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| key | Key | ResourceKeys | A key of number formats |
| locale | Locales | A locale, it will be used over than global scope or local scope. |

#### Returns

Formatted value

### (value: number, args: {        \[key: string]: string | boolean | number;    }): NumberFormatResult;

Number formatting

**Signature:**

```typescript
(value: number, args: {
        [key: string]: string | boolean | number;
    }): NumberFormatResult;
```

**Details**

Overloaded `n`. About details, see the [call signature](legacy#value-number-numberformatresult) details.

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| value | number | A number value |
| args | {         \[key: string]: string | boolean | number;     } | An argument values |

#### Returns

Formatted value

## VueI18nOptions

VueI18n Options

**Signature:**

```typescript
export interface VueI18nOptions<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<Schema, Locales> = ComposerOptions<Schema, Locales>> 
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This option is compatible with `VueI18n` class constructor options (offered with Vue I18n v8.x)

### availableLocales

**Signature:**

```typescript
availableLocales?: Locale[];
```

**Details**

The list of available locales in messages in lexical order.

**Default Value**

`[]`

### datetime

### datetimeFormats

### escapeParameterHtml

**Signature:**

```typescript
escapeParameterHtml?: Options['escapeParameter'];
```

**Details**

Whether to escape parameters for list or named interpolation values. When enabled, this option: - Escapes HTML special characters (`<`, `>`, `"`, `'`, `&`, `/`, `=`) in interpolation parameters - Sanitizes the final translated HTML to prevent XSS attacks by: - Escaping dangerous characters in HTML attribute values - Neutralizing event handler attributes (onclick, onerror, etc.) - Disabling javascript: URLs in href, src, action, formaction, and style attributes

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.

Setting `escapeParameterHtml` 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 - Using the escapeParameter option](../guide/essentials/syntax#using-the-escapeparameter-option)

### fallbackLocale

**Signature:**

```typescript
fallbackLocale?: Options['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?: Options['fallbackRoot'];
```

**Details**

In the component localization, whether to fall back 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)

### flatJson

**Signature:**

```typescript
flatJson?: Options['flatJson'];
```

**Details**

Allow use flat json messages or not

**Default Value**

`false`

### formatFallbackMessages

**Signature:**

```typescript
formatFallbackMessages?: Options['fallbackFormat'];
```

**Details**

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

**Default Value**

`false`

**See Also**

* [Fallbacking](../guide/essentials/fallback)

### locale

**Signature:**

```typescript
locale?: Options['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

### messageResolver

**Signature:**

```typescript
messageResolver?: MessageResolver;
```

**Details**

A message resolver to resolve [`messages`](legacy#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`](legacy#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`](legacy#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`](legacy#t-key)

* [`te`](legacy#te-key-locale)

* [`tm`](legacy#tm-key)

* [Translation component](component#translation)

:::tip
:new: v9.2+
:::

:::warning
If you use the message resolver, the [`flatJson`](legacy#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?: Options['missing'];
```

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

### modifiers

**Signature:**

```typescript
modifiers?: Options['modifiers'];
```

**Details**

Custom Modifiers for linked messages.

**See Also**

* [Custom Modifiers](../guide/essentials/syntax#custom-modifiers)

### number

### numberFormats

### pluralizationRules

**Signature:**

```typescript
pluralizationRules?: Options['pluralRules'];
```

**Details**

A set of rules for word pluralization

**Default Value**

`{}`

**See Also**

* [Custom Pluralization](../guide/essentials/pluralization#custom-pluralization)

### postTranslation

**Signature:**

```typescript
postTranslation?: Options['postTranslation'];
```

**Details**

A handler for post processing of translation. The handler gets after being called with the `$t`, and `t`.

This handler is useful if you want to filter on translated text such as space trimming.

**Default Value**

`null`

### sharedMessages

**Signature:**

```typescript
sharedMessages?: LocaleMessages<VueMessageType>;
```

**Details**

The shared locale messages of localization for components. More detail see Component based localization.

**Default Value**

`undefined`

**See Also**

* [Shared locale messages for components](../guide/essentials/local#shared-locale-messages-for-components)

### silentFallbackWarn

**Signature:**

```typescript
silentFallbackWarn?: Options['fallbackWarn'];
```

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

### silentTranslationWarn

**Signature:**

```typescript
silentTranslationWarn?: Options['missingWarn'];
```

**Details**

Whether suppress warnings outputted when localization fails.

If `true`, 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**

`false`

**See Also**

* [Fallbacking](../guide/essentials/fallback)

### sync

**Signature:**

```typescript
sync?: boolean;
```

**Details**

Whether synchronize 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)

### warnHtmlInMessage

**Signature:**

```typescript
warnHtmlInMessage?: WarnHtmlInMessageLevel;
```

**Details**

Whether to allow the use locale messages of HTML formatting.

See the warnHtmlInMessage 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)

## VueI18nResolveLocaleMessageTranslation

Resolve locale message translation functions for VueI18n legacy interfaces

**Signature:**

```typescript
export type VueI18nResolveLocaleMessageTranslation<Locales = 'en-US'> = ComposerResolveLocaleMessageTranslation<Locales>;
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This is the interface for [VueI18n](legacy#vuei18n). This interface is an alias of [ComposerResolveLocaleMessageTranslation](composition#composerresolvelocalemessagetranslation).

## VueI18nTranslation

Locale message translation functions for VueI18n legacy interfaces

**Signature:**

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

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

**Details**

This is the interface for [VueI18n](legacy#vuei18n)

### (key: Key | ResourceKeys): TranslateResult;

Locale message translation.

**Signature:**

```typescript
<Key extends string>(key: Key | ResourceKeys): TranslateResult;
```

**Details**

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

If [i18n component options](injection#i18n) is specified, it’s translated in preferentially local scope locale messages than global scope locale messages.

If [i18n component options](injection#i18n) isn't specified, it’s translated with global scope locale messages.

**See Also**

* [Scope and Locale Changing](../guide/essentials/scope)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |

#### Returns

Translated message

### (key: Key | ResourceKeys, named: Record\<string, unknown>): TranslateResult;

Locale message translation.

**Signature:**

```typescript
<Key extends string>(key: Key | ResourceKeys, named: Record<string, unknown>): TranslateResult;
```

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

**See Also**

* [Named interpolation](../guide/essentials/syntax#named-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| named | Record\<string, unknown> | A values of named interpolation |

#### Returns

Translated message

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

Locale message translation for named interpolations and plurals

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token, and return a pluralized translation message.

**See Also**

* [Pluralization](../guide/essentials/pluralization)
* [Named interpolation](../guide/essentials/syntax#named-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, named: NamedValue, defaultMsg: string): TranslateResult;

Locale message translation for named interpolations and plurals

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, for each placeholder x, the locale messages should contain a `{x}` token, and if no translation was found, return a default message.

**See Also**

* [Named interpolation](../guide/essentials/syntax#named-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, named: NamedValue, options: TranslateOptions\<Locales>): TranslateResult;

Locale message translation for named interpolations

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

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

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

About details of options, see the .

**See Also**

* [Named interpolation](../guide/essentials/syntax#named-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| named | NamedValue | A values of named interpolation |
| options | TranslateOptions\<Locales> | Additional  for translation |

#### Returns

Translated message

### (key: Key | ResourceKeys, plural: number): TranslateResult;

Locale message translation for plurals

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, return a pluralized translation message.

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

**See Also**

* [Pluralization](../guide/essentials/pluralization)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| plural | number | Which plural string to get. 1 returns the first one. |

#### Returns

Translated message

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

Locale message translation for plurals

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, return a pluralized translation message.

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

About details of options, see the .

**See Also**

* [Pluralization](../guide/essentials/pluralization)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, defaultMsg: string): TranslateResult;

Locale message translation for missing default message

**Signature:**

```typescript
<Key extends string>(key: Key | ResourceKeys, defaultMsg: string): TranslateResult;
```

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, if no translation was found, return a default message.

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

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| defaultMsg | string | A default message to return if no translation was found |

#### Returns

Translated message

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

Locale message translation for missing default message

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, if no translation was found, return a default message.

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

About details of options, see the .

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, list: unknown\[]): TranslateResult;

Locale message translation.

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

**See Also**

* [List interpolation](../guide/essentials/syntax#list-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| list | unknown\[] | A values of list interpolation |

#### Returns

Translated message

### (key: Key | ResourceKeys, list: unknown\[], plural: number): TranslateResult;

Locale message translation for list interpolations and plurals

**Signature:**

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

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list, and return a pluralized translation message.

**See Also**

* [Pluralization](../guide/essentials/pluralization)
* [List interpolation](../guide/essentials/syntax#list-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, list: unknown\[], defaultMsg: string): TranslateResult;

Locale message translation for list interpolations and missing default message

**Signature:**

```typescript
<Key extends string>(key: Key | ResourceKeys, list: unknown[], defaultMsg: string): TranslateResult;
```

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list, and if no translation was found, return a default message.

**See Also**

* [List interpolation](../guide/essentials/syntax#list-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | 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, list: unknown\[], options: TranslateOptions\<Locales>): TranslateResult;

Locale message translation for list interpolations

**Signature:**

```typescript
<Key extends string>(key: Key | ResourceKeys, list: unknown[], options: TranslateOptions<Locales>): TranslateResult;
```

**Details**

Overloaded `t`. About details, see the [call signature](legacy#key-key-resourcekeys-translateresult) details.

In this overloaded `t`, the locale messages should contain a `{0}`, `{1}`, … for each placeholder in the list.

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

About details of options, see the .

**See Also**

* [List interpolation](../guide/essentials/syntax#list-interpolation)

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| key | Key | ResourceKeys | A target locale message key |
| list | unknown\[] | A values of list interpolation |
| options | TranslateOptions\<Locales> | Additional  for translation |

#### Returns

Translated message

## WarnHtmlInMessageLevel

**Signature:**

```typescript
export type WarnHtmlInMessageLevel = 'off' | 'warn' | 'error';
```

:::danger DEPRECATED
will be removed at vue-i18n v12
:::

---

---
url: /guide/essentials/local.md
---
# Local Scope Based Localization

## i18n component options

[In *'Scope and Locale Changing’*](scope), Vue I18n has two scope concepts, global scope and local scope.

In general, locale info (e.g. `locale`,`messages`, etc) is set as option of `createI18n` and it sets (install) with `app.use`. To sum up, you use global scope translation functions `$t` to localize them.

Sometimes it is necessary to localize per component while still managing the resources of the local messages. In this case it can be useful to localize each local scope using i18n component option on the component instead of the global scope.

The following is an example of local scope based localization:

```js
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

// setting locale info used by global scope as an options
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello world',
        greeting: 'good morning, world!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、世界',
        greeting: 'おはよう、世界！'
      }
    }
  }
})

// define component
const Component1 = {
  template: `
    <div id="component">
      <h1>Component1</h1>
      <p>Component1 locale messages: {{ $t("message.hello") }}</p>
      <p>Fallback global locale messages: {{ $t("message.greeting") }}</p>
    </div>
  `,
  i18n: {
    messages: {
      en: { message: { hello: 'hello component1' } },
      ja: { message: { hello: 'こんにちは、component1' } }
    }
  }
}

const app = createApp({
  components: { Component1 }
})
app.use(i18n)
app.mount('#app')
```

Template:

```html
<div id="app">
  <h1>Root</h1>
  <p>{{ $t("message.hello") }}</p>
  <Component1 />
</div>
```

Outputs the following:

```html
<div id="app">
  <h1>Root</h1>
  <p>こんにちは、世界</p>
  <div class="component">
    <p>Component1 locale messages: こんにちは、component1</p>
    <p>Fallback global locale messages: おはよう、世界！</p>
  </div>
</div>
```

As in the example above, if the component doesn't have the locale message, it falls back to global scope. As explained the [here](scope#local-scope-2), due to the `locale` of local scope inherits from global scope, so the component uses the language set in global scope (in the above example: `locale: 'ja'`)

And also, as explained the [here](fallback#explicit-fallback-with-one-locale), note that, by default, falling back to global scope generates two warnings in the console:

```
[intlify] Not found 'message.greeting' key in 'ja' locale messages.
[intlify] Fall back to translate 'message.greeting' with root locale.
```

If you want to localize using the component locale, you can do that with `sync: false` and `locale` in the `i18n` component option.

## Shared locale messages for components

Sometimes you may want to import shared locale messages for certain components, not fallback from locale messages of global scope (e.g. common messages of certain feature for components).

You can use `sharedMessages` options of `i18n`.

Common locale messages example:

```js
export default {
  en: {
    buttons: {
      save: "Save",
      // ...
    }
  },
  ja: {
    buttons: {
      save: "保存",
      // ...
    }
  }
}
```

Components:

```js
import commonMessage from './locales/common' // import common locale messages

export default {
  name: 'ServiceModal',
  template: `
    <div class="modal">
      <div class="body">
        <p>This is good service</p>
      </div>
      <div class="footer">
        <button type="button">{{ $t('buttons.save') }}</button>
      </div>
    </div>
  `,
  i18n: {
    messages: { ... },
    sharedMessages: commonMessages
  }
}
```

If `sharedMessages` option is specified along with the `messages` option, those messages will be merged into locale messages into the VueI18n instance of the target component.

---

---
url: /guide/maintenance.md
---
# Maintenance Status

> \[!IMPORTANT]
> Vue I18n v9 and Vue I18n v10 has reached EOL and is no longer actively maintained.

> \[!IMPORTANT]
> When running `npm install`, v11 may appear as deprecated. **This was a mistake when deprecating v9 and v10. v11 will continue to be maintained**.

Vue I18n and related intlify packages has a lifecycle.

The following is the maintenance status for each version:

---

---
url: /guide/essentials/syntax.md
---
# Message Format Syntax

Vue I18n can use message format syntax to localize the messages to be displayed in the UI. Vue I18n messages are interpolations and messages with various feature syntax.

## Interpolations

Vue I18n supports interpolation using placeholders `{}` like "Mustache".

### Named interpolation

The Named interpolation can be interpolated in the placeholder using variable names defined in JavaScript.

As an example, the following locale messages resource:

```js
const messages = {
  en: {
    message: {
      hello: '{msg} world'
    }
  }
}
```

The locale messages is the resource specified by the `messages` option of `createI18n`. It’s defined `en` locale with `{ message: { hello: '{msg} world' } }`.

Named interpolation allows you to specify variables defined in JavaScript. In the locale message above, you can localize it by giving the JavaScript defined `msg` as a parameter to the translation function.

The variable name inside `{}` must starts with a letter (a-z, A-Z) or an underscore (`_`), followed by any combination of letters, digits, underscores (`_`), hyphens (`-`), or dollar signs (`$`).

Examples: `{msg}`, `{_userName}`, `{user-id}`, `{total$}`

The following is an example of the use of `$t` in a template:

```html
<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>
```

The first argument is `message.hello` as the locale messages key, and the second argument is an object with `msg` property as a parameter to `$t`.

:::tip NOTE
The locale message resource key for the translation function can be specified for a specific resource namespace with using `.` (dot), just like a JavaScript object.
::::

:::tip NOTE
`$t` has some overloads. About these overloads, see the [API Reference](../../api/injection#t-key)
:::

As result the below:

```html
<p>hello world</p>
```

### List interpolation

The List interpolation can be interpolated in the placeholder using an array defined in JavaScript.

As an example, the following locale messages resource:

```js
const messages = {
  en: {
    message: {
      hello: '{0} world'
    }
  }
}
```

It is defined `en` locale with `{ message: { hello: '{0} world' } }`.

List interpolation allows you to specify array defined in JavaScript. In the locale message above, you can be localized by giving the `0` index item of the array defined by JavaScript as a parameter to the translation function.

The following is an example of the use of `$t` in a template:

```html
<p>{{ $t('message.hello', ['hello']) }}</p>
```

The first argument is `message.hello` as the locale messages key, and the second argument is an array that have `'hello'` item as a parameter to `$t`.

As result the below:

```html
<p>hello world</p>
```

### Literal interpolation

The Literal interpolation can be interpolated in the placeholder using literal string.

As an example, the following locale messages resource:

```js
const messages = {
  en: {
    address: "{account}{'@'}{domain}"
  }
}
```

It is defined `en` locale with `{ address: "{account}{'@'}{domain}" }`.

Literal interpolation allows you to specify string literal that is quoted with single quotation `’`. The message specified with literal interpolation is localized **as the string** by the translation function.

The following is an example of the use of `$t` in a template:

```html
<p>email: {{ $t('address', { account: 'foo', domain: 'domain.com' }) }}</p>
```

The first argument is `address` as the locale messages key, and the second argument is an object with `account` and `domain` property as a parameter to `$t`.

As result the below:

```html
<p>email: foo@domain.com</p>
```

:::tip NOTE
Literal interpolation is useful for special characters in message format syntax, such as `{` and `}`, which cannot be used directly in the message.
:::

## Linked messages

If there’s a locale messages key that will always have the same concrete text as another one you can just link to it.

To link to another locale messages key, all you have to do is to prefix its contents with an *`@:key`* sign followed by the full name of the locale messages key including the namespace you want to link to.

Locale messages the below:

```js
const messages = {
  en: {
    message: {
      the_world: 'the world',
      dio: 'DIO:',
      linked: '@:message.dio @:message.the_world !!!!'
    }
  }
}
```

It’s `en` locale that has hierarchical structure in the object.

The `message.the_world` has `the world` and `message.dio`. The `message.linked` has `@:message.dio @:message.dio @:message.the_world !!!!`, and it’s linked to the locale messages key with `message.dio` and `message.the_world`.

The following is an example of the use of `$t` in a template:

```html
<p>{{ $t('message.linked') }}</p>
```

The first argument is `message.linked` as the locale messages key as a parameter to `$t`.

As result the below:

```html
<p>DIO: the world !!!!</p>
```

### Built-in Modifiers

If the language distinguish cases of character, you may need control the case of the linked locale messages.
Linked messages can be formatted with modifier *`@.modifier:key`*

The below modifiers are built-in available currently.

* `upper`: Uppercase all characters in the linked message
* `lower`: Lowercase all characters in the linked message
* `capitalize`: Capitalize the first character in the linked message

Locale messages the below:

```js
const messages = {
  en: {
    message: {
      homeAddress: 'Home address',
      missingHomeAddress: 'Please provide @.lower:message.homeAddress'
    }
  }
}
```

It’s `en` locale that has hierarchical structure in the object.

The `message.homeAddress` has `Home address`. The `message.missingHomeAddress` has `Please provide @.lower:message.homeAddress`, and it’s linked to the locale messages key with `message.homeAddress`.

Since the modifier `.lower` is specified in the above example, so the linked `message.homeAddress` key is resolved, after that is evaluated it.

The following is an example of the use of `$t` in a template:

```html
<label>{{ $t('message.homeAddress') }}</label>
<p class="error">{{ $t('message.missingHomeAddress') }}</p>
```

As result the below:

```html
<label>Home address</label>
<p class="error">Please provide home address</p>
```

### Custom Modifiers

If you want to use non built-in modifiers, you can use your custom modifiers.

To use custom modifiers, you must specify them in `modifiers` option of `createI18n`:

```js
const i18n = createI18n({
  locale: 'en',
  messages: {
    // set something locale messages ...
  },
  // set custom modifiers at `modifiers` option
  modifiers: {
    snakeCase: (str) => str.split(' ').join('_')
  }
})
```

Locale messages the below:

```js
const messages = {
  en: {
    message: {
      snake: 'snake case',
      custom_modifier: "custom modifiers example: @.snakeCase:{'message.snake'}"
    }
  }
}
```

It’s `en` locale that has hierarchical structure in the object.

The `message.snake` has `snake case`. The `message.custom_modifier` has `custom modifiers example: @.snakeCase:{'message.snake'}`, and it’s linked to the locale messages key, which is interpolated with literal.

:::tip NOTE
You can use the interpolations (Named, List, and Literal) for the key of Linked messages.
:::

This example shows the use of modifiers (`@.lower`, `@.upper`, `@.capitalize`) combined with named, list, and literal interpolations.

```js
const messages = {
  en: {
    message: {
      greeting: "Hello, @.lower:{'message.name'}! You have {count} new messages.",
      name:"{name}"
    },

    welcome: "Welcome, @.upper:{'name'}! Today is @.capitalize:{'day'}.",
    name: '{0}',
    day: '{1}',

    literalMessage: "This is an email: foo{'@'}@.lower:domain",
    domain: 'SHOUTING'
  }
}
```

### Named interpolation with modifier

In `message.greeting`, we use a named interpolation for `{count}` and link to `message.name`, applying the .lower modifier.

The key `message.name` contains `{name}`, which will be interpolated with the passed `name` param.

The `message.greeting` is linked to the locale message key `message.name`.

```html
<p>{{ $t('message.greeting', { name: 'Alice', count: 5 }) }}</p>
```

As result, the below

```html
<p>Hello, alice! You have 5 new messages.</p>
```

### List interpolation with modifier

In this case, the values for `{0}` and `{1}` are passed as an array. The keys `name` and `day` are resolved using list interpolation and transformed with modifiers.

```html
<p>{{ $t('welcome', ['bob', 'MONDAY']) }}</p>
```

As result, the below

```html
<p>Welcome, BOB! Today is Monday.</p>
```

### Literal interpolation with modifier

In this example, we use a literal string inside the message and apply the `.lower` modifier.

```html
<p>{{ $t('literalMessage') }}</p>
```

Here, the modifier is applied to the content inside `domain`, and the `@` is preserved as literal output.

As result, the below

```html
<p>This is an email: foo@shouting</p>
```

## Special Characters

The following characters used in the message format syntax are processed by the compiler as special characters:

* `{`
* `}`
* `@`
* `$`
* `|`

If you want to use these characters, you can use the [Literal interpolation](#literal-interpolation) or **escape sequences**.

### Escape Sequences

:::tip NOTE
Escape sequences are supported from v11.3 onwards.
:::

You can escape special characters with a backslash (`\`) prefix, similar to escape sequences in C:

| Escape | Result | Description |
|--------|--------|-------------|
| `\{` | `{` | Literal open brace |
| `\}` | `}` | Literal close brace |
| `\@` | `@` | Literal at sign |
| `\|` | `\|` | Literal pipe |
| `\\` | `\` | Literal backslash |

For example, the following locale messages resource:

```js
const messages = {
  en: {
    address: '{account}\\@{domain}',
    braces: 'hello \\{world\\}',
    choices: 'option A \\| option B'
  }
}
```

The following is an example of the use of `$t` in a template:

```html
<p>{{ $t('address', { account: 'foo', domain: 'domain.com' }) }}</p>
<p>{{ $t('braces') }}</p>
<p>{{ $t('choices') }}</p>
```

As result the below:

```html
<p>foo@domain.com</p>
<p>hello {world}</p>
<p>option A | option B</p>
```

:::tip NOTE
A backslash followed by a character that is not a special character is treated as a literal backslash. For example, `\n` in a message remains as `\n` (backslash + n), not a newline.
:::

## Rails i18n format

Vue I18n supports the message format that is compatible with [Ruby on Rails i18n](https://guides.rubyonrails.org/i18n.html).

You can interpolate message format syntax with `%` prefixing:

:::danger IMPORTANT
In v10 and later, Rails i18n format will be deprecated. We recommend using Named interpolation.
:::

As an example, the following locale messages resource:

```js
const messages = {
  en: {
    message: {
      hello: '%{msg} world'
    }
  }
}
```

It is defined `en` locale with `{ message: { hello: '%{msg} world' } }`.

As with [Named interpolation](#named-interpolation), you can specify variables defined in JavaScript. In the locale message above, it is possible to localize it by giving a JavaScript defined `msg` as a parameter to the translation function.

The following is an example of the use of `$t` in a template:

```html
<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>
```

As result, the below:

```html
<p>hello world</p>
```

## HTML Message

You can localize it with messages that contain HTML.

:::danger DANGER
:warning: Dynamically localizing arbitrary HTML on your site can be very dangerous because it can easily lead to XSS vulnerabilities. Only use HTML interpolation on trusted content and never on user-provided content.

We recommended using the [Component interpolation](../advanced/component).
:::

:::warning NOTICE
If the message contains HTML, Vue I18n outputs a warning to console when development mode (`process.env``.NODE_ENV !== 'production'`), Vue I18n outputs  warning to console.

You can control warning output with the `warnHtmlInMessage` or `warnHtmlMessage` options in `createI18n` or `useI18n`.
:::

As an example, the following locale messages resource:

```js
const messages = {
  en: {
    message: {
      hello: 'hello <br> world'
    }
  }
}
```

It is defined `en` locale with `{ message: { hello: 'hello <br> world' } }`.

The following is an example of the use of `v-html` and `$t` in a template:

```html
<p v-html="$t('message.hello')"></p>
```

As result, the below:

```html
<p>hello
<!--<br> exists but is rendered as html and not a string-->
world</p>
```

### Using the escape parameter option

To help mitigate XSS risks when using HTML messages, Vue I18n provides escape parameter options. When enabled, this option escapes interpolation parameters and sanitizes the final translated HTML.

:::tip NOTE
The option name depends on which API mode you're using:

* **Legacy API**: use `escapeParameterHtml`
* **Composition API**: use `escapeParameter`
  :::

#### Legacy API

```js
// enable `escapeParameterHtml` globally
const i18n = createI18n({
  locale: 'en',
  legacy: true,
  escapeParameterHtml: true,
  messages: {
    en: {
      message: {
        welcome: 'Welcome <strong>{name}</strong>!'
      }
    }
  }
})

// or enable it per translation
this.$t('message.welcome', { name: userInput }, { escapeParameter: true })
```

#### Composition API

```js
// enable `escapeParameter` globally
const i18n = createI18n({
  locale: 'en',
  escapeParameter: true,
  messages: {
    en: {
      message: {
        welcome: 'Welcome <strong>{name}</strong>!'
      }
    }
  }
})

// or enable it per translation
const { t } = useI18n()
t('message.welcome', { name: userInput }, { escapeParameter: true })
```

#### How it works

When the escape parameter option is enabled:

* HTML special characters (`<`, `>`, `"`, `'`, `&`, `/`, `=`) in interpolation parameters are escaped
* The final translated HTML is sanitized to prevent XSS attacks:
  * Dangerous characters in HTML attribute values are escaped
  * Event handler attributes (`onclick`, `onerror`, etc.) are neutralized
  * The `srcdoc` attribute of `<iframe>` is neutralized, because its value is parsed as a nested HTML document
  * JavaScript URLs in href, src, action, formaction, and style attributes are disabled

#### Example

```js
const userInput = '<img src=x onerror=alert(1)>'

// Without escape parameter (DANGEROUS):
$t('message.welcome', { name: userInput })
// Result: Welcome <strong><img src=x onerror=alert(1)></strong>!

// With escape parameter (SAFE):
$t('message.welcome', { name: userInput }, { escapeParameter: true })
// Result: Welcome <strong>&lt;img src&#x3D;x onerror&#x3D;alert(1)&gt;</strong>!
```

:::warning IMPORTANT
Even with the escape parameter option enabled, you should still be cautious about using HTML in translations. Always validate and sanitize user input before using it in translations, and prefer [Component interpolation](../advanced/component) when possible.
:::

---

---
url: /guide/advanced/function.md
---
# Messages Functions

Vue I18n recommends using the string base on list, named, and literal format as locale messages when translating messages.

However, sometimes string-based message format syntax is difficult to resolve.

For example, suppose you want to handle the following message in French:

* Manger de la soupe
* Manger une pomme
* Manger du pain
* Manger de l’orge

As you can see, the article preceding the noun will vary based on gender and phonetics.

The features supported by Vue I18n  Message Format Syntax may not be able to support these language-specific use cases.

There are situations however, where you really need the full programmatic power of JavaScript, due to the complex language syntax.
So instead of string-based messages, you can use the **Message functions**.

:::tip NOTE
The messages written in message format syntax are compiled into message functions with Vue I18n message compiler. Message functions and caching mechanism to maximize performance gains.
:::

## Basic usage

The following is a message function that returns a simple greeting:

```js
const messages = {
  en: {
    greeting: (ctx) => 'hello!'
  }
}
```

The message function accept the **Message context** as the first argument, which has several props and functions. We’ll explain how to use it in the following sections, so let’s go on.

The use of the message function is very easy! You just specify the key of the message function with `$t` or `t`:

```html
<p>{{ $t('greeting') }}</p>
```

Output is the below:

```html
<p>hello!</p>
```

The message function outputs the message of the return **string** value of the message function.

:::tip NOTE
If you need to use the Translation component (`i18n-t`), you need to support returning not only the string value, but also the **VNode** value.

To support for Translation component usage, the `type` prop of MessageContext is used as shown in the following code example:

```js
import { createVNode, Text } from 'vue'

const messages = {
  en: {
    greeting: ({ type }) => type === 'vnode'
      ? createVNode(Text, null, 'hello', 0)
      : 'hello'
  }
}
```

If you haven’t already, it’s recommended to read through the [Vue render function](https://v3.vuejs.org/guide/render-function.html#the-dom-tree) before diving into message functions.
:::

## Named interpolation

Vue I18n supports [named interpolation](../essentials/syntax#named-interpolation) as a string-based message format. Vue I18n interpolate the parameter values with `$t` or `t`, and it can be output it.

You can use the `named` function of the message context to do the same thing.

Here is the example of greeting:

```js
const messages = {
  en: {
    greeting: ({ named }) => `hello, ${named('name')}!`
  }
}
```

Template:

```html
<p>{{ $t('greeting', { name: 'DIO' }) }}</p>
```

Output is the below:

```html
<p>hello, DIO!</p>
```

You need to specify the key that resolves the value specified with the named of `$t` or `t`.

## List interpolation

Vue I18n supports [list interpolation](../essentials/syntax#list-interpolation) as a string-based message format. Vue I18n interpolate the parameter values with `$t` or `t`, and it can be output it.

You can use the `list` function of the message context to do the same thing.

Here is the example of greeting:

```js
const messages = {
  en: {
    greeting: ({ list }) => `hello, ${list(0)}!`
  }
}
```

Template:

```html
<p>{{ $t('greeting', ['DIO']) }}</p>
```

Output is the below:

```html
<p>hello, DIO!</p>
```

You need to specify the index that resolves the value specified with the list of `$t` or `t`.

## Linked messages

Vue I18n supports [linked messages](../essentials/syntax#linked-messages) as a string-based message format. Vue I18n interpolate the parameter values with `$t` or `t`, and it can be output it.

You can use the `linked` function of the message context to do the same thing.

Here is the example of message function:

```js
const messages = {
  en: {
    the_world: 'the world',
    dio: 'DIO:',
    linked: ({ linked }) => `${linked('message.dio')} ${linked('message.the_world')} !!!!`
  }
}
```

Template:

```html
<p>{{ $t('linked') }}</p>
```

Output is the below:

```html
<p>DIO: the world !!!!</p>
```

You need to specify the key that resolves the value specified with `$t` or `t`.

## Pluralization

Vue I18n supports [pluralization](../essentials/pluralization) as a string-based message format. Vue I18n interpolate the parameter values with `$t` or `t`, and it can be output it.

You can use the `plural` function of the message context to do the same thing.

Here is the example of message function:

```js
const messages = {
  en: {
    car: ({ plural }) => plural(['car', 'cars']),
    apple: ({ plural, named }) =>
      plural([
        'no apples',
        'one apple',
        `${named('count')} apples`
      ])
  }
}
```

Template:

```html
<p>{{ $t('car', 1) }}</p>
<p>{{ $t('car', 2) }}</p>

<p>{{ $t('apple', 0) }}</p>
<p>{{ $t('apple', 1) }}</p>
<p>{{ $t('apple', { count: 10 }, 10) }}</p>
```

Output is the below:

```html
<p>car</p>
<p>cars</p>

<p>no apples</p>
<p>one apple</p>
<p>10 apples</p>
```

You need to specify the key that resolves the value specified with `$t` or `t`.

---

---
url: /guide/migration/vue2.md
---
# Migration from Vue 2

## `vue-i18n-bridge`

:::danger NOTE
vue-i18n-bridge will not be provided in v10 due to Vue 2 EOL. v9.13 will be the last version.
:::

### What is `vue-i18n-bridge`?

`vue-i18n-bridge` is a bridge to make the upgrade as easy as possible between vue-i18n@v8.26.1 or later and vue-i18n@v9.x.

It can be used in Vue 2 applications that you have already built with vue-i18n@v8.26.1 or later.

And, also some features are backported from vue-i18n@v9.x:

* Vue I18n Composition API, that is powered by `@vue/composition-api` and `vue-demi`
* Message format syntax, that is powered by `@intlify/message-compiler`

### Installation

#### Package manager

::: code-group

```sh [npm]
npm install vue-i18n-bridge
```

```sh [yarn]
yarn add vue-i18n-bridge
```

```sh [pnpm]
pnpm add vue-i18n-bridge
```

:::

You must install the below packages before using this library:

* vue-i18n: >= v8.26.1 < v9
* vue-demi: >= v0.13.5
* @vue/composition-api: >= v1.2.0 (if you will use Vue 2.6)

#### CDN

**For Vue 2.7**:

Include `vue-i18n-bridge` after `vue`, `vue-demi` and it will install.

```html
<script src="https://cdn.jsdelivr.net/npm/vue@2.7"></script>
<script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
<script src="https://unpkg.com/vue-demi@0.13.5/lib/index.iife.js"></script>
<script src="https://unpkg.com/vue-i18n-bridge@9.2.0-beta.38/dist/vue-i18n-bridge.global.prod.js"></script>
```

**For Vue 2.6**:

Include `vue-i18n-bridge` after `vue`, `@vue/composition-api`, `vue-demi` and it will install.

```html
<script src="https://cdn.jsdelivr.net/npm/vue@2.6"></script>
<script src="https://unpkg.com/vue-i18n@8/dist/vue-i18n.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@vue/composition-api@1.4"></script>
<script src="https://unpkg.com/vue-demi@0.13.5/lib/index.iife.js"></script>
<script src="https://unpkg.com/vue-i18n-bridge@9.2.0-beta.38/dist/vue-i18n-bridge.global.prod.js"></script>
```

### Usage

#### Composition API

**For Vue 2.7**:

```js
import Vue from 'vue'
import { createApp } from 'vue-demi'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n

// `createI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
const i18n = createI18n({
  legacy: false,
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n`

const app = createApp({
 setup() {
   // `useI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
   const { t, locale } = useI18n()
   // ... todo something

   return { t, locale }
 }
})

app.use(i18n) // you must install `i18n` instance which is created by `createI18n`
app.mount('#app')
```

**For Vue 2.6**:

```js
import Vue from 'vue'
import VueCompositionAPI, { createApp } from '@vue/composition-api'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n

// `createI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
const i18n = createI18n({
  legacy: false,
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n`

const app = createApp({
 setup() {
   // `useI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
   const { t, locale } = useI18n()
   // ... todo something

   return { t, locale }
 }
})

app.use(i18n) // you must install `i18n` instance which is created by `createI18n`
app.mount('#app')
```

#### Legacy API

**For Vue 2.7**:

```js
import Vue from 'vue'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n

// `createI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n`

Vue.use(i18n) // you must install `i18n` instance which is created by `createI18n`

const app = new Vue({ i18n })
app.$mount('#app')
```

**For Vue 2.6**:

```js
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { createI18n, useI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true }) // you must specify '{ bridge: true }' plugin option when install vue-i18n

// `createI18n` options is almost same vue-i18n (vue-i18n@v9.x) API
const i18n = createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n) // `createI18n` which is provide `vue-i18n-bridge` has second argument, you **must** pass `VueI18n` constructor which is provide `vue-i18n`

Vue.use(i18n) // you must install `i18n` instance which is created by `createI18n`

const app = new Vue({ i18n })
app.$mount('#app')
```

**For TypeScript:**

```ts
import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'
import { createI18n, useI18n, castToVueI18n } from 'vue-i18n-bridge'

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true })

// you need to cast `i18n` instance
const i18n = castToVueI18n(createI18n({
  locale: 'ja',
  messages: {
    en: {
      message: {
        hello: 'hello, {name}!'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、{name}！'
      }
    }
  }
}, VueI18n))

Vue.use(i18n)

const app = new Vue({ i18n })
app.$mount('#app')
```

### Usage UMD module in browser

#### For Vue 2.7

```js
const { createApp } = VueDemi // exported UMD which is named by `VueDemi`
const { createI18n, useI18n } = VueI18nBridge // exported UMD which is named by `VueI18nBridge`

Vue.use(VueI18n, { bridge: true })

const i18n = createI18n({
  locale: 'ja',
  messages: {
    // ...
  }
}, VueI18n)

const app = createApp({}, {
  // ...
})
app.use(i18n)
app.mount('#app') // Vue app host container element
```

#### For Vue 2.6

```js
const { createApp } = VueCompositionAPI // exported UMD which is named by `VueCompositionAPI`
const { createI18n, useI18n } = VueI18nBridge // exported UMD which is named by `VueI18nBridge`

Vue.use(VueCompositionAPI)
Vue.use(VueI18n, { bridge: true })

const i18n = createI18n({
  locale: 'ja',
  messages: {
    // ...
  }
}, VueI18n)

const app = createApp({}, {
  // ...
})
app.use(i18n)
app.mount('#app') // Vue app host container element
```

### Limitations

* In Legacy API mode, You **cannot use [new message format syntax](https://vue-i18n.intlify.dev/guide/essentials/syntax.html)** by porting from `vue-i18n`
  * it use possible only Composition API mode
* In Legacy API mode, You **cannot use back-ported components that are following components** by porting from `vue-i18n`
  * Translation components: `<i18n-t>`
  * DateTime format components: `<i18n-d>`
  * Number format components: `<i18n-n>`
* In Composition API mode, the below APIs is prefixed with `$` is **global scope**
  * `$t`
  * `$d`
  * `$n`

### Explanation of Different Builds

In the [dist/ directory of the npm package](https://unpkg.com/browse/vue-i18n-bridge@9.2.0-beta.6/dist/) you will find many different builds of `vue-i18n-bridge`. Here is an overview of which dist file should be used depending on the use-case.

#### From CDN or without a Bundler

* **`vue-i18n-bridge(.runtime).global(.prod).js`**:
  * For direct use via `<script src="...">` in the browser. Exposes the `VueI18nBridge` global
  * In-browser message format compilation:
    * `vue-i18n-bridge.global.js` is the "full" build that includes both the compiler and the runtime so it supports compiling message formats on the fly
    * `vue-i18n-bridge.runtime.global.js` contains only the runtime and requires message formats to be pre-compiled during a build step
  * Inlines all Vue I18n core internal packages - i.e. it’s a single file with no dependencies on other files. This means you **must** import everything from this file and this file only to ensure you are getting the same instance of code
  * Contains hard-coded prod/dev branches, and the prod build is pre-minified. Use the `*.prod.js` files for production

:::warning NOTICE
Global builds are not [UMD](https://github.com/umdjs/umd) builds. They are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) and are only meant for direct use via `<script src="...">`.
:::

* **`vue-i18n-bridge(.runtime).esm-browser(.prod).js`**:
  * For usage via native ES modules imports (in browser via `<script type="module">`)
  * Shares the same runtime compilation, dependency inlining and hard-coded prod/dev behavior with the global build

#### With a Bundler

* **`vue-i18n-bridge(.runtime).esm-bundler.js`**:
  * For use with bundlers like `webpack`, `rollup` and `parcel`
  * Leaves prod/dev branches with `process.env``.NODE_ENV` guards (must be replaced by bundler)
  * Does not ship minified builds (to be done together with the rest of the code after bundling)
  * Imports dependencies (e.g. `@intlify/core-base`, `@intlify/message-compiler`)
    * Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@intlify/message-compiler` imports `@intlify/shared`)
    * This means you **can** install/import these deps individually without ending up with different instances of these dependencies, but you must make sure they all resolve to the same version
  * In-browser locale messages compilation:
    * **`vue-i18n-bridge.runtime.esm-bundler.js`** is runtime only, and requires all locale messages to be pre-compiled. This is the default entry for bundlers (via `module` field in `package.json`) because when using a bundler templates are typically pre-compiled (e.g. in `*.json` files)
    * **`vue-i18n-bridge.esm-bundler.js` (default)**: includes the runtime compiler. Use this if you are using a bundler but still want locale messages compilation (e.g. templates via inline JavaScript strings).  To use this build, change your import statement to: `import { createI18n } from "vue-i18n-bridge/dist/vue-i18n-bridge.esm-bundler.js";`

:::warning NOTICE
If you use `vue-i18n-bridge.runtime.esm-bundler.js`, you will need to precompile all locale messages, and you can do that with `.json` (`.json5`) or `.yaml`, i18n custom blocks to manage i18n resources. Therefore, you can be going to pre-compile all locale messages with bundler and the following loader / plugin.

* [`@intlify/unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n)
  :::

#### For Node.js (Server-Side)

* **`vue-i18n-bridge.cjs(.prod).js`**:
  * For use in Node.js via `require()`
  * If you bundle your app with webpack with `target: 'node'` and properly externalize `vue-i18n-bridge`, this is the build that will be loaded
  * The dev/prod files are pre-built, but the appropriate file is automatically required based on `process.env``.NODE_ENV`

## `vue-i18n-composable`

Composition API is supported from Vue 3, and you can use the official [`@vue/composition-api`](https://github.com/vuejs/composition-api) plugin to make the Composition API available to Vue 2.

Vue I18n Composition API is also available in Vue 2 using the `vue-i18n-composable` plugin.

About how to usage, See the [here](https://github.com/intlify/vue-i18n-composable)

:::warning NOTICE
`vue-i18n-composable` allows the main API of Vue I18n v8.x to work with the Composition API. All of Composition API provided in Vue I18n v9 are not available.
:::

---

---
url: /guide/migration/vue3.md
---
# Migration in Vue 3

## Migration to Composition API from Legacy API

### Summary

Vue I18n supports both styles which are Legacy API mode and Composition API mode. Legacy API mode is Options API style, and Composition API mode support Vue Composition API that is able to compose with function.

Legacy API mode is almost compatible with legacy Vue I18n v8.x, making it relatively easy to migrate Vue applications to Vue 3. Vue 3 supports the Options API style, so existing Vue 2 applications will be cases where applications will be migrated to Vue 3.

Vue 3 allows you to make Vue applications using a mix of the Options API style and Composition API style, but Vue I18n has not allowed for a mix of these API styles since the v9 initial release, so you can use either one or the other API style only.

Developing a Vue application with a mix of Options API styles and Compostion API styles is not a desirable software development project from a maintenance standpoint. This is because the cost of maintaining such code is high. However, there are advantages to using both styles. In particular, API style migration is easier to migrate step-by-step, since it works even when implemented in both API styles.

From Vue I18n v9.2, the Legacy API mode can also be used with Composition API mode.

### About supporting

:::danger NOTICE
This migration support will be removed in the next major version v10. If your Vue 3 application project has not yet been migrated, please migrate it to v9 and then upgrade to v10.
:::

### Limitations

:::warning NOTICE
You should understand as a limited feature for migration.
:::

* The Composition API in Legacy API mode does not support SSR
* If you want to use correctly Vue I18n Composition API (e.g `t`) on `setup` function context directly not `<template>`, you need to call via `nextTick` callback context.

### How to migration

#### `createI18n`

You need specify `allowComposition: true` to `createI18n` options. the below example:

```js
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: 'en',
  allowComposition: true, // you need to specify that!
  messages: {
    en: {
      hello: 'hello!'
    },
    ja: {
      hello: 'こんにちは！'
    }
  }
})

console.log(i18n.allowComposition) // output is true
```

### `useI18n` in Vue Component

#### `setup` option

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

export default defineComponent({
  name: 'Hello',
  setup() {
    const { t } = useI18n() // use as global scope
    return { t }
  }
})
</script>

<template>
  <p>{{ $t('hello') }}</p>
  <p>{{ t('hello') }}</p>
</template>
```

#### `<script setup>`

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

const { t } = useI18n() // use as global scope
</script>

<template>
  <p>{{ $t('hello') }}</p>
  <p>{{ t('hello') }}</p>
</template>
```

---

---
url: /guide/migration/features.md
---
# New Features in v9

Vue I18n v9 offers not only Vue 3 support, but this version also is included new features.

## Message format syntax

* See the [Literal interpolation](../essentials/syntax#literal-interpolation)

## Message functions

* See the [Linked messages](../advanced/function#linked-messages)
* See the [Pluralization](../advanced/function#pluralization)

## Composition API

See the [Composition API](../advanced/composition) advanced section

## Translation Component

Support for `plural` prop.
You can specify the number of messages to be pluralized.

The below example:

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

const { t } = useI18n({
  locale: 'en',
  messages: {
    en: {
      message: {
        plural: 'no bananas | {n} banana | {n} bananas'
      }
    }
  }
})

const count = ref(0)
</script>

<template>
  <i18n-t keypath="message.plural" :plural="count">
    <template #n>
      <b>{{ count }}</b>
    </template>
  </i18n-t>
</template>
```

## DatetimeFormat Component

For Datetime localization, since Vue I18n v9, we also offer the DatetimeFormat component like the [NumberFormat component](../essentials/number#custom-formatting).

See the [Datetime localization custom formatting](../essentials/datetime#custom-formatting)

## i18n Custom Block

* See the [`global` attribute](../advanced/sfc#define-locale-messages-for-global-scope)

---

---
url: /guide/essentials/number.md
---
# Number Formatting

## Basic Usage

You can localize the number with your definition formats.

Number formats the below:

```js
const numberFormats = {
  'en-US': {
    currency: {
      style: 'currency', currency: 'USD', notation: 'standard'
    },
    decimal: {
      style: 'decimal', minimumFractionDigits: 2, maximumFractionDigits: 2
    },
    percent: {
      style: 'percent', useGrouping: false
    }
  },
  'ja-JP': {
    currency: {
      style: 'currency', currency: 'JPY', useGrouping: true, currencyDisplay: 'symbol'
    },
    decimal: {
      style: 'decimal', minimumSignificantDigits: 3, maximumSignificantDigits: 5
    },
    percent: {
      style: 'percent', useGrouping: false
    }
  }
}
```

As the above, you can define named number formats (e.g. `currency`, etc), and you need to use [the options with ECMA-402 Intl.NumberFormat](https://tc39.es/ecma402/#numberformat-objects)

After that, when using the locale messages, you need to specify the `numberFormats` option of `createI18n`:

```js
const i18n = createI18n({
  numberFormats
})
```

To localize Number value with Vue I18n, use the `$n`.

:::tip NOTE
`$n` has some overloads. About these overloads, see the [API Reference](../../api/injection#n-value)
:::

The following is an example of the use of `$n` in a template:

```html
<p>{{ $n(10000, 'currency') }}</p>
<p>{{ $n(10000, 'currency', 'ja-JP') }}</p>
<p>{{ $n(10000, 'currency', 'ja-JP', { useGrouping: false }) }}</p>
<p>{{ $n(987654321, 'currency', { notation: 'compact' }) }}</p>
<p>{{ $n(0.99123, 'percent') }}</p>
<p>{{ $n(0.99123, 'percent', { minimumFractionDigits: 2 }) }}</p>
<p>{{ $n(12.11612345, 'decimal') }}</p>
<p>{{ $n(12145281111, 'decimal', 'ja-JP') }}</p>
```

The first argument is numeric value as a parameter, and the second argument is number format name as a parameter. The last argument locale value as a parameter.

As result the below:

```html
<p>$10,000.00</p>
<p>￥10,000</p>
<p>￥10000</p>
<p>$988M</p>
<p>99%</p>
<p>99.12%</p>
<p>12.12</p>
<p>12,145,000,000</p>
```

## Custom Formatting

`$n` returns resulting string with fully formatted number, which can only be used as a whole. In situations when you need to style some part of the formatted number (like fraction digits), `$n` is not enough. In such cases NumberFormat component (`i18n-n`) will be of help.

With a minimum set of properties, `i18n-n` generates the same output as `$n`, wrapped into configured DOM element.

The following template:

```html
<i18n-n tag="span" :value="100"></i18n-n>
<i18n-n tag="span" :value="100" format="currency"></i18n-n>
<i18n-n tag="span" :value="100" format="currency" locale="ja-JP"></i18n-n>
```

NumberFormat component has some props.

The `tag` is the property to set the tag.

The `value` is the property to set the numeric value to be formatted.

The `format` is the property to which the format defined by the `numberFormats` option of `createI18n` can be set.

The `locale` is the property to set the locale. It's localized with the locale specified by this prop instead of the one specified with the `locale` option of `createI18n`.

Will produce the below output:

```html
<span>100</span>
<span>$100.00</span>
<span>￥100</span>
```

But the real power of this component comes into play when it is used with [scoped slots](https://v3.vuejs.org/guide/component-slots.html#scoped-slots).

Let’s say there is a requirement to render the integer part of the number with a bolder font. This can be achieved by specifying `integer` scoped slot element:

```html
<i18n-n tag="span" :value="100" format="currency">
  <template #integer="slotProps">
    <span style="font-weight: bold">{{ slotProps.integer }}</span>
  </template>
</i18n-n>
```

Template above will result in the following HTML:

```html
<span>$<span style="font-weight: bold">100</span>.00</span>
```

It is possible to specify multiple scoped slots at the same time:

```html
<i18n-n tag="span" :value="1234" :format="{ key: 'currency', currency: 'EUR' }">
  <template #currency="slotProps">
    <span style="color: green">{{ slotProps.currency }}</span>
  </template>
  <template #integer="slotProps">
    <span style="font-weight: bold">{{ slotProps.integer }}</span>
  </template>
  <template #group="slotProps">
    <span style="font-weight: bold">{{ slotProps.group }}</span>
  </template>
  <template #fraction="slotProps">
    <span style="font-size: small">{{ slotProps.fraction }}</span>
  </template>
</i18n-n>
```

(this resulting HTML was formatted for better readability)

```html
<span>
  <span style="color: green">€</span>
  <span style="font-weight: bold">1</span>
  <span style="font-weight: bold">,</span>
  <span style="font-weight: bold">234</span>
  .
  <span style="font-size: small">00</span>
</span>
```

:::tip NOTE
Full list of the supported scoped slots as well as other `i18n-n`, properties can be found on [API Reference](../../api/component.html#numberformat).
:::

## Scope resolving

The Scope resolving of NumberFormat component is same as Translation component.

See the [here](../advanced/component.md#scope-resolving)

---

---
url: /guide/integrations/nuxt3.md
---
# Nuxt 3 integration

We recommend using [Nuxt I18n (@nuxtjs/i18n)](https://i18n.nuxtjs.org/) to use Vue I18n with Nuxt 3 with advanced features such as localized routing, SEO tags and more.

## Creating your own Nuxt 3 integration

The following is a tutorial on setting up a Nuxt 3 application with your own integration by adding Vue I18n through a Nuxt plugin.

:::warning NOTICE
This integration tutorial doesn't support advanced i18n features (such routing and SEO tags) and is intended for demonstration purposes, consider using the Nuxt I18n module check out its docs at [i18n.nuxtjs.org](https://i18n.nuxtjs.org/) for more details.
:::

## Requirements

Node.js requirement for this tutorial is the same environment as Nuxt 3.

Please check [here](https://nuxt.com/docs/getting-started/installation#prerequisites) for Node.js version of Nuxt 3.

## Example codes

You can get the code for the tutorial below on [examples/frameworks/nuxt3](https://github.com/intlify/vue-i18n/tree/master/examples/frameworks/nuxt3).

You can also see a deployed app made following this tutorial with a custom GitHub action to provide translations from DeepL in this [nuxt3-app-vue-i18n](https://github.com/lyqht/nuxt3-app-vue-i18n) project.

## Setup vue-i18n on Nuxt 3 Application

We will now set up the initial environment for using Vue I18n with Nuxt 3.

### Create Nuxt 3 application

Run the following command to create a Nuxt 3 application:

::: code-group

```sh [npx]
npx nuxi init nuxt3-app-vue-i18n
```

```sh [pnpm]
pnpm dlx nuxi init nuxt3-app-vue-i18n
```

:::

Once we have run the above command, the created Nuxt 3 initial project will have the following directory structure:

```
cd nuxt3-app-vue-i18n
tree -L 1
.
├── README.md
├── app.vue
├── nuxt.config.ts
├── package.json
└── tsconfig.json
```

### Install Vue I18n

Install Vue I18n with the following command:

::: code-group

```sh [npm]
npm install vue-i18n -D
```

```sh [yarn]
yarn add vue-i18n -D
```

```sh [pnpm]
pnpm add -D vue-i18n
```

:::

### Setup Nuxt plugin

Create a `plugins` directory as follows:

```sh
mkdir plugins
```

Next, create a Nuxt plugin file to set up Vue I18n.

```sh
touch plugins/i18n.ts
```

Once created, define the plugin as follows:

```ts
import { createI18n } from 'vue-i18n'

export default defineNuxtPlugin(({ vueApp }) => {
  const i18n = createI18n({
    legacy: false,
    globalInjection: true,
    locale: 'en',
    messages: {
      en: {
        hello: 'Hello, {name}!'
      }
    }
  })

  vueApp.use(i18n)
})
```

Configuration of locale resources to localize a Nuxt 3 application is described in the [next section](#localize-your-nuxt-3-application)

### Run the Nuxt 3 application

Let's see if Vue I18n works with Nuxt 3.

We will edit `app.vue` of the setup Nuxt 3 application as follows:

```vue
<template>
  <div>
   <NuxtWelcome /> // [!code --]
   <h1>{{ $t('hello', { name: 'vue-i18n' }) }}</h1> // [!code ++]
  </div>
</template>
```

We have edited and saved, run the following command to run the Nuxt 3 application in local:

::: code-group

```sh [npm]
npm run dev
```

```sh [yarn]
yarn dev
```

```sh [pnpm]
pnpm dev
```

:::

Once the application is served on `http://localhost:3000`, we'll see the following:

![Nuxt3 setup](/nuxt3-setup.png)

## Localize your Nuxt 3 application

So far, we have been able to integrate Vue I18n into our Nuxt 3 application. Let's implement language switching and import locale resources from outside.

By implementing language switching we are effectively, i18n our Nuxt 3 application. 🌎 🌍 🌏

Also, when we separate the locale resources from the source code (externalizing them), we can use a separate workflow with the help of the Localization service in order to localize the app.

In the following sections, we will enable support for English, French, and Japanese on out Nuxt 3 app.

### Add language switching

We will add language switching feature to `app.vue` as follows:

```vue
<template>
  <div>
    <h1>{{ $t('hello', { name: 'vue-i18n' }) }}</h1>
    <form> // [!code ++]
      <label for="locale-select">{{ $t('language') }}: </label> // [!code ++]
      <select id="locale-select" v-model="$i18n.locale"> // [!code ++]
        <option value="en">en</option> // [!code ++]
        <option value="fr">fr</option> // [!code ++]
        <option value="ja">ja</option> // [!code ++]
      </select> // [!code ++]
    </form> // [!code ++]
  </div>
</template>
```

Language switching is implemented using the `select` element on `form`.
The value of each option is defined as the value of the locale code, which will be explained later in the externalization of locale resources.

The value of each option defines the value of the locale code, which will be explained later in the externalization of locale resources.

### Externalize locale resources

We will define the locale resources as external.

There are several file formats for resources supported by Vue I18n, we'll opt for JSON in this particular case.

Let's create a non-"Nuxt-3-standard" directory named `locales` by running:

```sh
mkdir locales
```

Now, let's create the JSON files for each of the locales we want to support:

```sh
touch locales/en.json # for english
touch locales/fr.json # for french
touch locales/ja.json # for japanese
```

Let's populate them with the following:

For english at `locales/en.json`:

```json
{
  "hello": "Hello, {name}!",
  "language": "Language"
}
```

For french at `locales/fr.json`:

```json
{
  "hello": "Bonjour, {name}!",
  "language": "Langue"
}
```

For japanese at `locales/ja.json`:

```json
{
  "hello": "こんにちは、{name}！",
  "language": "言語"
}
```

### Import locale resources

Let's "register" the locales in our plugin (`plugins/i18n.ts`) as follows:

```js
import { createI18n } from 'vue-i18n'
import en from '../locales/en.json' // [!code ++]
import fr from '../locales/fr.json' // [!code ++]
import ja from '../locales/ja.json' // [!code ++]

export default defineNuxtPlugin(({ vueApp }) => {
  const i18n = createI18n({
    legacy: false,
    globalInjection: true,
    locale: 'en',
    messages: {
      en: { // [!code --]
        hello: "Hello, {name}!" // [!code --]
      } // [!code --]
      en, // [!code ++]
      fr, // [!code ++]
      ja // [!code ++]
    }
  })

  vueApp.use(i18n)
})
```

The `messages` option will be the one holding the local resources we register to it and being as fine-grained as we want. This granularity facilitates integration with the localization service.

Let's run `npm run dev` (or `yarn dev` or `pnpm dev`) and head to `http://localhost:3000` to see if the changes so far work.

![Setup i18n on Nuxt3](/nuxt3-setup-i18n.gif)

The Nuxt 3 application is now ready for basic internationalization! 🎉

## Optimize with `@intlify/unplugin-vue-i18n`

So far, you have been able to use Vue I18n to support language switching on the Nuxt 3 application. Also, by externalizing the locale resources, you have separated them from the source code, making it easier to manage locale resources and integrate with the localization service.

However, as described in [Optimization](../advanced/optimization), the Nuxt 3 application prepared so far is sub-optimal in its bundle size.

Since Vue I18n v9, the message compiler allows pre-compiling of locale resources for improved performance, but has not yet been optimized for that performance.

Enter [@intlify/unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n), a Vue I18n to optimize performance.

### Install `@intlify/unplugin-vue-i18n`

::: code-group

```sh [npm]
npm install @intlify/unplugin-vue-i18n -D
```

```sh [yarn]
yarn add @intlify/unplugin-vue-i18n -D
```

```sh [pnpm]
pnpm add -D @intlify/unplugin-vue-i18n
```

:::

### Configure Nuxt config

Configure `nuxt.config.ts` like the below:

```js
import { defineNuxtConfig } from 'nuxt'
import { resolve, dirname } from 'node:path' // [!code ++]
import { fileURLToPath } from 'url' // [!code ++]
import VueI18nVitePlugin from '@intlify/unplugin-vue-i18n/vite' // [!code ++]

// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({
  build: { // [!code ++]
    transpile: ['vue-i18n'] // [!code ++]
  }, // [!code ++]
  vite: { // [!code ++]
    plugins: [ // [!code ++]
      VueI18nVitePlugin({ // [!code ++]
        include: [ // [!code ++]
          resolve(dirname(fileURLToPath(import.meta.url)), './locales/*.json') // [!code ++]
        ] // [!code ++]
      }) // [!code ++]
    ] // [!code ++]
  } // [!code ++]
})
```

The bundler for Nuxt 3 is vite by default. So we will use the `vite` option here for optimization.

In `vite.plugins`, the plugin for `@intlify/unplugin-vue-i18n` is configured. As an option for this plugin, the `include` option specifies locale resources in json format placed in the `locales` directory. This allows `@intlify/unplugin-vue-i18n` to pre-compile locale resources at bundle time using Vue I18n message compiler internally. This improves the translation performance of Vue I18n and consequently the rendering performance of Nuxt 3 applications.

### Inside of bundling with optimization

Once finished with the setup, run `npm run dev` to check it out!

After accessing `http://localhost:3000`, the behavior of the Nuxt 3 application remains the same, but there is a change in the bandwidth of the Nuxt 3 application.

The following is a comparison of bundle sizes measured in the network tab of devtools with and without `@intlify/unplugin-vue-i18n`:

![Reduce bundle size](/nuxt3-reduce-bundle-size.png)

The area highlighted in blue is the code bundled by vite.

By setting up this plugin, the plugin will internally set up a Vue I18n module that is runtime-only. Specifically, vite config `resolve.alias`, set the `vue-i18n` alias to use only the Vue I18n runtime (`vue-i18n/dist/vue-i18n.runtime.esm-bundler.js`). This setting reduces the bundle size since the message compiler used by Vue I18n is not included.

About details, see `@intlify/unplugin-vue-i18n` [docs](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n#runtimeonly)

Also, you can see the changes in the bundling of locale resources.

Code for locale resources, depending on whether or not the `@intlify/unplugin-vue-i18n` plugin to `vite.plugins` is set. Below:

![Pre-compile](/nuxt3-pre-compile.png)

Without the `@intlify/unplugin-vue-i18n` plugin to `vite.plugins`, locale resources are bundled as **json**, but with this plugin set, locale resources are **converted from json to JavaScript code** for bandwidth.

Vue I18n just call the functions since they have already been compiled.

In this guide, the Nuxt 3 application is small, so we can not enough experience the performance of the optimization but as the application gets larger, it will definitely benefit from it.

---

---
url: /ecosystem/official.md
---
# Official tooling

## Vue CLI Plugin

[vue-cli-plugin-i18n](https://github.com/kazupon/vue-cli-plugin-i18n) is officially provided as the Vue CLI Plugin.

With this plugin, you can setup the i18n environment for the Vue application, and support the i18n development environment.

## ESLint Plugin

[eslint-plugin-vue-i18n](https://github.com/intlify/eslint-plugin-vue-i18n) is ESLint plugin for Vue I18n.

It easily integrates some localization lint features to your Vue.js Application.

## Intlify CLI

[@intlify/cli](https://github.com/intlify/cli) is CLI Tooling for i18n development.

You can pre-compile i18n resources (`json5?`, `ya?ml`) with `intlify compile` command.

## Extensions

[vue-i18n-extensions](https://github.com/intlify/vue-i18n-extensions) provides some extensions for Vue I18n.

You can use this extension to enable SSR and improve i18n performance.

## Composition API for Vue 2.x

[vue-i18n-composable](https://github.com/intlify/vue-i18n-composable) provides Composition API for Vue I18n in Vue 2.x.

## Petite-Vue-I18n

[petite-vue-i18n](https://github.com/intlify/vue-i18n/tree/master/packages/petite-vue-i18n) is an alternative distribution of Vue I18n, which provides only minimal features.

Note that petite-vue-i18n is still experimental, so you may encounter bugs and unsupported use cases.

---

---
url: /guide/advanced/optimization.md
---
# Optimization

## Performance

As described in "[Different Distribution files](../extra/dist##from-cdn-or-without-a-bundler)" section, Vue I18n offer the following two built ES modules for Bundler.

* message compiler + runtime: **`vue-i18n.esm-bundler.js`**
* runtime only: **`vue-i18n.runtime.esm-bundler.js`**

For bundler, it’s configured to bundle `vue-i18n.esm-bundler.js` with [`@intlify/unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) as default. If you want to reduce the bundle size further, you can configure the bundler to use `vue-i18n.runtime.esm-bundler.js`, which is runtime only.

The use of ES Module `vue-i18n.runtime.esm-bundler.js` means that **all locale messages have to pre-compile to Message functions or AST resources**. What that means, is that it improves performance because vue-i18n only executes Message functions, so no compilation.

:::tip NOTE
Before v9.3, the locale messages will be compiled to Message functions, after v9.3 or later these will be compiled to AST with `@intlify/bundle-tools`.
:::

:::tip NOTE
Before v9.3, all locale messages are compiled with `@intlify/unplugin-vue-i18n`, so the message compiler is not bundled, **bundle size can be reduced**.

After v9.3, since the message compiler is also bundled, the bundle size cannot be reduced. **This is a trade-off**.
About the reason, See [JIT compilation for details](#jit-compilation).
:::

:::danger NOTE
If [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is enabled in before v9.3, `vue-i18n.esm-bundler.js` would not work with compiler due to `eval` statements. These statements violate the `default-src 'self'` header. Instead you need to use `vue-i18n.runtime.esm-bundler.js`.
:::

:::warning NOTICE
From v9.3, the CSP issue can be worked around by JIT compilation of the vue-i18n message compiler. See [JIT compilation for details](#jit-compilation).
:::

## How to configure

We can configure these modules with module path using the module resolve alias feature (e.g. `resolve.alias` vite and webpack) of some bundler, but It takes time and effort.
Intlify project provides plugins/loaders for some bundlers, for simplicity

### unplugin-vue-i18n

[`unplugin`](https://github.com/unjs/unplugin) is an unified plugin system for bundle tool such as vite, webpack, rollup, esbuild and etc.

Intlify project is providing [`unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) for vite and webpack.

If you do the production build, Vue I18n will automatically bundle the runtime only module

#### Install plugin

::: code-group

```sh [npm]
npm install @intlify/unplugin-vue-i18n -D
```

```sh [yarn]
yarn add @intlify/unplugin-vue-i18n -D
```

```sh [pnpm]
pnpm add -D @intlify/unplugin-vue-i18n
```

:::

#### Configure plugin for vite

```js
// vite.config.ts
import { defineConfig } from 'vite'
import { resolve, dirname } from 'node:path'
import { fileURLToPath } from 'url'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

export default defineConfig({
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
    }),
  ],
})
```

#### Configure plugin for webpack

```js
// webpack.config.js
const path = require('path')
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack')

module.exports = {
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: path.resolve(__dirname, './path/to/src/locales/**'),
    })
  ]
}
```

#### More configuration

About options and features, see the detail [page](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n#intlifyunplugin-vue-i18n)

### Quasar CLI

No need to do anything. [Quasar CLI](https://quasar.dev) takes care of the optimizations for you.

## Feature build flags

### Reduce bundle size with tree-shaking

The `esm-bundler` builds now exposes global feature flags that can be overwritten at compile time:

* `__VUE_I18N_FULL_INSTALL__` (enable/disable, in addition to vue-i18n APIs, components and directives all fully support installation: `true`)
* `__VUE_I18N_LEGACY_API__` (enable/disable vue-i18n legacy style APIs support, default: `true`)

The build will work without configuring these flags, however it is **strongly recommended** to properly configure them in order to get proper tree shaking in the final bundle.

About how to configure for bundler, see the [here](#configure-feature-flags-for-bundler).

### JIT compilation

:::tip Support Version
:new: 9.3+
:::

Before v9.3, vue-i18n message compiler precompiled locale messages like AOT (Ahead Of Time).

However, it had the following issues:

* CSP issues: hard to work on service/web workers, edge-side runtimes of CDNs and etc.
* Back-end integration: hard to get messages from back-end such as database via API and localize them dynamically

To solve these issues, JIT (Just In Time) style compilation is supported message compiler.

Each time localization is performed in an application using `$t` or `t` functions, message resources will be compiled on message compiler.

You need to configure the following feature flag with `esm-bundler` build and bundler such as vite:

* `__INTLIFY_JIT_COMPILATION__`  (enable/disable message compiler for JIT style, default: `false`)
* `__INTLIFY_DROP_MESSAGE_COMPILER__`  (enable/disable whether to tree-shake message compiler when we will be bundling, this flag works when `__INTLIFY_JIT_COMPILATION__` is enabled. default: `false`)

:::warning NOTICE
This feature is opted out as default, because compatibility with previous version before v9.3.
:::

:::warning NOTICE
From v10, JIT compilation is enabled by default, so it is no longer necessary to set the `__INTLIFY_JIT_COMPILATION__` flag in the bundler.
:::

About how to configure for bundler, see the [here](#configure-feature-flags-for-bundler).

### Configure feature flags for bundler

* webpack: use [DefinePlugin](https://webpack.js.org/plugins/define-plugin/)
* Rollup: use [@rollup/plugin-replace](https://github.com/rollup/plugins/tree/master/packages/replace)
* Vite: configured by default, but can be overwritten using the [`define` option](https://github.com/vitejs/vite/blob/a4133c073e640b17276b2de6e91a6857bdf382e1/src/node/config.ts#L72-L76)
* Quasar CLI: configured by default, but can be overwritten using quasar.conf.js > build > rawDefine

:::tip NOTE
The replacement value **must be boolean literals** and cannot be strings, otherwise the bundler/minifier will not be able to properly evaluate the conditions.
:::

## Pre translations with extensions

You can use pre-translation(server-side rendering) with vue-i18n-extensions package.

About how to usage, see [here](https://github.com/intlify/vue-i18n-extensions).

## SSR (Server-Side Rendering)

### Configure plugin for SSR

For SSR applications, you need to configure the `ssr` option in [@intlify/unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n#ssr):

```js
// vite.config.ts
import { defineConfig } from 'vite'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

export default defineConfig({
  plugins: [
    VueI18nPlugin({
      ssr: true, // Enable SSR support
    }),
  ],
})
```

---

---
url: /guide/essentials/pluralization.md
---
# Pluralization

To localize the message, you might need to support the pluralization for some languages.

Vue i18n support pluralization, you can be able to use translation API that has pluralization feature.

## Basic Usage

You need to define the locale messages that have a pipe `|` separator and define plurals in pipe separator.

Locale messages the below:

```js
const messages = {
  en: {
    car: 'car | cars',
    apple: 'no apples | one apple | {count} apples'
  }
}
```

Here, we have an `en` locale object that has `car` and `apple`.

The `car` has `car | cars` pluralization message, while the `apple` has `no apples | one apple | {count} apples` pluralization message.

These plural messages are selected by the logic of the choice rule for each language in the translaton API according to the numeric value you specify at the translation API.

Vue I18n offers some ways to support pluralization. Here we’ll use the `$t`.

:::tip NOTE
`$t` has some overloads. About these overloads, see the [API Reference](../../api/injection#t-key)
:::

:::tip NOTE
Some ways to support pluralization are:

* injected global `$t`
* built-in Translation component (`i18n-t`)
* exported `t` from `useI18n` (for Composition API mode)
  :::

The following is an example of using the translation API.

```html
<p>{{ $t('car', 1) }}</p>
<p>{{ $t('car', 2) }}</p>

<p>{{ $t('apple', 0) }}</p>
<p>{{ $t('apple', 1) }}</p>
<p>{{ $t('apple', { count: 10 }) }}</p>
```

In the above example of using the `$t`, the first argument is the locale messages key and the second argument is a number. The `$t` returns the choice message as a result.

As result the below:

```html
<p>car</p>
<p>cars</p>

<p>no apples</p>
<p>one apple</p>
<p>10 apples</p>
```

## Predefined implicit arguments

You don’t need to explicitly give the number for pluralization.

Let’s look at an example to understand what that means!

Locale messages the below:

```js
const messages = {
  en: {
    apple: 'no apples | one apple | {count} apples',
    banana: 'no bananas | {n} banana | {n} bananas'
  }
}
```

Here, we have an `en` locale object that has `apple` and `banana`.

The `apple` has `no apples | one apple | {count} apples` pluralization message, and the `banana` has `no bananas | {n} banana | {n} bananas` pluralization message.

The number can be accessed within locale messages via predefined named arguments `{count}` and/or `{n}`. You can overwrite those predefined named arguments if necessary.

The following is an example of using `$t`:

```html
<p>{{ $t('apple', 10, { named: { count: 10 } }) }}</p>
<p>{{ $t('apple', 10) }}</p>

<p>{{ $t('banana', 1, { named: { n: 1 } }) }}</p>
<p>{{ $t('banana', 1) }}</p>
<p>{{ $t('banana', 100, { named: { n: 'too many' } }) }}</p>
```

In the above some examples, the first argument is the locale messages key and the second argument is the numeric value or object.

If an object is specified, it’s equivalent to Named interpolation. You can interpolate `n` or `count` with arguments implicit in the pluralization message by giving it.

As result the below:

```html
<p>10 apples</p>
<p>10 apples</p>

<p>1 banana</p>
<p>1 banana</p>
<p>too many bananas</p>
```

## Custom Pluralization

Such pluralization, however, does not apply to all languages (Slavic languages, for example, have different pluralization rules).

To implement these rules you can pass an optional `pluralizationRules` object into `VueI18n` constructor options.

Very simplified example using rules for Slavic languages (Russian, Ukrainian, etc.):

```js
function customRule(choice, choicesLength, orgRule) {
  if (choice === 0) {
    return 0
  }

  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 === 1
  if (!teen && endsWithOne) {
    return 1
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2
  }

  return choicesLength < 4 ? 2 : 3
}
```

To use the custom rules defined above, inside of `createI18n` set either:

1. `pluralizationRules` (for Options API)
   *or*
2. `pluralRules` (for Composition API)

like the the following locale:

```js
const i18n = createI18n({
  locale: 'ru',
  // use pluralRules for Composition api
  pluralizationRules: {
    ru: customRule
  },
  messages: {
    ru: {
      car: '0 машин | {n} машина | {n} машины | {n} машин',
      banana: 'нет бананов | {n} банан | {n} банана | {n} бананов'
    }
  }
})
```

With the following template:

```html
<h2>Car:</h2>
<p>{{ $t('car', 1) }}</p>
<p>{{ $t('car', 2) }}</p>
<p>{{ $t('car', 4) }}</p>
<p>{{ $t('car', 12) }}</p>
<p>{{ $t('car', 21) }}</p>

<h2>Banana:</h2>
<p>{{ $t('banana', 0) }}</p>
<p>{{ $t('banana', 4) }}</p>
<p>{{ $t('banana', 11) }}</p>
<p>{{ $t('banana', 31) }}</p>
```

As result the below:

```html
<h2>Car:</h2>
<p>1 машина</p>
<p>2 машины</p>
<p>4 машины</p>
<p>12 машин</p>
<p>21 машина</p>

<h2>Banana:</h2>
<p>нет бананов</p>
<p>4 банана</p>
<p>11 бананов</p>
<p>31 банан</p>
```

---

---
url: /guide/essentials/scope.md
---
# Scope and Locale Changing

## Scope

Vue I18n manages resources to offer i18n features, including locale switching, each language messages called locales messages, and named format for datetime and numbers. They are managed with the `VueI18n` instance.

The Vue application is built from some components on the tree structure. To localize each of components in Vue I18n using the i18n features, we need to understand the concept of scope.

Vue I18n has two scopes the below:

* global scope
* local scope

![scope](/scope.png)

### Global Scope

The global scope in Vue allows you to access and manage internationalization (i18n) resources across all components in your application. This is especially useful for centralizing i18n management.

When you create an i18n instance using createI18n, a global scope is automatically created. This global scope is tied to the VueI18n instance, which can be accessed through the global property of the i18n instance. Essentially, the global scope refers to the VueI18n instance that is accessible via the i18n instance’s global property.

If the i18n option is not specified in a component, the global scope is automatically enabled for that component. In this case, the VueI18n instance accessed through this.$i18n within the component is the same as the global instance available via the i18n instance’s global property.

### Local Scope

The local scope in Vue allows you to manage i18n resources on a per-component basis, similar to how `<style scoped>` works in single-file components. When a component has a local scope, only that component's i18n resources are active. This is particularly useful when you want to manage locale messages specific to each component.

Local scope is enabled by specifying the i18n option within the component. This creates a new VueI18n instance when the component is initialized. As a result, the VueI18n instance accessed through this.$i18n in that component is distinct from the global VueI18n instance available through the global property of the i18n instance.

## Locale Changing

So far, we’ve explained the concept of the scope, and once you understand the scope, it’s easy to understand how to change the locale.

### Global Scope

If you want to change the locale for the whole application, global scope allows you to use the `$i18n.locale` for each component.

Here’s an example:

```js
const i18n = createI18n({
  locale: 'ja', // set current locale
  messages: {
    en: {
      hello: 'hello!'
    },
    ja: {
      hello: 'こんにちは！'
    }
  },
  // vue-i18n something options here ...
  // ...
})

// create Vue app instance, install Vue I18n, and mount!
createApp({
  // something vue options here ...
  // ...
}).use(i18n).mount('#app')
```

Component:

```vue
<template>
  <div class="locale-changer">
    <select v-model="$i18n.locale">
      <option v-for="locale in $i18n.availableLocales" :key="`locale-${locale}`" :value="locale">{{ locale }}</option>
    </select>
  </div>
</template>
```

The above example uses the `availableLocales` property of `VueI18n` instance to list the available locales as options for the select element. Since `$i18n.locale` is bound with `v-model`, you can switch it by selecting the option of the select element, which sets its value to `$i18n.locale`.

As you can see, the global scope is very useful because it allows you to switch the messages displayed in the UI for all components of the application at once.

### Local Scope

`locale` of local scope is inherited from global Scope by default. Therefore, when you change the `locale` in global scope, the `locale` in local scope is also changed.

If you want to switch the locale for the whole application, you need to change it via `global` property of i18n instance created with `createI18n`.

:::tip NOTE
If you don’t want to inherit `locale` from global scope, you need to set `sync` of `i18n` component option to `false`.
:::

Example:

```js
const i18n = createI18n({
  locale: 'ja', // set current locale
  // vue-i18n something options here ...
  // ...
})

// create Vue app instance, install Vue I18n, and mount!
createApp({
  // something vue options here ...
  // ...
}).use(i18n).mount('#app')


// change locale via `global` property

// when vue-i18n is being used with legacy: false, note that i18n.global.locale is a ref, so we must set it via .value:
i18n.global.locale.value = 'en'

// otherwise - when using legacy: true, we set it like this:
i18n.global.locale = 'en'
```

:::warning NOTICE
Changing `locale` of local scope does not affect `locale` of global scope. This means that changing the locale in `$i18n.locale` in local scope component will not change the entire application’s locale, only that component. Use `$root.$i18n.locale` instead of `$i18n.locale`.
:::

---

---
url: /guide/advanced/sfc.md
---
# Single file components

## Basic Usage

If you are building Vue component or Vue application using single file components, you can manage the locale messages using i18n custom block.

The following in [single file components example](https://github.com/kazupon/vue-i18n/tree/dev/examples/sfc):

```vue
<script>
export default {
  name: 'App'
}
</script>

<template>
  <label for="locale">locale</label>
  <select v-model="$i18n.locale">
    <option>en</option>
    <option>ja</option>
  </select>
  <p>message: {{ $t('hello') }}</p>
</template>

<i18n>
{
  "en": {
    "hello": "hello world!"
  },
  "ja": {
    "hello": "こんにちは、世界！"
  }
}
</i18n>
```

In i18n custom blocks, the format of the locale messages resource is **json** format by default.

The locale messages defined by i18n custom blocks, are used as the  local scope in single file components.

If `$t('hello')` is used in the template, the `hello` key defined by `i18n` custom blocks is referred to.

:::tip NOTE
The Composition API requires `useI18n` to return the `setup` context in order to localize with reference to locale messages defined in the i18n custom blocks.

About how to usage of `useI18n` , see the [Composition API](./composition)
:::

To use i18n custom blocks, you need to use the following plugins for bundler.

## Bundling with Vite

### unplugin-vue-i18n

[`unplugin`](https://github.com/unjs/unplugin) is an unified plugin system for bundle tool such as vite, webpack, rollup, esbuild and etc.

[`unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) for vite and webpack.

:::tip REQUIREMENTS

* vite: **v3 or later**
* @vitejs/plugin-vue: **v3.2.0 or later**.
  :::

#### Installation

::: code-group

```sh [npm]
npm install @intlify/unplugin-vue-i18n -D
```

```sh [yarn]
yarn add @intlify/unplugin-vue-i18n -D
```

```sh [pnpm]
pnpm add -D @intlify/unplugin-vue-i18n
```

:::

#### Configure plugin for Vite

```js
// vite.config.ts
import { defineConfig } from 'vite'
import { resolve, dirname } from 'node:path'
import { fileURLToPath } from 'node:url'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

export default defineConfig({
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
    }),
  ],
})
```

#### Configure plugin for Webpack

```js
// webpack.config.js
const path = require('path')
const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack')

module.exports = {
  /* ... */
  plugins: [
    /* ... */
    VueI18nPlugin({
      /* options */
      // locale messages resource pre-compile option
      include: path.resolve(__dirname, './path/to/src/locales/**'),
    })
  ]
}
```

## Quasar CLI

If we want to add support to the `<i18n>` tag inside a single file component in a [Quasar CLI](https://quasar.dev) project then we need to modify the existing configuration.

In order to do that we need to edit `quasar.conf.js` at the root of our project:

```js
build: {
  chainWebpack: chain => {
    chain.module
      .rule('i18n-resource')
        .test(/\.(json5?|ya?ml)$/)
          .include.add(path.resolve(__dirname, './src/i18n'))
          .end()
        .type('javascript/auto')
        .use('i18n-resource')
          .loader('@intlify/vue-i18n-loader')
    chain.module
      .rule('i18n')
        .resourceQuery(/blockType=i18n/)
        .type('javascript/auto')
        .use('i18n')
          .loader('@intlify/vue-i18n-loader')
  }
}
```

We also need to make sure that we've installed `@intlify/vue-i18n-loader`:

::: code-group

```sh [npm]
npm install @intlify/vue-i18n-loader -D
```

```sh [yarn]
yarn add @intlify/vue-i18n-loader -D
```

```sh [pnpm]
pnpm add -D @intlify/vue-i18n-loader
```

:::

---

---
url: /guide/advanced/lite.md
---
# Small size subset of Vue I18n

`petite-vue-i18n` is an alternative distribution of Vue I18n, which provides only minimal features.

## What is the difference from Vue I18n ?

* The Size is smaller than vue-i18n
  * CDN or without a Bundler
    * Package reduce size: runtime + compiler `~32%`, runtime only `~45%`
    * `petite-vue-i18n`: runtime + compiler `~9.61KB`, runtime only `~5.51KB` (production build, brotli compression)
    * `vue-i18n`: runtime + compiler `~14.18KB`, runtime only `~10.12KB` (production build, brotli compression)
  * ES Modules for browser
    * Package reduce size: runtime + compiler `~32%`, runtime only `~45%`
    * `petite-vue-i18n`: runtime + compiler `~10.51KB`, runtime only `~6.20KB` (production build, brotli compression)
    * `vue-i18n`: runtime + compiler `~15.40KB`, runtime only `~11.12KB` (production build, brotli compression)
  * Application bundle size
    * Reduce size from `vue-i18n`: `~10%` (Code size check measurement of [vue-i18n](https://github.com/intlify/vue-i18n/tree/master/packages/size-check-vue-i18n) and [petite-vue-i18n](https://github.com/intlify/vue-i18n/tree/master/packages/size-check-petite-vue-i18n))
* The legacy API is not supported, **only the composition API**
* The APIs for the following DateTime Formats, Number Formats, and utilities aren’t included. **Translation only**
  * `n`, `$n`
  * `d`, `$d`
  * `rt`, `$rt`
  * `te`, `$te`
  * `tm`, `$tm`
  * `getDateTimeFormat`, `setDateTimeFormat`, `mergeDateTimeFormat`
  * `getNumberFormat`, `setNumberFormat`, `mergeNumberFormat`
* **The only locale messages that can be handled are simple key-values**. if you can handle hierarchical locale messages, you need to customize them using the API
* The algorithm of local fallback is **the array order** specified in `fallbackLocale`
* Custom directive `v-t` isn’t included
* The following components provided by `vue-i18n` aren’t included
  * Translation `i18n-t`
  * DatetimeFormat `i18n-d`
  * NumberFormat `i18n-n`

## The use case of `petite-vue-i18n`

`vue-i18n` includes various i18n features such as translation, datetimes format and number formats. Some projects may only use translation and not datetime formats.  At the moment, even in that case, the code for that feature is included.

If your project only uses `t` or `$t` API for translation, so we recommended you would use `petite-vue-i18n` better than `vue-i18n`. And your project needs the features of `vue-i18n`, you can smoothly migrate from `petite-vue-i18n` to `vue-i18n`. This means that it’s progressive enhancement.

## Installation

Basically, it’s the same as installing `vue-i18n`. The only difference is that the part of URL or part of path are changed from `vue-i18n` to `petite-vue-i18n`.

### CDN

You need to insert the following scripts to end of `<head>`:

```html
<script src="https://unpkg.com/vue@next"></script>
<script src="https://unpkg.com/petite-vue-i18n"></script>
```

The following is the application code with the script tag:

```html
<script>
const { createApp } = Vue
const { createI18n } = PetiteVueI18n

const i18n = createI18n({
  // something vue-i18n options here ...
})

const app = createApp({
  // something vue options here ...
})

app.use(i18n)
app.mount('#app')
</script>
```

### Package managers

::: code-group

```sh [npm]
npm install petite-vue-i18n@next --save
```

```sh [yarn]
yarn add petite-vue-i18n@next
```

```sh [pnpm]
pnpm add petite-vue-i18n@next
```

:::

```js
import { createApp } from 'vue'
import { createI18n } from 'petite-vue-i18n'

const i18n = createI18n({
  // something vue-i18n options here ...
})

const app = createApp({
  // something vue options here ...
})

app.use(i18n)
app.mount('#app')
```

## Usages

### Hello world

Template:

```html
<div id="app">
  <h1>{{ t('hello world') }}</h1>
</div>
```

Scripts:

```js
const { createApp } = Vue
const { createI18n, useI18n } = PetiteVueI18n
// or for ES modules
// import { createApp } from 'vue'
// import { createI18n } from 'petite-vue-i18n'

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      'hello world': 'Hello world!'
    },
    ja: {
      'hello world': 'こんにちは、世界！'
    }
  }
})

// define App component
const App = {
  setup() {
    const { t } = useI18n()
    return { t }
  }
}

const app = createApp(App)

app.use(i18n)
app.mount('#app')
```

### Message resolution in `petite-vue-i18n`

`petite-vue-i18n` uses a simple flat key-value resolver by default to keep the bundle size small. This means:

**Flat keys work:**

```js
const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      'hello': 'Hello!',
      'baseForm.test': 'Test Form'  // flat key with dot
    }
  }
})

t('hello')          // → "Hello!"
t('baseForm.test')  // → "Test Form"
```

**Nested (hierarchical) structures do NOT work by default:**

```js
const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      baseForm: {
        test: 'Test Form'  // nested structure
      }
    }
  }
})

t('baseForm.test')  // → "" (not resolved!)
```

:::warning
The `flatJson` option should NOT be used with `petite-vue-i18n`. `flatJson` transforms flat keys into nested structures at setup time, but since `petite-vue-i18n` cannot resolve nested structures by default, the transformed messages will not be found.
:::

If you need to use hierarchical locale messages with `petite-vue-i18n`, you need to register the message resolver from `@intlify/core-base` as described in the next section.

### Use the same message resolver and locale fallbacker as `vue-i18n`

In `petite-vue-i18n`, the message resolver and locale fallbacker use simple implementations to optimize code size:

* message resolver
  * Resolves key-value style locale messages only (flat `message[key]` lookup)
* locale fallbacker
  * Fallback according to the array order specified in `fallbackLocale`
  * If a simple string locale is specified, fallback to that locale

If you want to use hierarchical locale messages or the same locale fallback behavior as `vue-i18n`, you can change them using the API.

Note that at this time, only bundlers like vite and webpack are supported.

You need to install `@intlify/core-base` to your project with package manager.

::: code-group

```sh [npm]
npm install --save @intlify/core-base@next
```

```sh [yarn]
yarn add @intlify/core-base@next
```

```sh [pnpm]
pnpm add @intlify/core-base@next
```

:::

Then, at the entry point of the application, configure the message resolver and locale fallbacker using the API as the below:

```js
import { createApp } from 'vue'
import {
  createI18n,
  registerMessageResolver, // register the message resolver API
  registerLocaleFallbacker, // register the locale fallbacker API
} from 'petite-vue-i18n'
import {
  resolveValue, // message resolver of vue-i18n which is used by default
  fallbackWithLocaleChain // locale fallbacker of vue-i18n which is used by default
} from '@intlify/core-base'

// register message resolver of vue-i18n
registerMessageResolver(resolveValue)

// register locale fallbacker of vue-i18n
registerLocaleFallbacker(fallbackWithLocaleChain)

// some thing code ...
// ...
```

With the above settings, locale message resolving and locale fallbacking will be handled in the same way as in vue-i18n, note that the code size will increase slightly.

### Setting bundler plugin

If you are building your application with a build toolchain like vite, you must configure it.
Please set the [‘module’ option in `@intlify/unplugin-vue-i18n`](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n#module) configuration as follows.

> \[!NOTE]
> About `@intlify/unplugin-vue-i18n` setting, see the ['performance' section](./optimization.md) and [`@intlify/unplugin-vue-i18n` docs](https://github.com/intlify/bundle-tools/blob/main/packages/unplugin-vue-i18n/README.md)

> \[!IMPORTANT]
> `@intlify/unplugin-vue-i18n` version must **5.1.0 and later**

```diff
 // vite.config.ts
 import { defineConfig } from 'vite'
 import { resolve, dirname } from 'node:path'
 import { fileURLToPath } from 'url'
 import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'

 export default defineConfig({
   /* ... */
   plugins: [
     /* ... */
     VueI18nPlugin({
       /* options */
+      module: 'petite-vue-i18n',
       // locale messages resource pre-compile option
       include: resolve(dirname(fileURLToPath(import.meta.url)), './path/to/src/locales/**'),
     }),
   ],
 })
```

### Switch without changing import id

You can switch from vue-i18n to petite-vue-i18n in your application using npm alias without changing the import id.

package.json:

```diff
 {
   // ...
   "dependencies": {
     "vue": "^3.4.14",
-     "vue-i18n": "^10.0.0"
+     "vue-i18n": "npm:petite-vue-i18n@^10.0.0"
   },
 }
```

You need `@intlify/unplugin-vue-i18n` to build your application.

---

---
url: /ecosystem/integrations.md
---
# Third-party integrations

---

---
url: /ecosystem/tools.md
---
# Third-party tooling

## Loccy (VS Code extension)

Loccy is a VS Code extension designed to address common challenges in i18n workflows for Vue projects. It helps you easily find and update translations directly in your code.

Loccy also makes it easier to discover and reuse existing translations, helping you avoid duplication. AI-assisted suggestions support consistent terminology, provide initial wording, and enable quick syncing after edits in any language.

Finally, convenient previews show how translations appear in context.

## i18n Ally (VS Code extension)

[i18n Ally](https://marketplace.visualstudio.com/items?itemName=lokalise.i18n-ally) is i18n extension for VSCode.

The i18n Ally give awesome developer experience for your i18n development.

Read more about i18n Ally in [README](https://github.com/lokalise/i18n-ally).

## i18nPlugin (intellij platform)

[i18nPlugin](https://github.com/nyavro/i18nPlugin) Intellij idea i18next support plugin ( [JetBrains plugin page ](https://plugins.jetbrains.com/plugin/12981-i18n-support)).

Plugin for i18n typescript/javascript/PHP. Supports vue-i18n. To enable vue-i18n support go to settings -> Tools -> i18n Plugin configuration and check "Vue-i18n". You need set vue locales directory (locales by default).

## Easy I18n (intellij platform)

Translation helper for IntelliJ IDEA based IDE's. Requires dedicated language files. Features: `Tree-/Table-View` / `Search filter` / `Indication of missing translations` / `Quick CRUD operations`.

[JetBrains Marketplace](https://plugins.jetbrains.com/plugin/16316-easy-i18n) // [GitHub Repository](https://github.com/marhali/easy-i18n)

## Sherlock – i18n inspector (VS Code extension)

Sherlock is a VS Code extension that helps you to extract, edit & inspect your i18n keys in your codebase. It is available in the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=inlang.vs-code-extension).

Sherlock is part of the inlang ecosystem, which gives you multiple apps with awesome developer experience for your i18n development, like a [Figma plugin](https://inlang.com/m/gkrpgoir/app-parrot-figmaPlugin), a [web editor](https://inlang.com/m/tdozzpar/app-inlang-finkLocalizationEditor) or a [GitHub Action](https://inlang.com/m/3gk8n4n4/app-inlang-ninjaI18nAction).

## BabelEdit

[BabelEdit](https://www.codeandweb.com/babeledit) is translation editor for web apps.

BabelEdit can translate `json` files, and it can also translate `i18n` custom block of Single-file components.

Read more about BabelEdit in [tutorial page](https://www.codeandweb.com/babeledit/tutorials/how-to-translate-your-vue-app-with-vue-i18n).

## vue-i18n-extract

[vue-i18n-extract](https://github.com/pixari/vue-i18n-extract) performs static analysis on a Vue.js project based on vue-i18n and reports the following information:

* list of all the **unused vue-i18n keys** (entries found in the language files but not used in the project)
* list of all the **missing keys** (entries fond in the project but not in the language files)

It’s possible to show the output in the console or to write it in a json file.

The missing keys can be also automatically added to the given language files.

---

---
url: /guide/advanced/typescript.md
---
# TypeScript Support

:::tip Supported Versions
:new: 9.2+
:::

VueI18n use the resources, which locale messages, datetime formats and number formats.
Especially, locale messages can be externalized as i18n resources, such as `json` files, in order to collaborate with translators using the Localization service, and these resources can be imported for collaboration.

In order to achieve a smooth localization workflow in conjunction with the Localization Service, you may want to prevent missing localizations or missing resource definitions for externalized i18n resources.
And in development, you may not want to spoil the developer experience by preventing key string mistakes in using the translation function like `$t`.

## Type-safe resources with schema

You can support the type-safe resources with resource schema using TypeScript.

### Type-safe resources in `createI18n`

The following is an example code to define type-safe resources for `messages` defined with `createI18n` option.

Locale messages resource:

```json
{
  "world": "the world!"
}
```

Application entrypoint:

```ts
import { createI18n } from 'vue-i18n'
import enUS from './locales/en-US.json'

// Type-define 'en-US' as the master schema for the resource
type MessageSchema = typeof enUS

const i18n = createI18n<[MessageSchema], 'en-US' | 'ja-JP'>({
  locale: 'en-US',
  messages: {
    'en-US': enUS
  }
})
```

The above code defines a type from the `en-US` message resource specified in the `messages` option of `createI18n`. This defined type is the master-like schema for message resources handled with VueI18n. This means that you can define it **as a single source of truth** resource in your application. You can define a type-safe resource in other locales by specifying the type defined as a schema from a message resource as the first argument of the type parameter of `createI18n`.

The second argument of the type parameter of `createI18n` is the locale to handle. With this, type checking is performed for each locale specified in the second argument, based on the type of the resource specified in the first argument. In the above code example, `en-US` and `ja-JP` are specified as the main locale, which is also specified in the `locale` option. If you compile typescript in this state, you will get the following error to check that no `ja-JP` resource is defined in the `messages` option.

```sh
$ npx tsc
npx tsc
src/main.ts:11:3 - error TS2741: Property '"ja-JP"' is missing in type '{ 'en-US': { world: string; }; }' but required in type '{ "en-US": { world: string; }; "ja-JP": { world: string; }; }'.

11   messages: {
     ~~~~~~~~

  node_modules/vue-i18n/dist/vue-i18n.d.ts:712:5
    712     messages?: {
            ~~~~~~~~
    The expected type comes from property 'messages' which is declared here on type 'I18nOptions<{ message: { world: string; }; datetime: DateTimeFormat; number: NumberFormat; }, { messages: "en-US"; datetimeFormats: "en-US"; numberFormats: "en-US"; } | { ...; }, ComposerOptions<...> | VueI18nOptions<...>>'


Found 1 error.
```

If you are using [Visual Studio Code](https://code.visualstudio.com/) as an editor, you can notice that there is a resource definition omission in the editor with the following error before you run the typescript compilation.

![VSCode-Type-Error1](/ts-support-1.png)
![VSCode-Type-Error2](/ts-support-2.png)

### Type-safe resources in `useI18n`

Type-safe resources can be defined not only with `createI18n`, but also on a per-component basis with `useI18n` used with the Composition API.

In addition to local messages, the resource type definitions can also include datetime formats and number formats.

The following is an example of code that defines type-safe resources for locale messages and number formats on a per-component basis in `useI18n`.

locale messages to import in Vue components:

```json
{
  "messages": {
    "hello": "Hello, {name}!"
  }
}
```

Vue components with type-safe resources:

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import enUS from './en-US.json' // import locale messages for Vue component

// define message schema for Vue component
type MessageSchema = typeof enUS

// define number format schema for Vue component
type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}

/*
 * You can specify the your definition schema with object literal at first type parameters
 * About type parameter, see the http://vue-i18n.intlify.dev/api/composition.html#usei18n
 */
const { t, n } = useI18n<{
  message: MessageSchema,
  number: NumberSchema
}, 'en-US'>({
  inheritLocale: true,
  messages: {
    'en-US': enUS
  },
  numberFormats: {
    'en-US': {
      currency: {
        style: 'currency',
        currencyDisplay: 'symbol',
        currency: 'USD'
      }
    }
  }
})
</script>

<template>
  <p>message: {{ t('messages.hello', { name: 'kazupon' }) }}</p>
  <p>currency: {{ n(1000, 'currency') }}</p>
</template>
```

the above codes, by specifying the defined schema as the first type parameter of `useI18n`, you can use TypeScript to check for undefined resources for locale messages and number formats. Also, by specifying the locale to be defined in the second type parameter, TypeScript can check for undefined locales.

:::warning Limitation

* Type safety is not supported for i18n custom blocks in SFC. We'll plan to support it in the future.
* Currently support for `JSON` format only.
  :::

The code described so far is available as [example](https://github.com/intlify/vue-i18n/tree/master/examples/type-safe). Let's check it!

### Type-Safe supporting APIs

Other APIs support a type parameter that allows you to specify the schema of a resource for type-safe resource manipulation, such as:

* `getLocaleMessage`
* `setLocaleMessage`
* `mergeLocaleMessage`
* `getDateTimeFormat`
* `setDateTimeFormat`
* `mergeDateTimeFormat`
* `getNumberFormat`
* `setNumberFormat`
* `mergeNumberFormat`

For more details, check out these following API documentation pages.

* [Legacy API](https://vue-i18n.intlify.dev/api/legacy)
* [Composition API](https://vue-i18n.intlify.dev/api/composition)

## Resource Keys completion supporting

:::warning NOTICE
Resource Keys completion can be used if you are using [Visual Studio Code](https://code.visualstudio.com/)
:::

Along with the support for type-safe resource definitions, VueI18n now provides APIs such as `t` and `d` for interpolating resource keys in the Composition API.

The following indicate how to interpolate Resource keys in Visual Studio Code for the local scope Vue component described above.

![VSCode-Resource-Completion](/ts-support-3.gif)

Support for interpolation of Resource Keys can prevent translation missing.

Use-cases on your project, you may have Vue components that do not use local scope, but use global scope for everything.

For that use case, you can also support interpolation of resource keys by explicitly specifying the schema defined for the global scope in the type parameter of `useI18n`.

define schema for global scope:

```ts
/**
 * define the resource schema
 */

import enUS from './en-US.json'

// define message schema as master message schema
export type MessageSchema = typeof enUS

// define number format schema
export type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}
```

Then, just import the defined schema and use it as a type parameter of `useI18n`, as in the following Vue component:

```vue
<script lang="ts">
import { useI18n } from 'vue-i18n'

// import resource schema for global scope
import type { MessageSchema, NumberSchema } from '../locales/schema'

const { t, n } = useI18n<{ message: MessageSchema, number: NumberSchema }>({
  useScope: 'global'
})
</script>

<template>
  <p>message: {{ t('hello') }}</p>
  <p>currency: {{ n(1000, 'currency') }}</p>
</template>

```

As a result, you can use the interpolation of resource keys in the APIs provided by VueI18n, such as `t` and `n`.

:::warning NOTICE
Legacy Mode, and interpolation of Resource Keys of APIs such as `$t` and `$d`, which are injected into Component by `globalInjection: true` of Composition API, require explicitly specifying type parameters.

For more details, see the API documentation.
https://vue-i18n.intlify.dev/api/injection.html
:::

## Global resource schema type definition

In VueI18n, you can define resource types at the global scope level by using TypeScript feature to extend interfaces.

If your project uses all resources as global scope, it is very convenient to handle type-safe resources easily.

VueI18n provides the following interfaces:

* `DefineLocaleMessage`: Interface to globally define the schema for Locale messages
* `DefineDateTimeFormat`: Interface to globally define the schema for Datetime formats
* `DefineNumberFormat`: Interface to globally define the schema for Number formats

With using these interfaces and the `declare module`, you can define a global schema for VueI18n.

The following is an example of a global schema defined in `d.ts`:

```ts
/**
 * you need to import the some interfaces
 */
import {
  DefineLocaleMessage,
  DefineDateTimeFormat,
  DefineNumberFormat
} from 'vue-i18n'

declare module 'vue-i18n' {
  // define the locale messages schema
  export interface DefineLocaleMessage {
    hello: string
    menu: {
      login: string
    }
    errors: string[]
  }

  // define the datetime format schema
  export interface DefineDateTimeFormat {
    short: {
      hour: 'numeric'
      minute: 'numeric'
      second: 'numeric'
      timeZoneName: 'short'
      timezone: string
    }
  }

  // define the number format schema
  export interface DefineNumberFormat {
    currency: {
      style: 'currency'
      currencyDisplay: 'symbol'
      currency: string
    }
  }
}
```

With using the `declare module` and the interface provided by VueI18n, you can define the schema for global resources.

Previously, when using `createI18n` and `useI18n` with type definitions for global scope resources, it was necessary to specify each as a type parameter.
This way, you don't need to do that.

The following is an example with `createI18n`:

```ts
import { createI18n, type I18nOptions } from 'vue-i18n'

/**
 * import locale messages resource from json for global scope
 */
import enUS from './locales/en-US.json'
import jaJP from './locales/ja-JP.json'

const options: I18nOptions = {
  legacy: false,
  locale: 'ja-JP',
  fallbackLocale: 'en-US',
  messages: {
    'en-US': enUS,
    'ja-JP': jaJP
  },
  datetimeFormats: {
    'ja-JP': {
      short: {
        hour: 'numeric',
        minute: 'numeric',
        second: 'numeric',
        timeZoneName: 'short',
        timezone: 'Asia/Tokyo'
      }
    }
  },
  numberFormats: {
    'ja-JP': {
      currency: {
        style: 'currency',
        currencyDisplay: 'symbol',
        currency: 'JPY'
      }
    }
  }
}

/**
 * setup vue-i18n with i18n resources with global type definition.
 * if you define the i18n resource schema in your `*.d.ts`, these is checked with typeScript.
 */
const i18n = createI18n<false, typeof options>(options)
```

The first type parameter of `createI18n` above does not specify the type that is the schema of the resource. The above just specifies a type hint for the `global` property of the i18n instance created by `createI18n`.
(If `false`, the type is a `Composer` instance for the Composition API, if `true`, the type is a `VueI18n` instance for the legacy API)

The second type parameter of `createI18n` specifies a type hint for options.

In the case of the `useI18n` case used by Vue components, it looks like this:

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'

// use global scope
const { t, d, n } = useI18n({
  inheritLocale: true
})
</script>

<template>
  <p>`t` resource key completion: {{ t('menu.login') }}</p>
  <p>`d` resource key completion: {{ d(new Date(), 'short') }}</p>
  <p>`n` resource key completion: {{ n(1000, 'currency') }}</p>
</template>
```

As you can see from the above code, you don't need to specify anything for the type parameter of `useI18n`. You can interpolate API Resource Keys such as `t`, `d`, and `n` without specifying them.

---

---
url: /index.md
---


---

---
url: /guide/advanced/wc.md
---
# Web components

:::tip Supported Versions
:new: 9.2+
:::

:::tip
The fully example codes of this chapter is [here](https://github.com/intlify/vue-i18n/tree/master/examples/web-components)
:::

Vue 3.2 later, we can use the WebComponents as described in the [official documentation](https://v3.vuejs.org/guide/web-components.html).

This will support the use of Vue I18n in Web Components starting with Vue I18n v9.2.

There are a few things to keep in mind when using Vue I18n with Web Components.

## Make preparation for Web Components to host the I18n instance

Using `defineCustomElement`, which is supported since Vue 3.2, we can provide Vue components implemented in SFC as Web Components. This means that Vue components implemented using `useI18n` can be served as Web Components with i18n support.

However, the provided Web Components cannot be inserted directly into HTML. You need to prepare the following Web Components to host the i18n instance created by `createI18n`.

Web Components that host the i18n instance:

```vue
<script setup lang="ts">
import { provide } from 'vue'
import { createI18n, I18nInjectionKey } from 'vue-i18n'

/**
 * create an i18n instance to host for other web components
 */
const i18n = createI18n<false>({
  legacy: false, // must set to `false`
  locale: 'en',
  messages: {
    en: {
      hello: 'Hello!'
    },
    ja: {
      hello: 'こんにちは！'
    }
  }
})

/**
 * provide i18n instance with `I18nInjectionKey` for other web components
 */
provide(I18nInjectionKey, i18n)
</script>

<!-- template to slot the content -->
<template>
  <slot />
</template>
```

The above code has the following three points.

* Call `createI18n` to create an i18n instance
* In `setup`, specify the i18n instance created with `createI18n` along with `I18nInjectionKey` in `provide`
* template has `slot` element only

In the `script` block, we first use `createI18n` to create an i18n instance. In a Vue application, the i18n instance created by `createI18n` can be used as a Vue plugin by specifying the i18n instance in the Vue application `app.use` created by `createApp`. 18n instance to the Vue application `app.use` generated by `createApp`, we needed to install Vue I18n as a Vue plugin to the Vue application.

If you use `defineCustomElement`, the Vue component can no longer be controlled from the Vue application side, so even if you run the Web Components version of the component in your Vue application, you can't attach the i18n instance created with `createI18n` to the target Web Components via `app.use` from the Vue application side.

So, in order to attach i18n instances to Web Components, we use `provide` in `setup` to expose i18n instances to other Web Components. This allows Web Components that implement i18n with `useI18n` to work by being hosted by Web Components that work `provide`.

Then, to host other Web Components, the `template` block makes it possible by using the `slot` element.

Export this hosted Web Components as follows:

```js
import { defineCustomElement } from 'vue'
import I18nHost from './components/I18nHost.ce.vue'

const I18nHostElement = defineCustomElement(I18nHost)

export { I18nHostElement }
```

The following `useI18n` implements and exports Web Components to:

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
</script>

<template>
  <p>{{ t('hello') }}</p>
</template>
```

```js
import { defineCustomElement } from 'vue'
import HelloI18n from './components/HelloI18n.ce.vue'

const HelloI18nElement = defineCustomElement(HelloI18n)
export { HelloI18nElement }
```

When the following Vue application is registered as a custom element of Web Components:

```js
import { createApp } from 'vue'
import { I18nHostElement } from './path/to/I18nHostElement'
import { HelloI18nElement } from './path/to/HelloI18nElement'
import App from './App.vue'

customElements.define('i18n-host', I18nHostElement)
customElements.define('hello-i18n', HelloI18nElement)

createApp(App).mount('#app')
```

So, In `App.vue`, which is the entry point of a Vue application, the following template will work:

```vue
<template>
  <i18n-host>
    <h1>Vue I18n in Web component</h1>
    <hello-i18n />
  </i18n-host>
</template>
```

The complete example described so far can be looked [here](https://github.com/intlify/vue-i18n/tree/master/examples/web-components).

## Limitations

1. The Vue I18n that can be used to implement Web Components is only **Composition API**.
2. When implementing Web Components, **Vue components implemented with `useI18n` cannot be imported and used together**. This is due to the [Provide / Inject](https://v3.vuejs.org/guide/web-components.html#definecustomelement) limitations of Vue.js for Web Components.

---

---
url: /guide/introduction.md
---
# What is Vue I18n?

:::tip NOTE
If you would like to know more about the maintenance status of each version of Vue I18n, please see [here](./maintenance).
:::

Vue I18n is internationalization plugin of Vue.js. And that is one of [Intlify projects](https://intlify.dev/). It easily integrates some localization features to your Vue.js Application.

Go to [Installation](./installation)

## Meet the team