Translate your Vite and Vue website using Intlayer | Internationalisation (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

VideoCodeDemo

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-vite-vue-template.vercel.app

Open embedded page in fullscreen

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

   npx intlayer init --interactive
   

   the --interactive flag is optional. Use intlayer-cli init if you're an AI agent.

   This command will detect your environment and install the required packages. For example:

   bash

   Copy content

   Copy code

   Copy the code to the clipboard

   npm install intlayer vue-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

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

   • 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 localised 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 optimise 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 as they are included in 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

   Utilise Intlayer in Your Code

   To utilise Intlayer's internationalisation 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 internationalisation 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 level
   app.use(intlayer);
   
   // Mount the app
   app.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. 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.

• Destructuring syntax: The useIntlayer composable returns a Proxy with the content. This proxy can be destructured to access the content while maintaining reactivity.

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

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

// Get locale information and setLocale function
const { locale, availableLocales, setLocale } = useLocale();

// Track the selected locale with a ref
const selectedLocale = ref(locale.value);

// Update the locale when the selection changes
const changeLocale = () => setLocale(selectedLocale.value);

// Keep the selectedLocale in sync with the global locale
watch(
  () => locale.value,
  (newLocale) => {
    selectedLocale.value = newLocale;
  }
);
</script>

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

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

npm install vue-router
npx intlayer init

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 instance
export const router = createRouter({
  history: createWebHistory(),
  routes,
});

// Add navigation guard for locale handling
router.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();
});

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 app
app.use(router);

// Mount the app
app.mount("#app");

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

<template>
  <nav>
    <LocaleSwitcher />
  </nav>
  <RouterView />
</template>

<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>
  const { defineConfig } = require("vite"); const vue =
  require("@vitejs/plugin-vue"); const { intlayer, intlayerProxy } =
  require("vite-intlayer"); // https://vitejs.dev/config/ module.exports =
  defineConfig({ plugins: [vue(), intlayer(), intlayerProxy()], });
</template>

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

// Obtain Vue Router
const router = useRouter();

// Obtain locale information and setLocale function
const { locale, availableLocales, setLocale } = useLocale({
  onLocaleChange: (newLocale) => {
    // Obtain current route and create a localised URL
    const currentPath = router.currentRoute.value.fullPath;
    const localisedPath = getLocalizedUrl(currentPath, newLocale);

    // Navigate to the localised route without reloading the page
    router.push(localisedPath);
  },
});

// Track the selected locale with a ref
const selectedLocale = ref(locale.value);

// Update the locale when the selection changes
const changeLocale = () => {
  setLocale(selectedLocale.value);
};

// Keep the selectedLocale in sync with the global locale
watch(
  () => locale.value,
  (newLocale) => {
    selectedLocale.value = newLocale;
  }
);
</script>

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

import { watch } from "vue";
- **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 localised 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.

```js fileName="src/composables/useI18nHTMLAttributes.ts"
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;

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 behaviour is useful for several reasons:

      // Set the text direction (ltr for most languages, rtl for Arabic, Hebrew, etc.)
      document.documentElement.dir = getHTMLTextDir(newLocale);
    },
    { immediate: true }
  );
};

```vue fileName="src/components/Link.vue"
<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 external
const isExternalLink = computed(() => /^https?:\/\//.test(props.href || ""));

// Create a localised href for internal links
const 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:

```vue fileName="src/components/RouterLink.vue"
<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 localised to-prop for router-link
const localizedTo = computed(() => {
  if (typeof props.to === "string") {
    return getLocalizedUrl(props.to, locale.value);
  } else {
    // If 'to' is an object, localise 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:

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;

`

Run the extractor to transform your components and extract the content

npx intlayer extract

<Step number={10} title="Creating a Localised Link Component" isOptional={true}>

      document.documentElement.dir = getHTMLTextDir(newLocale);
    },
    { immediate: true }

);
};

<script setup lang="ts">
import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";

// Apply the HTML attributes based on the current locale
useI18nHTMLAttributes();
</script>

<template>
  <!-- Your app template -->
</template>

npm run build # Or npm run dev

</Step>

(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 take advantage 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 prevents you from 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 enhance 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 externalise your content using the CMS.

Frequently Asked Questions