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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createI18n
✓ import { createI18n } from 'vue-i18n-bridge'
✗ import { createI18n } from 'vue-i18n'
When using `vue-i18n-bridge`, you import `createI18n` directly from `vue-i18n-bridge`. The bridge internally redirects to the appropriate `vue-i18n` version. `legacy: false` must be set for Composition API mode.
useI18n
✓ import { useI18n } from 'vue-i18n-bridge'
✗ import { useI18n } from 'vue-i18n'
This Composition API hook is provided by `vue-i18n-bridge` and is enabled in Vue 2 environments when the bridge is correctly installed. It allows accessing the i18n instance within `setup()` functions.
VueI18n (type)
✓ import type { VueI18n } from 'vue-i18n-bridge'
✗ import VueI18n from 'vue-i18n'
While `VueI18n` was a default export constructor in v8.x, in a bridged setup for Vue 2, the `VueI18n` type, if explicitly needed for global type declarations or legacy interactions, should be imported from `vue-i18n-bridge` to ensure correct compatibility.
isVueI18n8, isVueI18n9
✓ import { isVueI18n8, isVueI18n9 } from 'vue-i18n-bridge'
These utility functions are provided by `vue-i18n-bridge` to programmatically detect the active `vue-i18n` version being used (v8.x or v9.x), useful for conditional logic during migration.
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>
*/
Errors
Common errors & fixes
Uncaught SyntaxError: vue-i18n-bridge support Vue 2.x only
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.
fixEnsure 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.
Cannot read properties of undefined (reading 'config')
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.
fixEnsure `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. TypeError: createI18n is not a function
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.
fixEnsure `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.
TypeError: Cannot read property '_t' of undefined / Cannot read properties of undefined (reading '$i18n')
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.
fixVerify 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.
Cannot read properties of undefined (reading '__i18n') (Vue 2.7 specific)
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`.
fixEnsure 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.
Audit
Dependencies
@vue/composition-apirequiredRequired for Vue 2 applications to enable Composition API features, which are fundamental to `vue-i18n` v9 and the bridge's functionality. Peer dependency: `>= v1.2.0`.
vue-i18nrequiredThe bridge is a compatibility layer between legacy `vue-i18n@v8.26.1` and `vue-i18n@v9.x`. It requires `vue-i18n` version `>= v8.26.1 < v9` or `>= v9.2.0-beta.25`.
vue-demirequiredRequired for Vue 2.7 support, enabling cross-version compatibility for Vue's reactivity system. Peer dependency: `>= v0.13.5`.