{"id":11070,"library":"i18next-vue","title":"i18next-vue","description":"i18next-vue is the official integration library for using the i18next internationalization framework with Vue 3 applications. It simplifies the process of translating content by providing a Vue plugin (`I18NextVue`) and a Composition API hook (`useTranslation`), along with global properties like `$t` and `$i18next` for easy access within components. The current stable version is 5.4.0, with regular updates that include performance improvements, bug fixes, and minor features, alongside occasional breaking changes for major version bumps (e.g., v3, v4, v5) to align with i18next or Vue ecosystem changes. It differentiates itself by offering robust TypeScript support and seamless reactivity for language switching and dynamic content, leveraging Vue's application context for broader compatibility, including Pinia stores.","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/i18next/i18next-vue","tags":["javascript","i18n","i18next","vue","typescript"],"install":[{"cmd":"npm install i18next-vue","lang":"bash","label":"npm"},{"cmd":"yarn add i18next-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18next-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core internationalization library; i18next-vue is a wrapper.","package":"i18next","optional":false},{"reason":"Vue 3 framework; i18next-vue is a Vue plugin.","package":"vue","optional":false}],"imports":[{"note":"This is the default export plugin for Vue's `app.use()`.","wrong":"import { I18NextVue } from 'i18next-vue'","symbol":"I18NextVue","correct":"import I18NextVue from 'i18next-vue'"},{"note":"A named export for Vue 3 Composition API hook.","wrong":"import useTranslation from 'i18next-vue/useTranslation'","symbol":"useTranslation","correct":"import { useTranslation } from 'i18next-vue'"},{"note":"The core i18next library, a peer dependency, must be imported separately and initialized before passing to i18next-vue.","wrong":"const i18next = require('i18next')","symbol":"i18next (core)","correct":"import i18next from 'i18next'"},{"note":"Accessible on `this` in Options API components and globally within templates after installing the plugin.","symbol":"$t (global)","correct":"this.$t('key')"}],"quickstart":{"code":"import { createApp, defineComponent } from 'vue';\nimport i18next from 'i18next';\nimport I18NextVue from 'i18next-vue';\nimport { useTranslation } from 'i18next-vue';\n\n// 1. Initialize i18next (before mounting Vue app)\ni18next.init({\n lng: 'en',\n fallbackLng: 'en',\n resources: {\n en: {\n translation: {\n 'welcome': 'Welcome to our app!',\n 'greeting': 'Hello, {{name}}!',\n 'dynamic_link': 'Visit the {{link}} page.',\n 'home': 'Home'\n }\n },\n de: {\n translation: {\n 'welcome': 'Willkommen in unserer App!',\n 'greeting': 'Hallo, {{name}}!',\n 'dynamic_link': 'Besuchen Sie die {{link}} Seite.',\n 'home': 'Startseite'\n }\n }\n }\n});\n\n// 2. Define your root Vue component\nconst App = defineComponent({\n setup() {\n const { i18next, t } = useTranslation();\n const changeLanguage = (lang: string) => {\n i18next.changeLanguage(lang);\n };\n return { i18next, t, changeLanguage };\n },\n template: `\n
\n `\n});\n\n// 3. Create and mount the Vue app with the i18next-vue plugin\nconst app = createApp(App);\napp.use(I18NextVue, { i18next });\napp.mount('#app');\n","lang":"typescript","description":"This quickstart demonstrates how to initialize i18next, integrate i18next-vue as a plugin, and use both the Composition API's `useTranslation` hook and the global `$t` function for translations. It also shows language switching and rich text interpolation with the `` component."},"warnings":[{"fix":"Update your TypeScript declaration files to reflect the new `declare module 'vue'` pattern. Refer to the official migration guide for exact changes.","message":"Version 5.0 changed how Vue types are augmented for global `$t` and `$i18next` properties. It now uses `declare module 'vue'` instead of `declare module '@vue/runtime-core'`, which can break existing TypeScript setups.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Remove the `i18nOptions` property from your `I18NextVue` plugin configuration. All i18next configuration should now be done directly on the `i18next` instance passed to the plugin.","message":"Version 4.0 entirely removed support for `i18nOptions`. Any existing configurations using this property will cause errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Consult the migration guide from v2.x to v3.x on the i18next-vue documentation. This often involves adapting to new Composition API patterns and changes in plugin configuration.","message":"Version 3.0 introduced significant changes, particularly enhancing Composition API support and removing legacy functionality. Migration from v2.x requires review of the updated documentation.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade to i18next-vue v5.1.0 or newer. This version uses app-level `provide`/`inject` to ensure `useTranslation()` is available in `app.runWithContext()` contexts.","message":"Before v5.1.0, the `useTranslation()` Composition API hook might not have worked correctly within contexts like Pinia stores or other scenarios using `app.runWithContext()`. This was due to how internal dependencies were provided.","severity":"gotcha","affected_versions":"<5.1.0"},{"fix":"Upgrade to i18next-vue v5.2.0 or newer to benefit from improved TypeScript type inference for `$t` that suggests keys including those with prefixes.","message":"TypeScript type suggestions for the `$t` function might not have included keys with namespace prefixes (e.g., `my-namespace:key`) before v5.2.0.","severity":"gotcha","affected_versions":"<5.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are on i18next-vue v5.0.0+ and that your TypeScript setup correctly includes the `declare module 'vue'` pattern as described in the v5 migration guide. Also, verify `app.use(I18NextVue, { i18next })` is correctly called.","cause":"Incorrect or missing TypeScript augmentation for global properties in Vue, or using a version of i18next-vue that clashes with Vue's type definitions.","error":"Property '$t' does not exist on type '...' (e.g., 'ComponentPublicInstance')"},{"fix":"Make sure you call `app.use(I18NextVue, { i18next: yourInitializedI18nextInstance })` and that `yourInitializedI18nextInstance` is a properly configured i18next object.","cause":"The `i18next` instance was not passed correctly to the `I18NextVue` plugin during `app.use()`.","error":"Error: i18next instance was not provided!"},{"fix":"Ensure `useTranslation` is imported as a named export (`import { useTranslation } from 'i18next-vue'`) and used within a Vue 3 `setup()` function or Composition API component.","cause":"Attempting to use `useTranslation` in a non-Composition API context, or an incorrect import path.","error":"TypeError: useTranslation is not a function"},{"fix":"The `` component should be automatically available after `app.use(I18NextVue, { i18next })`. If still failing, ensure the plugin is applied correctly and Vue is picking up the component registration.","cause":"The `` translation component is not registered or available.","error":"[Vue warn]: Failed to resolve component: i18next"}],"ecosystem":"npm"}