Getting Started Internationalizing (i18n) with Intlayer and Vite and Vue

This package is in development. See the issue for more information. Show your interest in Intlayer for Vue by liking the issue

What is Intlayer?

Intlayer is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications.

With Intlayer, you can:

• Easily manage translations using declarative dictionaries at the component level.
• Dynamically localize metadata, routes, and content.
• Ensure TypeScript support with autogenerated types, improving autocompletion and error detection.
• Benefit from advanced features, like dynamic locale detection and switching.

Step-by-Step Guide to Set Up Intlayer in a Vite and Vue Application

Step 1: Install Dependencies

Install the necessary packages using npm:

npm install intlayer vue-intlayer vite-intlayer

• intlayer

  The core package that provides internationalization tools for configuration management, translation, content declaration, transpilation, and CLI commands.

• vue-intlayer The package that integrates Intlayer with Vue application. It provides context providers and composables for Vue internationalization.

• vite-intlayer Includes the Vite plugin for integrating Intlayer with the Vite bundler, as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.

Step 2: Configuration of your project

Create a config file to configure the languages of your application:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Your other locales    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Through this configuration file, you can set up localized URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the configuration documentation.

Step 3: Integrate Intlayer in Your Vite Configuration

Add the intlayer plugin into your configuration.

import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin()],});

The intlayerPlugin() Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Vite application. Additionally, it provides aliases to optimize performance.

Step 4: Declare Your Content

Create and manage your content declarations to store translations:

import { t, type Dictionary } from "intlayer";const helloWorldContent = {  key: "helloworld",  content: {    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),    edit: t({      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",    }),    checkOut: t({ en: "Check out ", fr: "Vérifiez ", es: "Compruebe " }),    officialStarter: t({      en: ", the official Vue + Vite starter",      fr: ", le starter officiel Vue + Vite",      es: ", el starter oficial Vue + Vite",    }),    learnMore: t({      en: "Learn more about IDE Support for Vue in the ",      fr: "En savoir plus sur le support IDE pour Vue dans le ",      es: "Aprenda más sobre el soporte IDE para Vue en el ",    }),    vueDocs: t({      en: "Vue Docs Scaling up Guide",      fr: "Vue Docs Scaling up Guide",      es: "Vue Docs Scaling up Guide",    }),    readTheDocs: t({      en: "Click on the Vite and Vue logos to learn more",      fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",      es: "Haga clic en los logotipos de Vite y Vue para obtener más información",    }),  },} satisfies Dictionary;export default helloWorldContent;

Your content declarations can be defined anywhere in your application as soon they are included into the contentDir directory (by default, ./src). And match the content declaration file extension (by default, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}). For more details, refer to the content declaration documentation.

Step 5: Utilize Intlayer in Your Code

To utilize Intlayer's internationalization features throughout your Vue application, you first need to register the Intlayer singleton instance in your main file. This step is crucial as it provides the internationalization context to all components in your application, making translations accessible anywhere in your component tree.

import { createApp } from "vue";import { installIntlayer } from "vue-intlayer";import App from "./App.vue";import "./style.css";const app = createApp(App);// Inject the provider at the top levelinstallIntlayer(app);// Mount the appapp.mount("#app");

Access your content dictionaries throughout your application by creating a main Vue component and using the useIntlayer composables:

<script setup>import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const content = useIntlayer("helloworld");const count = ref(0);</script><template>  <h1>{{ msg }}</h1>  <div class="card">    <button type="button" @click="count++">      {{ content.count }}{{ count }}    </button>    <p v-html="content.edit.value"></p>  </div>  <p>    {{ content.checkOut }}    <a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"      >create-vue</a    >, {{ content.officialStarter }}  </p>  <p>    {{ content.learnMore }}    <a      href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"      target="_blank"      >{{ content.vueDocs }}</a    >.  </p>  <p class="read-the-docs">{{ content.readTheDocs }}</p></template>

If you want to use your content in an attribute, such as alt, title, href, aria-label, etc., you must call the value of the function with .value, like:

html

<img src="./logo.svg" :alt="content.image.value" />

(Optional) Step 6: Change the language of your content

To change the language of your content, you can use the setLocale function provided by the useLocale composable. This function allows you to set the locale of the application and update the content accordingly.

Create a component to switch between languages:

<template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup>import { ref, watch } from "vue";import { getLocaleName } from "intlayer";import { useLocale } from "vue-intlayer";// Get locale information and setLocale functionconst { locale, availableLocales, setLocale } = useLocale();// Track the selected locale with a refconst selectedLocale = ref(locale.value);// Update the locale when the selection changesconst changeLocale = () => setLocale(selectedLocale.value);// Keep the selectedLocale in sync with the global localewatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script>

