Vue I18n Bridge for Legacy Projects

raw JSON →
9.14.1 verified Sat Apr 25 auth: no javascript

vue-i18n-bridge is a specialized package designed to facilitate the migration of Vue 2 applications using vue-i18n v8.x (the "legacy" version) to the modern vue-i18n v9.x+ (the "next" version), which is primarily built for Vue 3. It allows developers to incrementally adopt the Composition API and new i18n features in their Vue 2 projects without a full rewrite, leveraging `@vue/composition-api` for reactivity. The bridge ensures compatibility between the global `$i18n` instance patterns from v8 and the application-level i18n instance of v9, making it a crucial tool during a phased migration. The current stable version is 9.14.1, aligning with the `vue-i18n-next` release cycle, with frequent updates addressing bugs and improving compatibility. Its key differentiator is enabling a mixed-mode i18n environment, allowing co-existence of legacy Options API components with new Composition API components using the updated i18n APIs during a transition phase.

error Uncaught SyntaxError: vue-i18n-bridge support Vue 2.x only
cause Attempting to use `vue-i18n-bridge` in a Vue 3 environment, or a Vue 2 project with `@vue/compat` where Vue is detected as version 3.
fix
Ensure your project is strictly a Vue 2 application with @vue/composition-api (for Vue 2.6/2.7). vue-i18n-bridge is not designed for Vue 3 or @vue/compat for Vue 3 migration. For Vue 3, use vue-i18n v9+ directly.
error Cannot read properties of undefined (reading 'config')
cause Vue I18n plugin not correctly installed or initialized globally in a Vue 2 app, or `this.$i18n` is accessed before the i18n instance is available.
fix
Ensure Vue.use(VueI18n, { bridge: true }) is called in your main.ts or main.js *before* creating the root Vue instance. Also, confirm createI18n is properly configured and passed to the Vue instance.
error TypeError: createI18n is not a function
cause Usually happens when importing `createI18n` from `vue-i18n` directly in a Vue 2 environment expecting the bridge to handle it, or `vue-i18n-bridge` itself is not installed or incorrectly imported.
fix
Ensure vue-i18n-bridge is installed and you are importing createI18n from 'vue-i18n-bridge', not 'vue-i18n', when working with the bridge in Vue 2.
error TypeError: Cannot read property '_t' of undefined / Cannot read properties of undefined (reading '$i18n')
cause The i18n instance or its translation methods (`$t`, `t`) are being called before the i18n instance is properly provided to the component or is not available in the current scope. This is common with Composition API if `useI18n()` is not called or if the global scope is not properly set up.
fix
Verify that useI18n() is called within the setup() function of your component. If using Options API, ensure the i18n instance is injected into the root Vue application and that this.$i18n is accessed within a mounted component context.
error Cannot read properties of undefined (reading '__i18n') (Vue 2.7 specific)
cause This error can occur in Vue 2.7 projects with i18n custom blocks if the internal reactivity system (often related to `vue-demi` or `@vue/composition-api`) is not correctly harmonized by `vue-i18n-bridge`.
fix
Ensure all required peer dependencies, especially vue-demi (for Vue 2.7) and @vue/composition-api (for Vue 2.6), are installed at the correct versions as specified by vue-i18n-bridge. Refer to the vue-i18n-bridge documentation for specific Vue 2.7 setup instructions.
breaking The `vue-i18n-bridge` package will no longer be provided starting with `vue-i18n` v10, as Vue 2 is past its End-Of-Life (EOL). Version 9.13 of `vue-i18n-bridge` (and `vue-i18n` v9.13) is expected to be the last supported version.
fix Plan for full migration to Vue 3 and `vue-i18n` v9 or later directly, or consider alternatives for Vue 2 internationalization that are still maintained if a full Vue 3 upgrade is not feasible.
gotcha When using `vue-i18n-bridge` in Vue 2.6, you must explicitly pass the `VueI18n` constructor from `vue-i18n` v8.x as the second argument to `createI18n` and use `{ bridge: true }` in `Vue.use(VueI18n, { bridge: true })`.
fix Ensure `Vue.use(VueI18n, { bridge: true })` is called with the legacy `VueI18n` instance, and `createI18n({ legacy: false, ... }, VueI18n)` is used, passing the v8 `VueI18n` constructor as the second argument.
gotcha New message format syntax (from `vue-i18n-next`) is only available in Composition API mode when using the bridge. Legacy API mode cannot use these new features.
fix Refactor components to use the Composition API (`setup()` function and `useI18n`) to leverage modern message formatting features.
gotcha Back-ported components like `<i18n-t>`, `<i18n-d>`, and `<i18n-n>` are not available in Legacy API mode when using `vue-i18n-bridge`.
fix Migrate relevant components to use the Composition API and their programmatic equivalents (`t`, `d`, `n` functions) or custom logic.
gotcha `vue-i18n-bridge` is specifically for Vue 2.x environments. Attempting to use it directly in a Vue 3 project (even with `@vue/compat`) will result in an error indicating it only supports Vue 2.x.
fix For Vue 3 projects, directly use `vue-i18n` v9 or later. The bridge is intended for incremental migration *within* Vue 2, not for Vue 3 compatibility itself.
gotcha When bundling with Vite, you may need to explicitly exclude `vue-i18n-bridge` from pre-bundling to ensure it works correctly.
fix Add `optimizeDeps: { exclude: ['vue-i18n-bridge'] }` to your `vite.config.js` or `vite.config.ts`.
npm install vue-i18n-bridge
yarn add vue-i18n-bridge
pnpm add vue-i18n-bridge

