Registry / web-framework / vue-i18n

vue-i18n

JSON →
library11.3.2jsnpmunverified

Vue I18n is the official and widely adopted internationalization plugin for Vue.js, providing comprehensive features to localize Vue 3 applications. The current stable version is 11.3.2, with the project maintaining an active and frequent release cadence focused on bug fixes and incremental feature enhancements, as evidenced by its recent rapid succession of patch releases. Key differentiators include its deep and seamless integration with Vue's reactivity system, support for both the Options API and Composition API, sophisticated pluralization rules, robust date and number formatting capabilities, and a flexible message syntax that handles interpolation, linked messages, and even HTML content. It provides various optimized build artifacts (e.g., global, esm-browser, esm-bundler, cjs, node.mjs) to cater to diverse deployment environments, from direct CDN usage in browsers to modern bundler-driven setups and server-side rendering with Node.js. It's built on the Intlify project, ensuring a consistent and performant i18n experience for the Vue ecosystem.

npm install vue-i18n
INSTALL
IMPORT
SIG · VUE-I18N
V
vue-i18n
web-frameworkjavascriptv11.3.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createI18n
import { createI18n } from 'vue-i18n'
const { createI18n } = require('vue-i18n')
For bundler setups and modern Node.js environments, prefer ES Modules (import) over CommonJS (require). The CJS build is deprecated in Node.js since v9.3+.
useI18n
import { useI18n } from 'vue-i18n'
This Composition API hook must be called within a Vue component's `setup` function or a setup-like context, and the i18n instance must be provided to the app.
I18nOptions
import type { I18nOptions } from 'vue-i18n'
When importing types in TypeScript, using the `type` keyword explicitly improves clarity and can assist with tree-shaking.
vI18n
import { vI18n } from 'vue-i18n'
import { i18nDirective } from 'vue-i18n'
The directive is exported as `vI18n` and registered with `app.directive('i18n', vI18n)`.

This quickstart demonstrates the setup of Vue I18n with Vue 3's Composition API, including creating an i18n instance, defining messages, using the `t` function for translations, and dynamically changing the locale.

import { createApp, ref } from 'vue' import { createI18n, useI18n } from 'vue-i18n' // Root Vue app component (e.g., App.vue) const App = { template: ` <div> <h1>{{ t('greeting', { name: 'World' }) }}</h1> <p>{{ t('welcome') }}</p> <p>{{ t('pluralExample', { count: messageCount }) }}</p> <p>{{ t('dynamicMessage', { type: 'dynamic' }) }}</p> <button @click="changeLocale('en')">English</button> <button @click="changeLocale('fr')">Français</button> </div> `, setup() { // Use the Composition API hook const { t, locale } = useI18n({ useScope: 'global' }) // 'global' scope is necessary for root app messages const messageCount = ref(1) const changeLocale = (lang: string) => { locale.value = lang // Reactively change the current locale messageCount.value = lang === 'en' ? 5 : 1 // Example for pluralization demo } return { t, messageCount, changeLocale } } } // Locale messages definitions const messages = { en: { greeting: 'Hello, {name}!', welcome: 'Welcome to our site.', pluralExample: 'You have {count} message | You have {count} messages.', dynamicMessage: 'This is a {type} message.' }, fr: { greeting: 'Bonjour, {name} !', welcome: 'Bienvenue sur notre site.', pluralExample: 'Vous avez {count} message | Vous avez {count} messages.', dynamicMessage: 'Ceci est un message {type}.' } } // Create the i18n instance const i18n = createI18n({ legacy: false, // Essential for using Composition API with Vue I18n v9+ locale: 'en', // Default locale fallbackLocale: 'en', // Fallback locale if a message is not found messages // Provide all locale messages }) // Create the Vue app instance const app = createApp(App) // Install the i18n plugin app.use(i18n) // Mount the app to a DOM element app.mount('#app')
Debug
Known issues
breakingVue I18n v9+ is designed exclusively for Vue 3. Projects migrating from Vue 2, which typically used vue-i18n v8 or earlier, will encounter significant breaking changes requiring a full re-configuration of the internationalization setup due to API changes and the shift to Vue 3's plugin system.
fix
Migrate your application to Vue 3, then follow the official Vue I18n v9+ migration guide to adapt your i18n configuration and usage to the new API. This often includes setting `legacy: false` in `createI18n` for Composition API usage.
affects: <9.0.0
gotchaUsing the runtime-only build (e.g., `vue-i18n.runtime.esm-bundler.js`) requires all locale messages to be pre-compiled. Attempting to provide string templates for messages at runtime with this build will lead to errors, as it lacks the message compiler.
fix
If you need to compile messages in the browser at runtime (e.g., from inline JavaScript strings), use the full build (e.g., `vue-i18n.esm-bundler.js`). Otherwise, ensure all locale messages are pre-compiled during your build process (e.g., by using JSON files for messages).
affects: >=9.0.0
deprecatedThe CommonJS (CJS) builds for Node.js (e.g., `vue-i18n.cjs.js`) are considered deprecated as of v9.3+ in favor of ES Modules (ESM) builds (e.g., `vue-i18n.node.mjs`). While still functional, future versions may remove or limit support for CJS, making ESM the recommended approach for Node.js environments.
fix
Refactor your Node.js server-side rendering or build scripts to use ES Module `import` statements and the `vue-i18n.node.mjs` entry point instead of CommonJS `require`.
affects: >=9.3.0
gotchaThe `esm-bundler` builds expose global feature flags like `__VUE_I18N_FULL_INSTALL__` that are intended to be replaced by bundlers. If these flags are not correctly configured during the build process (e.g., via a `DefinePlugin` in webpack), it can lead to unexpected behavior, including tree-shaking issues or incorrect feature activation.
fix
Ensure your bundler is configured to replace these feature flags with appropriate boolean values (e.g., `true` or `false`). Consult the Vue I18n documentation or your bundler's configuration guide for details on how to set these global defines.
affects: >=9.0.0
Errors
Common errors & fixes
[vue-i18n] Not found locale messages in "en"
The i18n instance was initialized, but the messages for the specified locale (e.g., 'en') or a configured fallback locale are either missing or were not correctly provided to `createI18n`.
fix
Verify that your `messages` object contains entries for all active and fallback locales, and that they are correctly structured and passed into the `createI18n` function.
Property '$t' does not exist on type 'ComponentPublicInstance<...>' or 'Cannot read properties of undefined (reading '$t')'
This typically occurs when trying to access global i18n properties like `$t` (Options API) or the `t` function (Composition API via `useI18n`) without correctly installing the `i18n` instance on the Vue application or outside an appropriate component context.
fix
For Options API, ensure `app.use(i18n)` is called in your main application entry point. For Composition API, ensure `const { t } = useI18n()` is called within a component's `setup` function or a setup-like context, and that `legacy: false` is set in `createI18n`.
You must set 'legacy: false' option to use the Composition API
You are attempting to use Vue I18n's Composition API features (e.g., `useI18n`) with an i18n instance configured in 'legacy' mode (which is often the default or implied if not explicitly set to `false`).
fix
When initializing your i18n instance with `createI18n`, explicitly include `legacy: false` in the options object to enable Composition API support: `createI18n({ legacy: false, ... })`.
Upgrade
Version history
11.3.2latest on npm
Audit
Dependencies
vuerequiredVue I18n is a plugin for Vue.js and requires Vue 3 as a peer dependency.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
vue-i18n — npm install vue-i18n · libregistry