{"id":12507,"library":"vue-i18n-routing","title":"Vue I18n Routing","description":"vue-i18n-routing is a critical extension within the Intlify ecosystem, designed to seamlessly integrate internationalization capabilities (provided by `vue-i18n`) with client-side routing (provided by `vue-router`). It enhances `vue-router` by enabling locale-aware URL patterns, dynamic route parameter handling for locales, and helper functions for navigating between localized routes. The package is currently at version 1.2.0 and receives active maintenance, evidenced by recent bug fixes and feature additions. Its primary differentiator is providing a cohesive solution for managing multi-language URLs without boilerplate, supporting both Vue 2 (via `vue-i18n-bridge` and `@vue/composition-api`) and Vue 3 environments. It abstracts the complexity of locale prefixes and path resolution, making it easier to build SEO-friendly, internationalized Vue applications with consistent user experiences across different languages.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/intlify/routing","tags":["javascript","i18n","internationalization","intlify","routing","typescript"],"install":[{"cmd":"npm install vue-i18n-routing","lang":"bash","label":"npm"},{"cmd":"yarn add vue-i18n-routing","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-i18n-routing","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Vue 2 compatibility to use Composition API features.","package":"@vue/composition-api","optional":true},{"reason":"Core Vue.js library. Supports Vue 2.6.14+ and Vue 3.2.0+.","package":"vue","optional":false},{"reason":"The primary internationalization library this package extends. Supports vue-i18n 8.26.1+ or 9.2.0+.","package":"vue-i18n","optional":false},{"reason":"Enables Vue 3 Composition API usage with Vue 2, crucial for cross-version compatibility.","package":"vue-i18n-bridge","optional":true},{"reason":"The core routing library this package enhances. Supports vue-router 3.5.3+ or 4.0.0+.","package":"vue-router","optional":false}],"imports":[{"note":"This `createRouter` is a wrapper provided by vue-i18n-routing that integrates i18n logic with Vue Router. Always use this one when you need i18n functionality in your routes.","wrong":"import { createRouter } from 'vue-router' // For i18n-aware routing, use vue-i18n-routing's wrapper","symbol":"createRouter","correct":"import { createRouter } from 'vue-i18n-routing'"},{"note":"A Composition API hook to get the path for the current route with the active locale prefix. Essential for programmatic navigation within a localized application.","wrong":"import { useLocalePath } from 'vue-i18n'","symbol":"useLocalePath","correct":"import { useLocalePath } from 'vue-i18n-routing'"},{"note":"A Composition API hook that provides a function to switch the locale of the current route, generating the correct URL for the new locale while preserving the route name and params.","wrong":"import { useSwitchLocalePath } from 'vue-i18n'","symbol":"useSwitchLocalePath","correct":"import { useSwitchLocalePath } from 'vue-i18n-routing'"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport { createRouter, createWebHistory } from 'vue-router';\nimport { createI18n } from 'vue-i18n';\nimport { createRouter as createI18nRouter, useLocalePath, useSwitchLocalePath } from 'vue-i18n-routing';\n\n// --- i18n setup ---\nconst messages = {\n en: {\n welcome: 'Welcome to our multi-language app!',\n about: 'About Us',\n home: 'Home',\n greeting: 'Hello from home!',\n switch_locale: 'Switch to {locale}'\n },\n fr: {\n welcome: 'Bienvenue dans notre application multilingue !',\n about: 'À Propos',\n home: 'Accueil',\n greeting: 'Bonjour de l\\'accueil !',\n switch_locale: 'Passer au {locale}'\n }\n};\n\nconst i18n = createI18n({\n locale: 'en',\n fallbackLocale: 'en',\n messages,\n legacy: false, // Must be false for Composition API\n globalInjection: true\n});\n\n// --- Vue Router setup ---\nconst routes = [\n {\n path: '/:locale',\n component: { template: '' }, // A wrapper for localized routes\n children: [\n { path: '', name: 'home', component: { template: `\n
\n ` } }\n ]\n }\n];\n\nconst router = createI18nRouter({\n router: createRouter({\n history: createWebHistory(),\n routes\n }),\n i18n,\n defaultLocale: 'en' // Specify default locale to omit from path\n});\n\n// --- Vue App setup ---\nconst app = createApp({\n setup() {\n const localePath = useLocalePath();\n const switchLocalePath = useSwitchLocalePath();\n\n const switchLocale = (locale) => {\n router.push(switchLocalePath(locale));\n };\n\n return { localePath, switchLocale };\n }\n});\n\napp.use(i18n);\napp.use(router);\n\napp.mount('#app');","lang":"typescript","description":"This quickstart demonstrates how to set up a basic Vue 3 application with `vue-i18n` and `vue-i18n-routing`. It configures two locales (English and French), defines locale-prefixed routes, and shows how to use `useLocalePath` for navigation and `useSwitchLocalePath` to dynamically change the current route's locale. This setup is typical for creating internationalized Single Page Applications (SPAs) where the locale is managed via URL segments."},"warnings":[{"fix":"Carefully review the package's `peerDependencies` and install compatible versions. For Vue 2 projects needing Vue 3 Composition API features, ensure `@vue/composition-api` and `vue-i18n-bridge` are installed and correctly configured.","message":"The package has strict peer dependency requirements for `vue`, `vue-i18n`, and `vue-router`. Mismatched versions, especially between major versions (e.g., Vue 2 with Vue Router 4, or vue-i18n v8 with vue-i18n v9+ without `vue-i18n-bridge`), can lead to runtime errors or unexpected behavior. Always ensure your peer dependencies satisfy the `package.json` ranges.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to `vue-i18n-routing` version 1.1.4 or higher to benefit from fixes related to URL encoding and query parameter preservation when switching locales. Always test locale switching thoroughly after updates.","message":"When migrating between versions or frameworks, inconsistencies in URL encoding and query parameter handling during locale switching have been reported and fixed. This could lead to malformed URLs or lost state if not on a patched version.","severity":"gotcha","affected_versions":"<1.1.4"},{"fix":"Always import `createRouter` from `'vue-i18n-routing'` when setting up your router to ensure i18n functionalities are correctly integrated. Pass the `vue-router` instance and `vue-i18n` instance to it.","message":"The `createRouter` function exported by `vue-i18n-routing` is a wrapper around `vue-router`'s `createRouter`. Directly importing `createRouter` from `vue-router` will bypass the i18n integration provided by this package, leading to non-localized routes and navigation issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `legacy: false` is explicitly set when initializing `createI18n` for modern Vue 3 Composition API usage: `createI18n({ ..., legacy: false })`.","message":"The `legacy: false` option is crucial for `createI18n` from `vue-i18n` when using the Composition API. If `legacy` is set to `true` (or omitted, as the default can vary), Composition API hooks like `useI18n` will not function as expected, impacting `vue-i18n-routing`'s hooks which rely on it.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you call `app.use(i18n)` and `app.use(router)` (where `router` is the instance created by `vue-i18n-routing`) before `app.mount('#app')`.","cause":"The `vue-i18n` plugin or its routing wrapper was not properly installed into the Vue application instance before it was mounted.","error":"Error: [vue-i18n] Not installed. Make sure to call `app.use(i18n)` before `app.mount()`."},{"fix":"Verify that `createI18n` is called correctly and its instance is passed to `app.use()`. Also, ensure that any components using i18n hooks or global properties are within the `app`'s scope after `app.use(i18n)` has been called.","cause":"Attempting to access `i18n.locale` or related properties before `vue-i18n` has been fully initialized or provided to the component context.","error":"TypeError: Cannot read properties of undefined (reading 'locale')"},{"fix":"Confirm that your `vue-router` routes are correctly defined with a dynamic `:locale` segment at the root. For example, `{ path: '/:locale', children: [...] }`. Also, ensure the route name is consistent if using named routes with `localePath`.","cause":"A route with a locale prefix was accessed, but no matching route definition exists for the path or the locale parameter is not correctly handled.","error":"[vue-router] No match for current location: \"/en/non-existent\""}],"ecosystem":"npm"}