Then, use this component in your App.vue:

<script setup>import { useIntlayer } from "vue-intlayer";import HelloWorld from "@components/HelloWorld.vue";import LocaleSwitcher from "@components/LocaleSwitcher.vue";import { ref, watch } from "vue";const content = useIntlayer("app"); // Create related intlayer declaration file</script><template>  <div>    <LocaleSwitcher />    <a href="https://vite.dev" target="_blank">      <img src="/vite.svg" class="logo" :alt="content.viteLogo" />    </a>    <a href="https://vuejs.org/" target="_blank">      <img src="./assets/vue.svg" class="logo vue" :alt="content.vueLogo" />    </a>  </div>  <HelloWorld :msg="content.title" /></template>

(Optional) Step 7: Add localized Routing to your application

Adding localized routing in a Vue application typically involves using Vue Router with locale prefixes. This makes unique routes for each language, which is useful for SEO and SEO-friendly URLs.

Example:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

First, install Vue Router:

npm install intlayer vue-router

Then, create a router configuration that handles locale-based routing:

import {  configuration,  getPathWithoutLocale,  localeFlatMap,  type Locales,} from 'intlayer';import { createIntlayerClient } from 'vue-intlayer';import { createRouter, createWebHistory } from 'vue-router';import HomeView from './views/home/HomeView.vue';import RootView from './views/root/Root.vue';// Get internationalization configurationconst { internationalization, middleware } = configuration;const { defaultLocale } = internationalization;/** * Declare the routes with locale-specific paths and metadata. */const routes = localeFlatMap((localizedData) => [  {    path: `${localizedData.urlPrefix}/`,    name: `Root-${localizedData.locale}`,    component: RootView,    meta: {      locale: localizedData.locale,    },  },  {    path: `${localizedData.urlPrefix}/home`,    name: `Home-${localizedData.locale}`,    component: HomeView,    meta: {      locale: localizedData.locale,    },  },]);// Create the router instanceexport const router = createRouter({  history: createWebHistory(),  routes,});// Add navigation guard for locale handlingrouter.beforeEach((to, _from, next) => {  const client = createIntlayerClient();  const metaLocale = to.meta.locale as Locales | undefined;  if (metaLocale) {    // Reuse the locale defined in the route meta    client.setLocale(metaLocale);    next();  } else {    // Fallback: no locale in meta, possibly unmatched route    // Optional: handle 404 or redirect to default locale    client.setLocale(defaultLocale);    if (middleware.prefixDefault) {      next(`/${defaultLocale}${getPathWithoutLocale(to.path)}`);    } else {      next(getPathWithoutLocale(to.path));    }  }});

The name is used to identify the route in the router. It should be unique across all routes to avoid conflicts and ensure proper navigation and linking.

Then, register the router in your main.js file:

import { createApp } from "vue";import App from "./App.vue";import { router } from "./router";import "./style.css";const app = createApp(App);// Add the router to the appapp.use(router);// Mount the appapp.mount("#app");

Then update your App.vue file to render the RouterView component. This component will display the matched component for the current route.

<script setup>import LocaleSwitcher from "@components/LocaleSwitcher.vue";</script><template>  <nav>    <LocaleSwitcher />  </nav>  <RouterView /></template>

In parallel, you can also use the intLayerMiddlewarePlugin to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.

import { defineConfig } from "vite";import vue from "@vitejs/plugin-vue";import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],});

(Optional) Step 8: Change the URL when the locale changes

To automatically update the URL when the user changes the language, you can modify the LocaleSwitcher component to use Vue Router:

