Language routing and URL localization made easy.

Built on top of 🚦 Vue Router and 🌐 Vue I18n.

You can play with demo at Code Sandbox.

⏳ Asynchronous translation loading

🎭 URL localization

🏛️ Default language (no language prefix in URL)

👶 Supports variables and children in routes

🚗 🚲 Supports both history and hash mode

📚 Sets user-preferred language on first visit

📝 Loads last used language when visiting site again

⏩ No extra router setup

This version is compatible with Vue 3. If you need Vue 2 compatible version, please check out v1 of this project.

If you are migrating from Vue 2, you need to adjust your router.js and main.js files. See points 4 and 5.

The easiest way to install Language Router is using Vue CLI plugin for Language Router. The plugin will modify your router file, setup translation files and more.

Use this command to add Language Router to your Vue.js project:

$ vue add lang-router

$ npm i vue-lang-router@next

Note: This example uses Czech and English translations.

Example file structure:

src
└── lang
    └── translations
        ├── cs.json
        ├── en.json
        └── index.js

Create JSON files for all desired languages and reference them in index.js. Translations are loaded on demand.

/*  src/lang/translations/en.json  */

{
  "hello": "Hello!",
  "about": {
    "example": "This is an About page."
  }
}

/*  src/lang/translations/cs.json  */

{
  "hello": "Ahoj!",
  "about": {
    "example": "Tohle je stránka O nás."
  }
}

/*  src/lang/translations/index.js  */

export default {
  en: {
    name: 'English',
    load: () => { return import('./en.json'); },
  },
  cs: {
    name: 'Česky',
    load: () => { return import('./cs.json'); },
  },
};

In case you do not want to load translations asynchronously, you can provide messages object with translations instead of load function. For example:

export default {
  en: {
    name: 'English',
    messages: {
      hello: 'Hello!',
    },
  },
};

Note: Localized URLs are optional.

Example file structure:

src
└── lang
    └── localized-urls
        ├── cs.json
        └── index.js

Create JSON files for all desired languages and import them in index.js. Localized URLs need to be imported before router instantiation.

/*  src/lang/localized-urls/cs.json  */

{
  "about": "o-nas"
}

/*  src/lang/localized-urls/index.js  */

import cs from './cs.json';

export default { cs };

Language router will parse any given path and attempt to localize its segments based on this configuration. If no match is found, the original path segment is retained.

• Import createLangRouter and use it instead of createRouter.
• Import translations and localized URLs.
• Create router using createLangRouter. Pass in the language options and router options. The router options are exactly the same as if using createRouter.

/*  src/router/index.js  */

import { createWebHistory } from 'vue-router';
import { createLangRouter } from 'vue-lang-router';

import translations from '../lang/translations';
import localizedURLs from '../lang/localized-urls';

const routes = [ /* Your routes here */ ];

const langRouterOptions = {
	defaultLanguage: 'en',
	translations,
	localizedURLs,
};
const routerOptions = {
	routes,
	history: createWebHistory(process.env.BASE_URL),
};

const router = createLangRouter(langRouterOptions, routerOptions);

export default router;

Import i18n and use it in your Vue app.

/*  src/main.js  */

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { i18n } from 'vue-lang-router';

createApp(App).use(router).use(i18n).mount('#app');

To use any translated string, use $t('stringName') in your code. For more information check out Vue I18n.

Use <localized-link> component. It localizes given router path based on current language. It's a simple, yet powerful component, which takes a hassle out of generating proper links on your site.

It accepts the same options as <router-link>.

<localized-link to="/user/john-smith">John Smith</localized-link>

The above code will generate a link with href value depending on various factors. Here are a few examples:

/*
Default language: "en"
Current language: "en"
Localized URLs "en": {}
Current URL: /
*/

href="/user/john-smith"


/*
Default language: "en"
Current language: "en"
Localized URLs "en": { "user": "u" }
Current URL: /en/example
*/

href="/en/u/john-smith"


/*
Default language: "en"
Current language: "cs"
Localized URLs "cs": { "user": "uzivatel" }
Current URL: /
*/

href="/cs/uzivatel/john-smith"

Use <language-switcher> component for this. The component will loop over all available languages and generate links array with properties, which you can use to create your own menu.

The wrapper element will have router-language-switcher class.

<language-switcher v-slot="{ links }">
  <router-link :to="link.url" v-for="link in links" :key="link.langIndex">
    <img :src="require(`@/assets/${link.langIndex}.png`)" alt="" />
    <span>{{ link.langName }}</span>
  </router-link>
</language-switcher>

<language-switcher v-slot="{ links }" tag="ul" active-class="my-custom-class">
  <li :class="link.activeClass" v-for="link in links" :key="link.langIndex">
    <a :href="link.url">{{ link.langIndex }}</a>
  </li>
</language-switcher>

• url : The localized path to the current/specified page in iterated language.
• langIndex : The index of the iterated language provided in translations.
• langName : The name of the iterated language provided in translations.
• activeClass : Returns the active class when iterated language equals current language, otherwise empty.

• tag : Use this attribute to specify which tag should be used as a wrapper element. The default is div.
• url : Provides a specific path to generate translation links for. If omitted, current path is used.
• active-class : Defines the name of class to provide when language of the link equals current language. The default is router-active-language.

In case you'd like to pass in custom vue-i18n options, you can do so using i18nOptions property, for example:

/*  src/router/index.js  */

const langRouterOptions = {
	defaultLanguage: 'en',
	translations,
	localizedURLs,
  i18nOptions: {
    datetimeFormats: { ... },
    pluralizationRules: { ... },
  },
};