Creation:2024-03-07Last update:2026-05-31

    Translate your Astro website using Intlayer | Internationalization (i18n)

    ide.intlayer.org

    Table of Contents

    Why Intlayer over alternatives?

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

    Intlayer is optimized to work perfectly with Astro by offering multilingual routing, sitemap, and all the features needed for scaling internationalization (i18n).

    Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps reduce your bundle and page sizes by up to 50%.

    Scoping your application's content facilitates maintenance for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is fully typed to ensure your content's accuracy.

    Co-locating content reduces the context needed by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a CLI to test for missing translations,LSP, MCP, and agent skills, to make the developer experience (DX) even smoother for AI agents.

    Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a compiler to automate content extraction, as well as a web platform to help translate in the background.

    Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.

    More than just an i18n solution, Intlayer provides an self-hosted visual editor and a full CMS to help you manage your multilingual content in real-time, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.

    Step-by-Step Guide to Set Up Intlayer in Astro

    See Application Template on GitHub.

    1. Install Dependencies

      Install the necessary packages using your package manager:

      bash
      npm install intlayer astro-intlayernpx intlayer init

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

      • astro-intlayer Includes the Astro integration 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. Configuration of your project

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

      intlayer.config.ts
      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. Integrate Intlayer in Your Astro Configuration

      Add the intlayer plugin into your configuration.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});
      The intlayer() Astro integration plugin is used to integrate Intlayer with Astro. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Astro application. Additionally, it provides aliases to optimize performance.

    4. Declare Your Content

      Create and manage your content declarations to store translations:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",    }),  },} satisfies Dictionary;export default appContent;
      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. Use your content in Astro

      You can consume dictionaries directly in .astro files using the core helpers exported by intlayer. You should also add SEO metadata like hreflang and canonical links to each page and include a locale switcher to allow users to change languages.

      src/pages/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  defaultLocale,  localeMap,  getHTMLTextDir,  type LocalesValues,} from "intlayer";import LocaleSwitcher from "../components/LocaleSwitcher.astro";// Get the current locale from the URL (e.g. /es/about -> 'es')const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;// Get the content for the 'app' dictionaryconst { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <!-- Canonical link: Tells search engines which is the primary version of this page -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang: Tell Google about all localized versions -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <!-- x-default: Fallback for users in unmatched languages -->    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <header>      <LocaleSwitcher />    </header>    <main>      <h1>{title}</h1>    </main>  </body></html>

    6. Localized routing

      Create a dynamic route segment to serve localized pages. To handle both the default locale (without prefix) and all other locales, use a rest parameter [...locale] in your page structure, for example src/pages/[...locale]/index.astro:

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getPrefix,  localeMap,  defaultLocale,  getHTMLTextDir,  type LocalesValues,} from "intlayer";import LocaleSwitcher from "../../components/LocaleSwitcher.astro";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { title } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{title}</title>    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <LocaleSwitcher />    <h1>{title}</h1>  </body></html>

      Note on Routing Configuration: The directory structure you use depends on the middleware.routing setting in your intlayer.config.ts:

      • prefix-no-default (default): Keeps the default locale at the root (no prefix) and prefixes others. Use [...locale] to catch all cases.
      • prefix-all: All URLs are prefixed with the locale. You can use standard [locale] if you don't need to handle the root separately.
      • search-param or no-prefix: No locale folder is needed. The locale is handled via search parameters or cookies.

    7. Add a Locale Switcher

      To allow users to switch between languages, you can create a LocaleSwitcher component. This component should display a list of all supported locales and link to the same page in each language.

      src/components/LocaleSwitcher.astro
      ---import {  locales,  getLocaleName,  getLocalizedUrl,  getLocaleFromPath,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);---<nav>  {    locales.map((localeItem) => (      <a        href={getLocalizedUrl(pathWithoutLocale, localeItem)}        data-locale={localeItem}        aria-current={localeItem === locale ? "page" : undefined}      >        {getLocaleName(localeItem)}      </a>    ))  }</nav><script>  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const locale = link.getAttribute("data-locale") as LocalesValues;      // Update the locale cookie      setLocaleInStorageClient(locale);    });  });</script><style>  nav {    display: flex;    gap: 1rem;  }  a[aria-current="page"] {    font-weight: bold;    text-decoration: underline;  }</style>

      Note on Persistence: Using setLocaleInStorageClient in the client-side script ensures that the user's language preference is saved in a cookie. This allows the Intlayer middleware to remember the choice and automatically redirect the user to their preferred language on future visits.

    8. Sitemap and Robots.txt

      Intlayer provides utilities to generate localized sitemaps and robots.txt files dynamically.

      Sitemap

      Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

      The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

      Create src/pages/sitemap.xml.ts to generate a sitemap that includes all your localized routes.

      src/pages/sitemap.xml.ts
      import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

      Robots.txt

      Create src/pages/robots.txt.ts to control search engine crawling.

      src/pages/robots.txt.ts
      import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

    9. Continue using your favorite framework

      Continue using your favorite framework to build your application.

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

      bash
      npx intlayer extract

    Configure TypeScript

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

    Autocompletion

    Translation error

    Ensure your TypeScript configuration includes the autogenerated types.

    tsconfig.json
    {  // ... 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:

    bash
    # 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.

    Tanstack Start Solid
    Astro and React