{"id":16927,"library":"vue-i18n","title":"Vue I18n","description":"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.","status":"active","version":"11.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/intlify/vue-i18n","tags":["javascript","i18n","internationalization","intlify","plugin","vue","vue.js","typescript"],"install":[{"cmd":"npm install vue-i18n","lang":"bash","label":"npm"},{"cmd":"yarn add vue-i18n","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-i18n","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Vue I18n is a plugin for Vue.js and requires Vue 3 as a peer dependency.","package":"vue","optional":false}],"imports":[{"note":"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+.","wrong":"const { createI18n } = require('vue-i18n')","symbol":"createI18n","correct":"import { createI18n } from 'vue-i18n'"},{"note":"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.","symbol":"useI18n","correct":"import { useI18n } from 'vue-i18n'"},{"note":"When importing types in TypeScript, using the `type` keyword explicitly improves clarity and can assist with tree-shaking.","symbol":"I18nOptions","correct":"import type { I18nOptions } from 'vue-i18n'"},{"note":"The directive is exported as `vI18n` and registered with `app.directive('i18n', vI18n)`.","wrong":"import { i18nDirective } from 'vue-i18n'","symbol":"vI18n","correct":"import { vI18n } from 'vue-i18n'"}],"quickstart":{"code":"import { createApp, ref } from 'vue'\nimport { createI18n, useI18n } from 'vue-i18n'\n\n// Root Vue app component (e.g., App.vue)\nconst App = {\n template: `\n
\n

{{ t('greeting', { name: 'World' }) }}

\n

{{ t('welcome') }}

\n

{{ t('pluralExample', { count: messageCount }) }}

\n

{{ t('dynamicMessage', { type: 'dynamic' }) }}

\n\n \n \n
\n `,\n setup() {\n // Use the Composition API hook\n const { t, locale } = useI18n({ useScope: 'global' }) // 'global' scope is necessary for root app messages\n\n const messageCount = ref(1)\n\n const changeLocale = (lang: string) => {\n locale.value = lang // Reactively change the current locale\n messageCount.value = lang === 'en' ? 5 : 1 // Example for pluralization demo\n }\n\n return { t, messageCount, changeLocale }\n }\n}\n\n// Locale messages definitions\nconst messages = {\n en: {\n greeting: 'Hello, {name}!',\n welcome: 'Welcome to our site.',\n pluralExample: 'You have {count} message | You have {count} messages.',\n dynamicMessage: 'This is a {type} message.'\n },\n fr: {\n greeting: 'Bonjour, {name} !',\n welcome: 'Bienvenue sur notre site.',\n pluralExample: 'Vous avez {count} message | Vous avez {count} messages.',\n dynamicMessage: 'Ceci est un message {type}.'\n }\n}\n\n// Create the i18n instance\nconst i18n = createI18n({\n legacy: false, // Essential for using Composition API with Vue I18n v9+\n locale: 'en', // Default locale\n fallbackLocale: 'en', // Fallback locale if a message is not found\n messages // Provide all locale messages\n})\n\n// Create the Vue app instance\nconst app = createApp(App)\n\n// Install the i18n plugin\napp.use(i18n)\n\n// Mount the app to a DOM element\napp.mount('#app')","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Vue 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.","severity":"breaking","affected_versions":"<9.0.0"},{"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).","message":"Using 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.","severity":"gotcha","affected_versions":">=9.0.0"},{"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`.","message":"The 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.","severity":"deprecated","affected_versions":">=9.3.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=9.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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`.","error":"[vue-i18n] Not found locale messages in \"en\""},{"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`.","cause":"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.","error":"Property '$t' does not exist on type 'ComponentPublicInstance<...>' or 'Cannot read properties of undefined (reading '$t')'"},{"fix":"When initializing your i18n instance with `createI18n`, explicitly include `legacy: false` in the options object to enable Composition API support: `createI18n({ legacy: false, ... })`.","cause":"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`).","error":"You must set 'legacy: false' option to use the Composition API"}],"ecosystem":"npm","meta_description":null}