Registry / web-framework / vue-i18n-bridge

vue-i18n-bridge

JSON →
library9.14.1jsnpmunverified

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.

npm install vue-i18n-bridge
INSTALL
IMPORT
SIG · VUE-I18N-BRIDGE
V
vue-i18n-bridge
web-frameworkjavascriptv9.14.1
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.

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> */
Debug
Known issues
breakingThe `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.
affects: >=10.0.0
gotchaWhen 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.
affects: >=9.0.0
gotchaNew 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.
affects: >=9.0.0
gotchaBack-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.
affects: >=9.0.0
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.
affects: *
gotchaWhen 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`.
affects: >=9.0.0
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.
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.
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.
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.
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.
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.
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.
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.
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`.
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.
Upgrade
Version history
9.14.1latest on npm
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`.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
vue-i18n-bridge — npm install vue-i18n-bridge · libregistry