{"id":18077,"library":"vue-i18n-bridge","title":"Vue I18n Bridge for Legacy Projects","description":"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.","status":"active","version":"9.14.1","language":"javascript","source_language":"en","source_url":"https://github.com/intlify/vue-i18n-next","tags":["javascript","bridge","i18n","internationalization","intlify","migration","plugin","vue","vue.js","typescript"],"install":[{"cmd":"npm install vue-i18n-bridge","lang":"bash","label":"npm"},{"cmd":"yarn add vue-i18n-bridge","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-i18n-bridge","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required 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`.","package":"@vue/composition-api","optional":false},{"reason":"The 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`.","package":"vue-i18n","optional":false},{"reason":"Required for Vue 2.7 support, enabling cross-version compatibility for Vue's reactivity system. Peer dependency: `>= v0.13.5`.","package":"vue-demi"}],"imports":[{"note":"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.","wrong":"import { createI18n } from 'vue-i18n'","symbol":"createI18n","correct":"import { createI18n } from 'vue-i18n-bridge'"},{"note":"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.","wrong":"import { useI18n } from 'vue-i18n'","symbol":"useI18n","correct":"import { useI18n } from 'vue-i18n-bridge'"},{"note":"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.","wrong":"import VueI18n from 'vue-i18n'","symbol":"VueI18n (type)","correct":"import type { VueI18n } from 'vue-i18n-bridge'"},{"note":"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.","symbol":"isVueI18n8, isVueI18n9","correct":"import { isVueI18n8, isVueI18n9 } from 'vue-i18n-bridge'"}],"quickstart":{"code":"import Vue from 'vue';\nimport VueCompositionAPI from '@vue/composition-api';\nimport { createI18n, useI18n } from 'vue-i18n-bridge'; // Import from vue-i18n-bridge\nimport App from './App.vue';\n\n// 1. Install Composition API for Vue 2\nVue.use(VueCompositionAPI);\n\n// 2. Install vue-i18n (v8.x) with the bridge option\n// Note: `vue-i18n-bridge` must also be installed via npm/yarn/pnpm\n// For Vue 2.6, VueI18n constructor from 'vue-i18n' (v8) is passed as a second argument\n// For Vue 2.7, this step might be slightly different with `vue-demi`\nimport VueI18n from 'vue-i18n'; // Legacy vue-i18n v8\nVue.use(VueI18n as any, { bridge: true }); // Important: tell v8.x to enable bridge mode\n\nconst messages = {\n  en: {\n    hello: 'Hello Vue 2 with i18n v9 features!',\n    greeting: 'Welcome, {name}!'\n  },\n  es: {\n    hello: '¡Hola Vue 2 con características de i18n v9!',\n    greeting: '¡Bienvenido, {name}!'\n  }\n};\n\n// 3. Create the i18n instance using createI18n from vue-i18n-bridge\nconst i18n = createI18n({\n  legacy: false, // Essential for using Composition API mode and vue-i18n@9 features\n  locale: 'en',\n  fallbackLocale: 'en',\n  messages,\n}, VueI18n); // Pass the VueI18n v8 constructor as the second argument for Vue 2.6\n\n// Inject i18n instance into Vue 2 app\nnew Vue({\n  i18n: i18n as any, // Type assertion often needed due to bridge's compatibility layer\n  render: h => h(App),\n}).$mount('#app');\n\n// App.vue (example component using Composition API)\n// Ensure you have a template like <template>...</template> in App.vue\n\n/*\n<script lang=\"ts\">\nimport { defineComponent, ref } from '@vue/composition-api';\nimport { useI18n } from 'vue-i18n-bridge'; // Use useI18n from the bridge\n\nexport default defineComponent({\n  name: 'App',\n  setup() {\n    const { t, locale } = useI18n(); // Access translation functions\n    const username = ref('Developer');\n\n    const switchLocale = (newLocale: string) => {\n      locale.value = newLocale;\n    };\n\n    return {\n      t,\n      locale,\n      username,\n      switchLocale,\n    };\n  },\n  template: `\n    <div>\n      <h1>{{ t('hello') }}</h1>\n      <p>{{ t('greeting', { name: username }) }}</p>\n      <p>Current Locale: {{ locale }}</p>\n      <button @click=\"switchLocale('en')\">English</button>\n      <button @click=\"switchLocale('es')\">Español</button>\n    </div>\n  `\n});\n</script>\n*/","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"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 })`.","severity":"gotcha","affected_versions":">=9.0.0"},{"fix":"Refactor components to use the Composition API (`setup()` function and `useI18n`) to leverage modern message formatting features.","message":"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.","severity":"gotcha","affected_versions":">=9.0.0"},{"fix":"Migrate relevant components to use the Composition API and their programmatic equivalents (`t`, `d`, `n` functions) or custom logic.","message":"Back-ported components like `<i18n-t>`, `<i18n-d>`, and `<i18n-n>` are not available in Legacy API mode when using `vue-i18n-bridge`.","severity":"gotcha","affected_versions":">=9.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"*"},{"fix":"Add `optimizeDeps: { exclude: ['vue-i18n-bridge'] }` to your `vite.config.js` or `vite.config.ts`.","message":"When bundling with Vite, you may need to explicitly exclude `vue-i18n-bridge` from pre-bundling to ensure it works correctly.","severity":"gotcha","affected_versions":">=9.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","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.","error":"Uncaught SyntaxError: vue-i18n-bridge support Vue 2.x only"},{"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.","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.","error":"Cannot read properties of undefined (reading 'config')"},{"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.","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.","error":"TypeError: createI18n is not a function"},{"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.","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.","error":"TypeError: Cannot read property '_t' of undefined / Cannot read properties of undefined (reading '$i18n')"},{"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.","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`.","error":"Cannot read properties of undefined (reading '__i18n') (Vue 2.7 specific)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}