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

Table of Contents

Why Intlayer over alternatives?

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

Step-by-Step Guide to Set Up Intlayer in a Nuxt 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 --save-dev nuxt-intlayernpx 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 the composables for the Vue components.

   • nuxt-intlayer The Nuxt module that integrates Intlayer with Nuxt applications. It provides automatic setup, middleware for locale detection, cookie management, and 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 Nuxt Configuration

   Add the intlayer module to your Nuxt configuration:

   nuxt.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Your existing Nuxt configuration  modules: ["nuxt-intlayer"],});

   The nuxt-intlayer module automatically handles the integration of Intlayer with Nuxt. It sets up the content declaration building, monitors files in development mode, provides middleware for locale detection, and manages localized routing.

4. 4

   Declare Your Content

   Create and manage your content declarations to store translations:

   Your content declarations can be defined anywhere in your application as long 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

   Utilize Intlayer in Your Code

   Access your content dictionaries throughout your Nuxt application using the useIntlayer composable:

   components/HelloWorld.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,  nuxtIntlayer,  learnMore,  nuxtDocs,  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://nuxt.com/docs/getting-started/introduction" target="_blank"      >Nuxt</a    >, <nuxtIntlayer />  </p>  <p>    <learnMore />    <a href="https://nuxt.com" target="_blank"><nuxtDocs /></a>.  </p>  <p class="read-the-docs"><readTheDocs /></p>  <p class="read-the-docs">{{ readTheDocs }}</p></template>

   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.

   • 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 using NuxtLink. Using links instead of buttons for locale switching is a best practice for SEO and page discoverability, as it allows search engines to crawl and index all localized versions of your pages:

   components/LocaleSwitcher.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";// Nuxt auto-imports useRouteconst route = useRoute();const { locale, availableLocales, setLocale } = useLocale();</script><template>  <nav class="locale-switcher">    <NuxtLink      v-for="localeEl in availableLocales"      :key="localeEl"      :to="getLocalizedUrl(route.fullPath, localeEl)"      class="locale-link"      :class="{ 'active-locale': localeEl === locale }"      @click="setLocale(localeEl)"    >      {{ getLocaleName(localeEl) }}    </NuxtLink>  </nav></template>

   Using NuxtLink with proper href attributes (via getLocalizedUrl) ensures that search engines can discover all language variants of your pages. This is preferable to JavaScript-only locale switching, which search engine crawlers may not follow.

   Then, set up your app.vue to use layouts:

   app.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <template>  <NuxtLayout>    <NuxtPage />  </NuxtLayout></template>

7. 7

   Add localized Routing to your application

   Optional

   Nuxt automatically handles localized routing when using the nuxt-intlayer module. This creates routes for each language automatically based on your pages directory structure.

   Example:

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

   pages/├── index.vue          → /, /fr, /es├── about.vue          → /about, /fr/about, /es/about└── contact/    └── index.vue      → /contact, /fr/contact, /es/contact

   To create localized pages, simply create your Vue files in the pages/ directory. Here are two example pages:

   Home page (pages/index.vue):

   pages/index.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("home-page");useHead({  title: content.metaTitle.raw,  meta: [    {      name: "description",      content: content.metaDescription.raw,    },  ],});</script><template>  <h1><content.title /></h1></template>

   About page (pages/about.vue):

   pages/about.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Use .raw for primitive string access  meta: [    {      name: "description",      content: content.metaDescription.raw, // Use .raw for primitive string access    },  ],});</script><template>  <h1><content.title /></h1></template>

   Note: useHead is auto-imported in Nuxt. You can access content values using either .value (reactive) or .raw (primitive string) depending on your needs.

   The nuxt-intlayer module will automatically:

   • Detect the user's preferred locale
   • Handle locale switching via URL
   • Set the appropriate <html lang=""> attribute
   • Manage locale cookies
   • Redirect users to the appropriate localized URL
8. 8

   Creating a Localized Link Component

   Optional

   To ensure that your application's navigation respects the current locale, you can create a custom Links component. This component automatically prefixes internal URLs with the current language, which is essential for SEO and page discoverability.

   components/Links.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";interface Props {  href: string;  locale?: string;}const props = defineProps<Props>();const { locale: currentLocale } = useLocale();// Compute the final pathconst finalPath = computed(() => {  // 1. Check if the link is external  const isExternal = /^https?:\/\//.test(props.href || "");  // 2. If external, return as is (NuxtLink handles the <a> tag generation)  if (isExternal) return props.href;  // 3. If internal, localize the URL  const targetLocale = props.locale || currentLocale.value;  return getLocalizedUrl(props.href, targetLocale);});</script><template>  <NuxtLink :to="finalPath" v-bind="$attrs">    <slot />  </NuxtLink></template>

   Then use this component throughout your application:

   layouts/default.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Home</Links>    <Links href="/about">About</Links>  </div></template>

   By using NuxtLink with localized paths, you ensure that:

   • Search engines can crawl and index all language versions of your pages
   • Users can share localized URLs directly
   • Browser history works correctly with locale-prefixed URLs

9. 9

   Handle Metadata and SEO

   Optional

   Nuxt provides excellent SEO capabilities via the useHead composable (auto-imported). You can use Intlayer to handle localized metadata using the .raw or .value accessor to get the primitive string value:

   pages/about.vue

   Copy content

   Copy code

   Copy the code to the clipboard

   <script setup lang="ts">import { useIntlayer } from "vue-intlayer";// useHead is auto-imported in Nuxtconst content = useIntlayer("about-page");useHead({  title: content.metaTitle.raw, // Use .raw for primitive string access  meta: [    {      name: "description",      content: content.metaDescription.raw, // Use .raw for primitive string access    },  ],});</script><template>  <h1><content.title /></h1></template>

   Alternatively, you can use the import { getIntlayer } from "intlayer" function to get the content without Vue reactivity.

   Accessing content values:

   • Use .raw to get the primitive string value (non-reactive)
   • Use .value to get the reactive value
   • Use <content.key /> component syntax for Visual Editor support

   Create the corresponding content declaration:

   pages/about-page.content.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { t, type Dictionary } from "intlayer";
   
   const aboutPageContent = {
     key: "about-page",
     content: {
       metaTitle: t({
         en: "About Us - My Company",
         fr: "À Propos - Ma Société",
         es: "Acerca de Nosotros - Mi Empresa",
       }),
       metaDescription: t({
         en: "Learn more about our company and our mission",
         fr: "En savoir plus sur notre société et notre mission",
         es: "Conozca más sobre nuestra empresa y nuestra misión",
       }),
       title: t({
         en: "About Us",
         fr: "À Propos",
         es: "Acerca de Nosotros",
       }),
     },
   } satisfies Dictionary;
   
   export default aboutPageContent;

(Optional) Step 6b: Create a Layout with Navigation

Nuxt layouts allow you to define a common structure for your pages. Create a default layout that includes the locale switcher and navigation:

<script setup lang="ts">import Links from "~/components/Links.vue";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <slot />    </main>    <Links href="/">Home</Links>    <Links href="/about">About</Links>  </div></template>

The Links component (shown below) ensures that internal navigation links are automatically localized.

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.