Translate your Astro website using Intlayer | Internationalization (i18n)

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:

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

See Application Template on GitHub.

1. 1

   Install Dependencies

   Install the necessary packages using your package manager:

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

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

   Add the intlayer plugin into your configuration.

   astro.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export 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. 4

   Declare Your Content

   Create and manage your content declarations to store translations:

   src/app.content.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

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

   Copy content

   Copy code

   Copy the code to the clipboard

   ---
   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' dictionary
   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>
   
       <!-- 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. 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

   Copy content

   Copy code

   Copy the code to the clipboard

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

   Copy content

   Copy code

   Copy the code to the clipboard

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

   Copy content

   Copy code

   Copy the code to the clipboard

   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

   Copy content

   Copy code

   Copy the code to the clipboard

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

   Continue using your favorite framework

   Continue using your favorite framework to build your application.

   • Intlayer + React: Intlayer with React
   • Intlayer + Vue: Intlayer with Vue
   • Intlayer + Svelte: Intlayer with Svelte
   • Intlayer + Solid: Intlayer with Solid
   • Intlayer + Preact: Intlayer with Preact
   • Intlayer + Lit: Intlayer with Lit
   • Intlayer + Vanilla JS: Intlayer with Vanilla JS
10. 15

    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
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    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
    

Configure TypeScript

Intlayer use 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.

Frequently Asked Questions