Registry / web-framework / vue-i18n-routing

vue-i18n-routing

JSON →
library1.2.0jsnpmunverified

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.

npm install vue-i18n-routing
INSTALL
IMPORT
SIG · VUE-I18N-ROUTING
V
vue-i18n-routing
web-frameworkjavascriptv1.2.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRouter
✓ import { createRouter } from 'vue-i18n-routing'
✗ import { createRouter } from 'vue-router' // For i18n-aware routing, use vue-i18n-routing's wrapper
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.
useLocalePath
✓ import { useLocalePath } from 'vue-i18n-routing'
✗ import { useLocalePath } from 'vue-i18n'
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.
useSwitchLocalePath
✓ import { useSwitchLocalePath } from 'vue-i18n-routing'
✗ import { useSwitchLocalePath } from 'vue-i18n'
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.

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.

import { createApp } from 'vue'; import { createRouter, createWebHistory } from 'vue-router'; import { createI18n } from 'vue-i18n'; import { createRouter as createI18nRouter, useLocalePath, useSwitchLocalePath } from 'vue-i18n-routing'; // --- i18n setup --- const messages = { en: { welcome: 'Welcome to our multi-language app!', about: 'About Us', home: 'Home', greeting: 'Hello from home!', switch_locale: 'Switch to {locale}' }, fr: { welcome: 'Bienvenue dans notre application multilingue !', about: 'À Propos', home: 'Accueil', greeting: 'Bonjour de l\'accueil !', switch_locale: 'Passer au {locale}' } }; const i18n = createI18n({ locale: 'en', fallbackLocale: 'en', messages, legacy: false, // Must be false for Composition API globalInjection: true }); // --- Vue Router setup --- const routes = [ { path: '/:locale', component: { template: '<router-view />' }, // A wrapper for localized routes children: [ { path: '', name: 'home', component: { template: ` <div> <h1>{{ $t('greeting') }}</h1> <router-link :to="localePath('about')">{{ $t('about') }}</router-link> <p> <button @click="switchLocale('fr')">{{ $t('switch_locale', { locale: 'fr' }) }}</button> <button @click="switchLocale('en')">{{ $t('switch_locale', { locale: 'en' }) }}</button> </p> </div> ` } }, { path: 'about', name: 'about', component: { template: ` <div> <h1>{{ $t('about') }}</h1> <p>{{ $t('welcome') }}</p> <router-link :to="localePath('home')">{{ $t('home') }}</router-link> </div> ` } } ] } ]; const router = createI18nRouter({ router: createRouter({ history: createWebHistory(), routes }), i18n, defaultLocale: 'en' // Specify default locale to omit from path }); // --- Vue App setup --- const app = createApp({ setup() { const localePath = useLocalePath(); const switchLocalePath = useSwitchLocalePath(); const switchLocale = (locale) => { router.push(switchLocalePath(locale)); }; return { localePath, switchLocale }; } }); app.use(i18n); app.use(router); app.mount('#app');
Debug
Known issues
breakingThe 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.
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.
affects: >=1.0.0
gotchaWhen 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.
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.
affects: <1.1.4
gotchaThe `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.
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.
affects: >=1.0.0
gotchaThe `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.
fix
Ensure `legacy: false` is explicitly set when initializing `createI18n` for modern Vue 3 Composition API usage: `createI18n({ ..., legacy: false })`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: [vue-i18n] Not installed. Make sure to call `app.use(i18n)` before `app.mount()`.
The `vue-i18n` plugin or its routing wrapper was not properly installed into the Vue application instance before it was mounted.
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')`.
TypeError: Cannot read properties of undefined (reading 'locale')
Attempting to access `i18n.locale` or related properties before `vue-i18n` has been fully initialized or provided to the component context.
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.
[vue-router] No match for current location: "/en/non-existent"
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.
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`.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies
@vue/composition-apioptionalRequired for Vue 2 compatibility to use Composition API features.
vuerequiredCore Vue.js library. Supports Vue 2.6.14+ and Vue 3.2.0+.
vue-i18nrequiredThe primary internationalization library this package extends. Supports vue-i18n 8.26.1+ or 9.2.0+.
vue-i18n-bridgeoptionalEnables Vue 3 Composition API usage with Vue 2, crucial for cross-version compatibility.
vue-routerrequiredThe core routing library this package enhances. Supports vue-router 3.5.3+ or 4.0.0+.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources