@intlify/unplugin-vue-i18n

unplugin for Vue I18n

🌟 Features

• i18n resource pre-compilation
• i18n custom block
  • i18n resource definition
  • i18n resource importing
  • Locale of i18n resource definition
  • Locale of i18n resource definition for global scope
  • i18n resource formatting

💿 Installation

1npm i @intlify/unplugin-vue-i18n

1// vite.config.ts
2import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'
3
4export default defineConfig({
5  plugins: [
6    VueI18nPlugin({ /* options */ }),
7  ],
8})

1const VueI18nPlugin = require('@intlify/unplugin-vue-i18n/webpack')
2
3// webpack.config.js
4module.exports = {
5  /* ... */
6  plugins: [
7    VueI18nPlugin({ /* options */ })
8  ]
9}

1// nuxt.config.ts
2import { defineNuxtConfig } from 'nuxt'
3import VueI18nPlugin from '@intlify/unplugin-vue-i18n'
4
5export default defineNuxtConfig({
6  vite: {
7    plugins: [
8      VueI18nPlugin.vite({ /* options */ }),
9    ],
10  },
11  // When using Webpack
12  // builder: '@nuxt/webpack-builder',
13  webpack: {
14    plugins: [
15      VueI18nPlugin.webpack({ /* options */ }),
16    ]
17  }
18})

🚀 Usage

i18n resources pre-compilation

Since vue-i18n@v9.x, the locale messages are handled with message compiler, which converts them to javascript functions after compiling. After compiling, message compiler converts them into javascript functions, which can improve the performance of the application.

However, with the message compiler, the javascript function conversion will not work in some environments (e.g. CSP). For this reason, vue-i18n@v9.x and later offer a full version that includes compiler and runtime, and a runtime only version.

If you are using the runtime version, you will need to compile before importing locale messages by managing them in a file such as .json.

i18n custom block

The below example that examples/vite/src/App.vue have i18n custom block:

1<template>
2  <form>
3    <label>{{ t('language') }}</label>
4    <select v-model="locale">
5      <option value="en">en</option>
6      <option value="ja">ja</option>
7    </select>
8  </form>
9  <p>{{ t('hello') }}</p>
10  <Banana />
11</template>
12
13<script>
14import { useI18n } from 'vue-i18n'
15import Banana from './Banana.vue'
16
17export default {
18  name: 'App',
19  components: {
20    Banana
21  },
22  setup() {
23    const { t, locale } = useI18n({
24      inheritLocale: true,
25      useScope: 'local'
26    })
27    return { t, locale }
28  }
29}
30</script>
31
32<i18n>
33{
34  "en": {
35    "language": "Language",
36    "hello": "hello, world!"
37  },
38  "ja": {
39    "language": "言語",
40    "hello": "こんにちは、世界！"
41  }
42}
43</i18n>

Locale Messages formatting

You can be used by specifying the following format in the lang attribute:

• json (default)
• yaml
• yml
• json5

example yaml format:

1<i18n lang="yaml">
2en:
3  hello: 'Hello World!'
4ja:
5  hello: 'こんにちは、世界！'
6</i18n>

Static bundle importing

unplugin-vue-i18n allows you to statically bundle i18n resources such as json or yaml specified by the include option of the plugin described below as locale messages with the import syntax.

In this case, only one i18n resource can be statically bundled at a time with import syntax, so the these code will be redundant for multiple locales.

1import { createApp } from 'vue'
2import { createI18n } from 'vue-i18n'
3/*
4 * The i18n resources in the path specified in the plugin `include` option can be read
5 * as vue-i18n optimized locale messages using the import syntax
6 */
7import en from './src/locales/en.json'
8import ja from './src/locales/ja.yaml'
9import fr from './src/locales/fr.json5'
10
11const i18n = createI18n({
12  locale: 'en',
13  messages: {
14    en,
15    ja,
16    fr
17  }
18})
19
20const app = createApp()
21app.use(i18n).mount('#app')

unplugin-vue-i18n can use the bundler virtual mechanism to import all locales at once, using the special identifier @intlify/unplugin-vue-i18n/messages, as the bellow:

1import { createApp } from 'vue'
2import { createI18n } from 'vue-i18n'
3/*
4 * All i18n resources specified in the plugin `include` option can be loaded
5 * at once using the import syntax
6 */
7import messages from '@intlify/unplugin-vue-i18n/messages'
8
9const i18n = createI18n({
10  locale: 'en',
11  messages
12})
13
14const app = createApp()
15app.use(i18n).mount('#app')

Types

If you want type definition of @intlify/unplugin-vue-i18n/messages, add unplugin-vue-i18n/messages to compilerOptions.types of your tsconfig:

1{
2  "compilerOptions": {
3    "types": ["@intlify/unplugin-vue-i18n/messages"]
4  }
5}

📦 Automatic bundling

For Vue I18n

As noted here, NPM provides many different builds of Vue I18n.

This plugin will automatically select and bundle Vue I18n build according to the following behavior:

• development: vue-i18n.esm-bundler.js
• production: vue-i18n.runtime.esm-bundler.js

About details, See the here

For petite-vue-i18n

This plugin will automatically select and bundle petite-vue-i18n build according to the following vite behavior:

