Registry / web-framework / i18next-vue

i18next-vue

JSON →
library5.4.0jsnpmunverified

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.

npm install i18next-vue
INSTALL
IMPORT
SIG · I18NEXT-VUE
I
i18next-vue
web-frameworkjavascriptv5.4.0
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.

I18NextVue
import I18NextVue from 'i18next-vue'
import { I18NextVue } from 'i18next-vue'
This is the default export plugin for Vue's `app.use()`.
useTranslation
import { useTranslation } from 'i18next-vue'
import useTranslation from 'i18next-vue/useTranslation'
A named export for Vue 3 Composition API hook.
i18next (core)
import i18next from 'i18next'
const i18next = require('i18next')
The core i18next library, a peer dependency, must be imported separately and initialized before passing to i18next-vue.
$t (global)
this.$t('key')
Accessible on `this` in Options API components and globally within templates after installing the plugin.

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 `<i18next>` component.

import { createApp, defineComponent } from 'vue'; import i18next from 'i18next'; import I18NextVue from 'i18next-vue'; import { useTranslation } from 'i18next-vue'; // 1. Initialize i18next (before mounting Vue app) i18next.init({ lng: 'en', fallbackLng: 'en', resources: { en: { translation: { 'welcome': 'Welcome to our app!', 'greeting': 'Hello, {{name}}!', 'dynamic_link': 'Visit the {{link}} page.', 'home': 'Home' } }, de: { translation: { 'welcome': 'Willkommen in unserer App!', 'greeting': 'Hallo, {{name}}!', 'dynamic_link': 'Besuchen Sie die {{link}} Seite.', 'home': 'Startseite' } } } }); // 2. Define your root Vue component const App = defineComponent({ setup() { const { i18next, t } = useTranslation(); const changeLanguage = (lang: string) => { i18next.changeLanguage(lang); }; return { i18next, t, changeLanguage }; }, template: ` <div> <h1>{{ t('welcome') }}</h1> <p>{{ t('greeting', { name: 'World' }) }}</p> <p>Current language: {{ i18next.language }}</p> <button @click="changeLanguage('en')">English</button> <button @click="changeLanguage('de')">Deutsch</button> <h2>Using $t in template:</h2> <p>{{ $t('greeting', { name: 'Vue User' }) }}</p> <h2>Using the <i18next> component for rich text:</h2> <i18next :translation="t('dynamic_link')"> <template #link> <a href="/home">{{ t('home') }}</a> </template> </i18next> </div> ` }); // 3. Create and mount the Vue app with the i18next-vue plugin const app = createApp(App); app.use(I18NextVue, { i18next }); app.mount('#app');
Debug
Known issues
breakingVersion 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.
fix
Update your TypeScript declaration files to reflect the new `declare module 'vue'` pattern. Refer to the official migration guide for exact changes.
affects: >=5.0.0
breakingVersion 4.0 entirely removed support for `i18nOptions`. Any existing configurations using this property will cause errors.
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.
affects: >=4.0.0
breakingVersion 3.0 introduced significant changes, particularly enhancing Composition API support and removing legacy functionality. Migration from v2.x requires review of the updated documentation.
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.
affects: >=3.0.0
gotchaBefore 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.
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.
affects: <5.1.0
gotchaTypeScript type suggestions for the `$t` function might not have included keys with namespace prefixes (e.g., `my-namespace:key`) before v5.2.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.
affects: <5.2.0
Errors
Common errors & fixes
Property '$t' does not exist on type '...' (e.g., 'ComponentPublicInstance')
Incorrect or missing TypeScript augmentation for global properties in Vue, or using a version of i18next-vue that clashes with Vue's type definitions.
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.
Error: i18next instance was not provided!
The `i18next` instance was not passed correctly to the `I18NextVue` plugin during `app.use()`.
fix
Make sure you call `app.use(I18NextVue, { i18next: yourInitializedI18nextInstance })` and that `yourInitializedI18nextInstance` is a properly configured i18next object.
TypeError: useTranslation is not a function
Attempting to use `useTranslation` in a non-Composition API context, or an incorrect import path.
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.
[Vue warn]: Failed to resolve component: i18next
The `<i18next>` translation component is not registered or available.
fix
The `<i18next>` 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.
Upgrade
Version history
5.4.0latest on npm
Audit
Dependencies
i18nextrequiredCore internationalization library; i18next-vue is a wrapper.
vuerequiredVue 3 framework; i18next-vue is a Vue plugin.
Agent activity
4 hits · last 30 days
node
4
Resources
i18next-vue — npm install i18next-vue · libregistry