Translate your Vite and Vue website using Intlayer | Internationalization (i18n)

Table of Contents

Why Intlayer over alternatives?

Compared to main solutions like vue-i18n or i18next, Intlayer is a solution that comes with integrated optimizations such as:

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

See Application Template on GitHub.

1. 1

   Install Dependencies

   Install the necessary packages using npm:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer vue-intlayernpm install vite-intlayer --save-devnpx intlayer init

   • 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.

2. 2

   Configuration of your project

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

   intlayer.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   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.

3. 3

   Integrate Intlayer in Your Vite Configuration

   Add the intlayer plugin into your configuration.

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

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

   The intlayer() 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.

4. 4

   Declare Your Content

   Create and manage your content declarations to store translations:

   src/helloWorld.content.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   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,cjs,md,mdx,yaml,yml}).

   For more details, refer to the content declaration documentation.

5. 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.

   Copy content

   Copy code

   Copy the code to the clipboard

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

   You can also call installIntlayer(app) directly as a function if you prefer:

   javascript

   Copy content

   Copy code

   Copy the code to the clipboard

   import { intlayer } from "vue-intlayer";app.use(intlayer);

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

   src/HelloWord.vue

   Copy content

   Copy code

   Copy the code to the clipboard

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

   If your app already exists, you can use the Intlayer Compiler, as well as the extract command, to transform thousands of components in a second.

   Accessing Content in Intlayer

   Intlayer offers different APIs to access your content:

   • Component-based syntax (recommended): Use the <myContent />, or <Component :is="myContent" /> syntax to render content as an Intlayer Node. You can also customize the rendering by using the .use() method: <Component :is="myContent.use({ b: (props) => h('strong', props) })" />. This integrates seamlessly with the Visual Editor and CMS.

   • String-based syntax: Use {{ myContent }} to render the content as plain text, without Visual Editor support.

   • Raw HTML syntax: Use <div v-html="myContent" /> to render the content as raw HTML, without Visual Editor support.

   • Destructuration syntax: The useIntlayer composable returns an Proxy with the content. This proxy can be destructured to access the content while keeping the reactivity.

     • Use const content = useIntlayer("myContent"); And {{ content.myContent }} / <content.myContent />.
     • Or use const { myContent } = useIntlayer("myContent"); And {{ myContent}} / <myContent/> to destructure the content.
6. 6

   Change the language of your content

   Optional

   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:

   src/components/LocaleSwitcher.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { getLocaleName } from "intlayer";import { ref, watch } from "vue";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><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>

   Then, use this component in your App.vue:

   src/App.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">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>

7. 7

   Add localized Routing to your application

   Optional

   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:

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

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

   First, install Vue Router:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install vue-routernpx intlayer init

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

   src/router/index.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import {  localeFlatMap,  type Locale,} 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';/** * Declare the routes with locale-specific paths and metadata. */const routes = localeFlatMap(({ urlPrefix, locale }) => [  {    path: `${urlPrefix}/`,    name: `Root-${locale}`,    component: RootView,    meta: {      locale,    },  },  {    path: `${urlPrefix}/home`,    name: `Home-${locale}`,    component: HomeView,    meta: {      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 Locale;  // Reuse the locale defined in the route meta  client.setLocale(metaLocale);  next();});

   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:

   src/main.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   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.

   src/App.vue

   Copy content

   Copy code

   Copy the code to the clipboard

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

   In parallel, you can also use the intlayerProxy 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.

   Note that to use the intlayerProxy in production, you need to switch the vite-intlayer package from devDependencies to dependencies.

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

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

8. 8

   Change the URL when the locale changes

   Optional

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

   src/components/LocaleSwitcher.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { Locales, getLocaleName, getLocalizedUrl } from "intlayer";import { ref, watch } from "vue";import { useLocale } from "vue-intlayer";import { useRouter } from "vue-router";// 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><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>

   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.

   html

   Copy content

   Copy code

   Copy the code to the clipboard

   <ol>  <li>    <a      hreflang="x-default"      aria-label="Switch to English"      target="_self"      aria-current="page"      href="/doc/get-started"    >      <div>        <span dir="ltr" lang="en">English</span>        <span>English</span>        <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>

9. 9

   Switch the HTML Language and Direction Attributes

   Optional

   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.

   src/composables/useI18nHTMLAttributes.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   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 const 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:

   src/App.vue

   Copy content

   Copy code

   Copy the code to the clipboard

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

10. 10

    Creating a Localized Link Component

    Optional

    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.

    src/components/Link.vue

    Copy content

    Copy code

    Copy the code to the clipboard

    <script setup lang="ts">import { getLocalizedUrl } from "intlayer";import { computed } from "vue";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><template>  <a :href="localizedHref" v-bind="$attrs">    <slot />  </a></template>

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

    src/components/RouterLink.vue

    Copy content

    Copy code

    Copy the code to the clipboard

    <script setup lang="ts">import { getLocalizedUrl } from "intlayer";import { computed } from "vue";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><template>  <router-link :to="localizedTo" v-bind="$attrs">    <slot />  </router-link></template>

    Use these components in your application:

    src/App.vue

    Copy content

    Copy code

    Copy the code to the clipboard

    <script setup lang="ts">import Link from "@components/Link.vue";import RouterLink from "@components/RouterLink.vue";</script><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>

11. 11

    Extract the content of your components

    Optional

    If you have an existing codebase, transforming thousands of files can be time-consuming.

    To ease this process, Intlayer propose a compiler / extractor to transform your components and extract the content.

    To set it up, you can add a compiler section in your intlayer.config.ts file:

    intlayer.config.ts

    Copy content

    Copy code

    Copy the code to the clipboard

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Rest of your config
      compiler: {
        /**
         * Indicates if the compiler should be enabled.
         */
        enabled: true,
    
        /**
         * Defines the output files path
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indicates if the components should be saved after being transformed.
         *
         * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
         *
         * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
         */
        saveComponents: false,
    
        /**
         * Dictionary key prefix
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;

    Extract commandBabel compiler

    Run the extractor to transform your components and extract the content

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npx intlayer extract

    Update your vite.config.ts to include the intlayerCompiler plugin:

    vite.config.ts

    Copy content

    Copy code

    Copy the code to the clipboard

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Adds the compiler plugin ],});

    bash

    Copy content

    Copy code

    Copy the code to the clipboard

    npm run build # Or npm run dev

(Optional) Sitemap and robots.txt (build-time)

Intlayer includes formatters such as generateSitemap and getMultilingualUrls that produce crawler-ready multilingual sitemap.xml and robots.txt output you can write into your project’s public/ folder. In practice you run a small Node script before Vite (for example predev / prebuild npm hooks) so those files exist when you build or serve the app.

Sitemap

Intlayer’s sitemap generator respects your locale setup and includes the usual metadata for crawlers.

The generated sitemap supports the xhtml:link namespace (hreflang XML extensions). Unlike basic generators that only emit flat URLs, Intlayer wires bidirectional links between every localized variant of each page (for example /about, /fr/about, or /about?lang=fr, depending on your routing mode), which helps search engines relate localized URLs.

Robots.txt

Use getMultilingualUrls so Disallow entries cover every localized spelling of sensitive paths.

1. Add generate-seo.mjs at the project root

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

intlayer must be installed so the script can import it. Set SITE_URL in the environment for production (for example in CI).

Prefer generate-seo.mjs for Node ESM. If you use generate-seo.js instead, ensure "type": "module" is set in package.json, or run Node with ESM enabled.

2. Run the script before Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Adjust if you use pnpm or yarn. You can also invoke the same script from CI or another step if that fits your workflow.

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.