Demonstrates how to set up `vue-i18n-bridge` in a Vue 2 application using TypeScript, enabling the Composition API and `vue-i18n` v9 features, including dynamic locale switching.

import Vue from 'vue';
import VueCompositionAPI from '@vue/composition-api';
import { createI18n, useI18n } from 'vue-i18n-bridge'; // Import from vue-i18n-bridge
import App from './App.vue';

// 1. Install Composition API for Vue 2
Vue.use(VueCompositionAPI);

// 2. Install vue-i18n (v8.x) with the bridge option
// Note: `vue-i18n-bridge` must also be installed via npm/yarn/pnpm
// For Vue 2.6, VueI18n constructor from 'vue-i18n' (v8) is passed as a second argument
// For Vue 2.7, this step might be slightly different with `vue-demi`
import VueI18n from 'vue-i18n'; // Legacy vue-i18n v8
Vue.use(VueI18n as any, { bridge: true }); // Important: tell v8.x to enable bridge mode

const messages = {
  en: {
    hello: 'Hello Vue 2 with i18n v9 features!',
    greeting: 'Welcome, {name}!'
  },
  es: {
    hello: '¡Hola Vue 2 con características de i18n v9!',
    greeting: '¡Bienvenido, {name}!'
  }
};

// 3. Create the i18n instance using createI18n from vue-i18n-bridge
const i18n = createI18n({
  legacy: false, // Essential for using Composition API mode and vue-i18n@9 features
  locale: 'en',
  fallbackLocale: 'en',
  messages,
}, VueI18n); // Pass the VueI18n v8 constructor as the second argument for Vue 2.6

// Inject i18n instance into Vue 2 app
new Vue({
  i18n: i18n as any, // Type assertion often needed due to bridge's compatibility layer
  render: h => h(App),
}).$mount('#app');

// App.vue (example component using Composition API)
// Ensure you have a template like <template>...</template> in App.vue

/*
<script lang="ts">
import { defineComponent, ref } from '@vue/composition-api';
import { useI18n } from 'vue-i18n-bridge'; // Use useI18n from the bridge

export default defineComponent({
  name: 'App',
  setup() {
    const { t, locale } = useI18n(); // Access translation functions
    const username = ref('Developer');

    const switchLocale = (newLocale: string) => {
      locale.value = newLocale;
    };

    return {
      t,
      locale,
      username,
      switchLocale,
    };
  },
  template: `
    <div>
      <h1>{{ t('hello') }}</h1>
      <p>{{ t('greeting', { name: username }) }}</p>
      <p>Current Locale: {{ locale }}</p>
      <button @click="switchLocale('en')">English</button>
      <button @click="switchLocale('es')">Español</button>
    </div>
  `
});
</script>
*/