i18next-vue

Common errors

• Property '$t' does not exist on type '...' (e.g., 'ComponentPublicInstance')

  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.
  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!

  cause 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

  cause 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

  cause 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.

Warnings

• breaking 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.
  Fix: Update your TypeScript declaration files to reflect the new `declare module 'vue'` pattern. Refer to the official migration guide for exact changes.
• breaking Version 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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha TypeScript 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.

Install

• npm install i18next-vue npm
• yarn add i18next-vue yarn
• pnpm add i18next-vue pnpm

Imports

• I18NextVue
  wrong:

  import { I18NextVue } from 'i18next-vue'

  correct:

  import I18NextVue from 'i18next-vue'

  This is the default export plugin for Vue's `app.use()`.
• useTranslation
  wrong:

  import useTranslation from 'i18next-vue/useTranslation'

  correct:

  import { useTranslation } from 'i18next-vue'

  A named export for Vue 3 Composition API hook.
• i18next (core)
  wrong:

  const i18next = require('i18next')

  correct:

  import i18next from '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.

Quickstart

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');