<template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup>import { ref, watch } from "vue";import { useRouter } from "vue-router";import { Locales, getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Get Vue Routerconst router = useRouter();// Get locale information and setLocale functionconst { locale, availableLocales, setLocale } = useLocale({  onLocaleChange: (newLocale) => {    // Get current route and create a localized URL    const currentPath = router.currentRoute.value.fullPath;    const localizedPath = getLocalizedUrl(currentPath, newLocale);    // Navigate to the localized route without reloading the page    router.push(localizedPath);  },});// Track the selected locale with a refconst selectedLocale = ref(locale.value);// Update the locale when the selection changesconst changeLocale = () => {  setLocale(selectedLocale.value);};// Keep the selectedLocale in sync with the global localewatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script>

Tip: For better SEO and accessibility, use tags as <a href="/fr/home" hreflang="fr"> to link to localized pages, as shown in Step 10. This allows search engines to discover and index language-specific URLs properly. To preserve SPA behavior, you can prevent the default navigation with @click.prevent, change the locale using useLocale, and programmatically navigate using Vue Router.

<ol class="divide-text/20 divide-y divide-dashed overflow-y-auto p-1">  <li>    <a      hreflang="x-default"      aria-label="Switch to English"      target="_self"      aria-current="page"      href="/doc/get-started"    >      <div>        <div><span dir="ltr" lang="en">English</span><span>English</span></div>        <span>EN</span>      </div>    </a>  </li>  <li>    <a      hreflang="es"      aria-label="Switch to Spanish"      target="_self"      href="/es/doc/get-started"    >      <div>        <span dir="ltr" lang="es">Español</span><span>Spanish</span>        <span>ES</span>      </div>    </a>  </li></ol>

(Optional) Step 9: Switch the HTML Language and Direction Attributes

When your application supports multiple languages, it's crucial to update the <html> tag's lang and dir attributes to match the current locale. Doing so ensures:

• Accessibility: Screen readers and assistive technologies rely on the correct lang attribute to pronounce and interpret content accurately.
• Text Rendering: The dir (direction) attribute ensures that text is rendered in the proper order (e.g., left-to-right for English, right-to-left for Arabic or Hebrew), which is essential for readability.
• SEO: Search engines use the lang attribute to determine the language of your page, helping to serve the right localized content in search results.

By updating these attributes dynamically when the locale changes, you guarantee a consistent and accessible experience for users across all supported languages.

import { watch } from "vue";import { useLocale } from "vue-intlayer";import { getHTMLTextDir } from "intlayer";/** * Composable that updates the HTML <html> element's `lang` and `dir` attributes * based on the current locale. * * @example * // In your App.vue or a global component * import { useI18nHTMLAttributes } from './composables/useI18nHTMLAttributes' * * useI18nHTMLAttributes() */export function useI18nHTMLAttributes() {  const { locale } = useLocale();  // Update the HTML attributes whenever the locale changes  watch(    () => locale.value,    (newLocale) => {      if (!newLocale) return;      // Update the language attribute      document.documentElement.lang = newLocale;      // Set the text direction (ltr for most languages, rtl for Arabic, Hebrew, etc.)      document.documentElement.dir = getHTMLTextDir(newLocale);    },    { immediate: true }  );}

Use this composable in your App.vue or a global component:

<script setup>import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";// Apply the HTML attributes based on the current localeuseI18nHTMLAttributes();</script><template>  <!-- Your app template --></template>

(Optional) Step 10: Creating a Localized Link Component

To ensure that your application’s navigation respects the current locale, you can create a custom Link component. This component automatically prefixes internal URLs with the current language, so that. For example, when a French-speaking user clicks on a link to the "About" page, they are redirected to /fr/about instead of /about.

This behavior is useful for several reasons:

• SEO and User Experience: Localized URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
• Consistency: By using a localized link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
• Maintainability: Centralizing the localization logic in a single component simplifies the management of URLs, making your codebase easier to maintain and extend as your application grows.

<template>  <a :href="localizedHref" v-bind="$attrs">    <slot></slot>  </a></template><script setup>import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  href: {    type: String,    required: true,  },});const { locale } = useLocale();// Check if the link is externalconst isExternalLink = computed(() => /^https?:///.test(props.href || ""));// Create a localized href for internal linksconst localizedHref = computed(() =>  isExternalLink.value ? props.href : getLocalizedUrl(props.href, locale.value));</script>

For use with Vue Router, create a router-specific version:

<template>  <router-link :to="localizedTo" v-bind="$attrs">    <slot></slot>  </router-link></template><script setup>import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: [String, Object],    required: true,  },});const { locale } = useLocale();// Create localized to-prop for router-linkconst localizedTo = computed(() => {  if (typeof props.to === "string") {    return getLocalizedUrl(props.to, locale.value);  } else {    // If 'to' is an object, localize the path property    return {      ...props.to,      path: getLocalizedUrl(props.to.path ?? "/", locale.value),    };  }});</script>

Use these components in your application:

<template>  <div>    <!-- Vue router  -->    <RouterLink to="/">Root</RouterLink>    <RouterLink to="/home">Home</RouterLink>    <!-- Other -->    <Link href="/">Root</Link>    <Link href="/home">Home</Link>  </div></template><script setup>import Link from "@components/Link.vue";import RouterLink from "@components/RouterLink.vue";</script>

Configure TypeScript

Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

Ensure your TypeScript configuration includes the autogenerated types.

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

Git Configuration

It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

To do this, you can add the following instructions to your .gitignore file:

# Ignore the files generated by Intlayer.intlayer

VS Code Extension

To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

Install from the VS Code Marketplace

This extension provides:

• Autocompletion for translation keys.
• Real-time error detection for missing translations.
• Inline previews of translated content.
• Quick actions to easily create and update translations.

For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

Go Further

To go further, you can implement the visual editor or externalize your content using the CMS.