• vite dev: petite-vue-i18n.esm-bundler.js
• vite build: petite-vue-i18n.runtime.esm-bundler.js

🔧 Options

include

• Type: string | string[] | undefined

• Default: undefined

  A minimatch pattern, or array of patterns, you can specify a path to pre-compile i18n resources files. The extensions of i18n resources to be precompiled are as follows:

  - json
  - json5
  - yaml
  - yml
  

  Note json resources matches this option, it will be handled before the internal json plugin of bundler, and will not be processed afterwards, else the option doesn't match, the bundler side will handle.

runtimeOnly

• Type: boolean

• Default: true

  Whether or not to automatically use Vue I18n runtime-only in production build, set vue-i18n.runtime.esm-bundler.js in the vue-i18n field of bundler config, the below:

  - vite config: `resolve.alias`
  - webpack config: `resolve.alias`
  

  If false is specified, Vue I18n (vue-i18n) package.json module field will be used.

  For more details, See here

compositionOnly

• Type: boolean

• Default: true

  Whether to make vue-i18n API only composition API. By default the legacy API is tree-shaken.

  For more details, See here

fullInstall

• Type: boolean

• Default: true

  Whether to install the full set of APIs, components, etc. provided by Vue I18n. By default, all of them will be installed.

  If false is specified, buld-in components and directive will not be installed in vue and will be tree-shaken.

  For more details, See here

forceStringify

• Type: boolean

• Default: false

  Whether pre-compile number and boolean values as message functions that return the string value.

  For example, the following json resources:

  1{
  2  "trueValue": true,
  3  "falseValue": false,
  4  "nullValue": null,
  5  "numberValue": 1
  6}

  after pre-compiled (development):

  1export default {
  2  "trueValue": (()=>{const fn=(ctx) => {const { normalize: _normalize } = ctx;return _normalize(["true"])};fn.source="true";return fn;})(),
  3  "falseValue": (()=>{const fn=(ctx) => {const { normalize: _normalize } = ctx;return _normalize(["false"])};fn.source="false";return fn;})(),
  4  "nullValue": (()=>{const fn=(ctx) => {const { normalize: _normalize } = ctx;return _normalize(["null"])};fn.source="null";return fn;})(),
  5  "numberValue": (()=>{const fn=(ctx) => {const { normalize: _normalize } = ctx;return _normalize(["1"])};fn.source="1";return fn;})()
  6}

defaultSFCLang

• Type: string

• Default: 'json'

  Specify the content for all your inlined i18n custom blocks on your SFC.

  defaultSFCLang must have one of the following values:

  - json
  - json5
  - yaml
  - yml
  

  On inlined i18n custom blocks that have specified the lang attribute, the defaultSFCLang is not applied.

  For example, with defaultSFCLang: "yaml" or defaultSFCLang: "yml", this custom block:

  1<i18n lang="yaml">
  2en:
  3  hello: Hello
  4es:
  5  hello: Hola
  6</i18n>

  and this another one, are equivalent:

  1<i18n>
  2en:
  3  hello: Hello
  4es:
  5  hello: Hola
  6</i18n>

globalSFCScope

• Type: boolean

• Default: undefined

  Whether to include all i18n custom blocks on your SFC on global scope.

  If true, it will be applied to all inlined i18n or imported custom blocks.

  Warning: beware enabling globalSFCScope: true, all i18n custom blocks in all your SFC will be on global scope.

  For example, with globalSFCScope: true, this custom block:

  1<i18n lang="yaml" global>
  2en:
  3  hello: Hello
  4es:
  5  hello: Hola
  6</i18n>

  and this another one, are equivalent:

  1<i18n lang="yaml">
  2en:
  3  hello: Hello
  4es:
  5  hello: Hola
  6</i18n>

  You can also use defaultSFCLang: "yaml", following with previous example, this another is also equivalent to previous ones:

  1<i18n>
  2en:
  3  hello: Hello
  4es:
  5  hello: Hola
  6</i18n>

bridge

• Type: boolean

• Default: false

  The mode to birdge the i18n custom block to work in both vue-i18n@v8.x and vue-i18n@v9.x environments.

  To support in a smooth transition from vue-i18n@v8.x to vue-i18n@v9.x, we provide a mode that bundles the i18n custom block to be available in either version.

  ⚠️ Note that if you set bridge: true, the bundle size will increase. It is recommended to disable this mode after the migration from vue-i18n@v8.26 to vue-i18n@v9.x is completed.

esm

• Type: boolean

• Default: true

  For bridge option is true, whether to bundle locale resources with ESM. By default ESM, if you need to bundl with commonjs for especialy webpack, you need to set false

useClassComponent

• Type: boolean

• Default: false

  This option that to use i18n custom blocks in vue-class-component.

useVueI18nImportName (Experimental)

• Type: boolean

• Default: false

  Whether to use the import name of petite-vue-i18n with the same import name as vue-i18n (import { xxx } from 'vue-i18n').

  This option allows a smooth migration from petite-vue-i18n to vue-i18n and allows progressive enhacement.

📜 Changelog

Details changes for each release are documented in the CHANGELOG.md

©️ License

MIT