Vue CLI i18n Plugin

2.3.2 · maintenance · verified Tue Apr 21

The `vue-cli-plugin-i18n` package is a Vue CLI plugin designed to integrate `vue-i18n` into new or existing Vue projects, streamlining the setup of internationalization. As of version 2.3.2, its latest release in late 2021, the plugin provides scaffolding for `vue-i18n`'s basic configuration, support for locale messages within Single File Components via `vue-i18n-loader`, and experimental reporting features for missing or unused locale keys. It supports both Vue 2 and Vue 3 projects, offering distinct options like `enableInSFC` for Vue 2 (related to `vue-i18n` v8.x) and `enableLegacy` or `runtimeOnly` for Vue 3 (related to `vue-i18n` v9+). Additionally, it includes a `enableBridge` option for Vue 2 projects to facilitate migration to `vue-i18n@v9.x`. The plugin is maintained by the Intlify organization, known for the `vue-i18n` library itself, ensuring close compatibility and up-to-date best practices.

Common errors

```
Error: Failed to resolve entry for package "vue-i18n". The package may have an incorrect main/module field.
```
cause Incorrect Vue I18n build chosen for the project context, often related to runtime-only vs. full build.

fix Ensure `runtimeOnly: false` (or omit) if you need the full build, or `runtimeOnly: true` if you intend to use the runtime-only version, configured in `vue.config.js` under `pluginOptions.i18n`.
```
[vue-i18n] Not found i18n instance. Please make sure that you install the plugin in the Vue app with `app.use(i18n)`.
```
cause The `i18n` instance was not correctly provided to the Vue application.

fix Verify that `app.use(i18n)` is called in your `main.js` (or `main.ts`) file after creating the Vue app, and that `i18n` is correctly imported from the generated `src/i18n.js`.
```
[vue-i18n] Fallback locale `en` is not registered. Please register it before use.
```
cause The fallback locale specified in `vue.config.js` or `.env` is not present in your locale message files.

fix Ensure that a locale messages file (e.g., `en.json`) exists in your `localeDir` and contains valid internationalization messages for the `fallbackLocale`.

Warnings

breaking When migrating a Vue 2 project to Vue 3, `vue-cli-plugin-i18n` v2.x requires configuring `enableLegacy: true` in `vue.config.js` to use the legacy Vue I18n API or refactoring to the Composition API and `createI18n`.
Fix: Set `enableLegacy: true` in `vue.config.js` under `pluginOptions.i18n` for legacy API or refactor i18n usage to `createI18n` and `useI18n` with Vue I18n v9+.
gotcha Using the `enableBridge` option in Vue 2 to prepare for Vue I18n v9.x migration requires manual installation of `@vue/composition-api` if you intend to use the Composition API.
Fix: Run `npm install @vue/composition-api` or `yarn add @vue/composition-api` in your project if you enable `enableBridge` and use the Composition API.
gotcha The `enableInSFC` option, which allows locale messages in Single File Components, is only supported for Vue 2 projects using Vue I18n v8.x.
Fix: Ensure your project is Vue 2 and using vue-i18n v8.x when setting `enableInSFC: true` in `vue.config.js`.
gotcha The `vue-cli-service i18n:report` command has limitations and cannot detect missing or unused keys from locale messages defined within i18n custom blocks in Single File Components.
Fix: Be aware of this limitation; manual review may be necessary for locale messages within custom blocks.
deprecated The `vue-cli-plugin-i18n` is tied to Vue CLI, which is moving towards maintenance mode as newer build tools like Vite gain prominence. While still functional, new Vue projects may favor alternative i18n integration methods.
Fix: For new Vue 3 projects, consider directly integrating `vue-i18n` using Vite or similar build tools without the CLI plugin, or explore `@intlify/vue-i18n-unplugin` for Vite/Webpack integration.

Install

npm install vue-cli-plugin-i18n npm
yarn add vue-cli-plugin-i18n yarn
pnpm add vue-cli-plugin-i18n pnpm

Imports

createI18n
wrong:
```
import VueI18n from 'vue-i18n'
```
correct:
```
import { createI18n } from 'vue-i18n'
```
For Vue 3 projects, `createI18n` is the standard way to initialize vue-i18n. The plugin scaffolds this setup.
i18n instance
wrong:
```
import { i18n } from './i18n'
```
correct:
```
import i18n from './i18n'
```
The plugin scaffolds an `i18n.js` or `i18n.ts` file which typically exports the initialized `i18n` instance as a default export.
useI18n
wrong:
```
this.$i18n
```
correct:
```
import { useI18n } from 'vue-i18n'
```
For Vue 3 and Composition API, `useI18n` provides access to i18n functions. The `this.$i18n` approach is for Options API or Vue 2.

Quickstart

This demonstrates how to create a new Vue project, add the i18n plugin, and integrate the scaffolded internationalization setup into the main application entry point.

vue create my-vue-app
cd my-vue-app
vue add i18n

// After installation, a src/i18n.js (or .ts) file will be generated.
// You can then use it in your main.js (or main.ts):
// src/main.js
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n' // Auto-generated by the plugin

createApp(App).use(i18n).mount('#app')

// To report missing/unused keys (experimental):
// vue-cli-service i18n:report

view raw JSON →