Vue I18n Bridge for Legacy Projects
raw JSON →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.
Common errors
error Uncaught SyntaxError: vue-i18n-bridge support Vue 2.x only ↓
@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') ↓
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 ↓
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') ↓
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) ↓
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. Warnings
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. ↓
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 })`. ↓
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. ↓
gotcha Back-ported components like `<i18n-t>`, `<i18n-d>`, and `<i18n-n>` are not available in Legacy API mode when using `vue-i18n-bridge`. ↓
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. ↓
gotcha When bundling with Vite, you may need to explicitly exclude `vue-i18n-bridge` from pre-bundling to ensure it works correctly. ↓
Install
npm install vue-i18n-bridge yarn add vue-i18n-bridge pnpm add vue-i18n-bridge Imports
- createI18n wrong
import { createI18n } from 'vue-i18n'correctimport { createI18n } from 'vue-i18n-bridge' - useI18n wrong
import { useI18n } from 'vue-i18n'correctimport { useI18n } from 'vue-i18n-bridge' - VueI18n (type) wrong
import VueI18n from 'vue-i18n'correctimport type { VueI18n } from 'vue-i18n-bridge' - isVueI18n8, isVueI18n9
import { isVueI18n8, isVueI18n9 } from 'vue-i18n-bridge'
Quickstart
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>
*/