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

    Translate your Astro site with Intlayer | Internationalisation (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 Configure Intlayer in Astro

    Check out the application template on GitHub.

    1. Install Dependencies

      Install the necessary packages using your preferred package manager:

      bash
      npm install intlayer astro-intlayer# Optional: If you add support for React islandsnpm install react react-dom react-intlayer @astrojs/react

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

      • astro-intlayer Includes the Astro integration plugin to link Intlayer with the Vite bundler, as well as the middleware to detect the user's preferred language, manage cookies, and handle URL redirects.

    2. Configure Your Project

      Create a configuration file to define your application's languages:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.ENGLISH_UNITED_KINGDOM,      // Your other languages    ],    defaultLocale: Locales.ENGLISH,  },};export default config;
      Through this configuration file, you can configure localised URLs, middleware redirects, cookie names, location and extensions of content declarations, disable Intlayer logs in the console, and more. For a full list of available parameters, refer to the configuration documentation.

    3. Integrate Intlayer into Your Astro Configuration

      Add the intlayer plugin to your Astro 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() integration plugin is used to integrate Intlayer with Astro. It ensures the generation of the content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Astro application and provides aliases to optimise 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",      "en-GB": "Hello World",    }),  },} satisfies Dictionary;export default appContent;
      Content declarations can be defined anywhere in your application, as long as they are included in the contentDir (by default ./src) and match the content declaration file extension (by default .content.{json,ts,tsx,js,jsx,mjs,cjs}).
      For more information, refer to the content declaration documentation.

    5. Using Content in Astro

      You can consume the dictionaries directly in your .astro files using the core helpers exported from intlayer.

      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. Localised Routing

      Create dynamic route segments to serve localised pages (e.g., src/pages/[locale]/index.astro):

      src/pages/[locale]/index.astro
      ---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

      The Astro integration adds a Vite middleware that helps with language-sensitive routing and environment definitions during development. You can also create links across languages using your own logic or intlayer tools like getLocalizedUrl.

    7. Continue Using Your Favourite Frameworks

      Keep building your application using the framework of your choice.

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

    TypeScript Configuration

    Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust.

    Autocompletion

    Translation Error

    Ensure your TypeScript configuration includes the autogenerated types.

    tsconfig.json
    {  // ... your existing TypeScript configuration  "include": [    // ... your existing TypeScript configuration    ".intlayer/**/*.ts", // Include autogenerated types  ],}

    Git Configuration

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

    To do this, 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.

    Installation from the VS Code Marketplace

    This extension provides:

    • Autocompletion for translation keys.
    • Real-time error detection for missing translations.
    • Inline preview of translated content.
    • Quick actions for easily creating and updating translations.

    For more information on using the extension, refer to the VS Code Extension documentation.

    Deepen Your Knowledge

    If you want to learn more, you can also implement the Visual Editor or use the CMS to externalise your content.

    Tanstack Start Solid
    Astro and React