Translate your Vite and React website using Intlayer | Internationalization (i18n)

Table of Contents

Why Intlayer over alternatives?

Compared to main solutions like react-i18next 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 React 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 react-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

   • react-intlayer The package that integrates Intlayer with React application. It provides context providers and hooks for React internationalization.

   • 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 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 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 react from "@vitejs/plugin-react-swc";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [react(), 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 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: {
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       reactLogo: t({
         en: "React logo",
         fr: "Logo React",
         es: "Logo React",
       }),
   
       title: "Vite + React",
   
       count: t({
         en: "count is ",
         fr: "le compte est ",
         es: "el recuento es ",
       }),
   
       edit: t<ReactNode>({
         en: (
           <>
             Edit <code>src/App.tsx</code> and save to test HMR
           </>
         ),
         fr: (
           <>
             Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR
           </>
         ),
         es: (
           <>
             Edita <code>src/App.tsx</code> y guarda para probar HMR
           </>
         ),
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and React logos to learn more",
         fr: "Cliquez sur les logos Vite et React pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y React para obtener más información",
       }),
     },
   } 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.

   If your content file includes TSX code, you should consider importing import React from "react"; in your content file.

5. 5

   Utilize Intlayer in Your Code

   Access your content dictionaries throughout your application:

   src/App.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { useState, type FC } from "react";
   import reactLogo from "./assets/react.svg";
   import viteLogo from "/vite.svg";
   import "./App.css";
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   
   const AppContent: FC = () => {
     const [count, setCount] = useState(0);
     const content = useIntlayer("app");
   
     return (
       <>
         <div>
           <a href="https://vitejs.dev" target="_blank">
             <img src={viteLogo} className="logo" alt={content.viteLogo.value} />
           </a>
           <a href="https://react.dev" target="_blank">
             <img
               src={reactLogo}
               className="logo react"
               alt={content.reactLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div className="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count}
             {count}
           </button>
           <p>{content.edit}</p>
         </div>
         <p className="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: FC = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;

   If you want to use your content in a string attribute, such as alt, title, href, aria-label, etc., you can use the value of the function, like:

   html

   Copy content

   Copy code

   Copy the code to the clipboard

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

   To Learn more about the useIntlayer hook, refer to the documentation.

   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.

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 hook. This function allows you to set the locale of the application and update the content accordingly.

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { FC } from "react";
   import { Locales } from "intlayer";
   import { useLocale } from "react-intlayer";
   
   const LocaleSwitcher: FC = () => {
     const { setLocale } = useLocale();
   
     return (
       <button onClick={() => setLocale(Locales.English)}>
         Change Language to English
       </button>
     );
   };

   To Learn more about the useLocale hook, refer to the documentation.

7. 7

   Add localized Routing to your application

   Optional

   The purpose of this step is to make unique routes for each language. This is useful for SEO and SEO-friendly URLs. Example:

   plaintext

   Copy content

   Copy code

   Copy the code to the clipboard

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

   By default, the routes are not prefixed for the default locale. If you want to prefix the default locale, you can set the middleware.prefixDefault option to true in your configuration. See the configuration documentation for more information.

   To add localized routing to your application, you can create a LocaleRouter component that wraps your application's routes and handles locale-based routing. Here is an example using React Router:

   src/components/LocaleRouter.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { localeMap } from "intlayer"; // Utility functions and types from 'intlayer'
   import type { FC, PropsWithChildren } from "react"; // React types for functional components and props
   import { IntlayerProvider } from "react-intlayer"; // Provider for internationalization context
   import { BrowserRouter, Route, Routes } from "react-router-dom"; // Router components for managing navigation
   
   /**
    * A router component that sets up locale-specific routes.
    * It uses React Router to manage navigation and render localized components.
    */
   export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
     <BrowserRouter>
       <Routes>
         {localeMap(({ locale, urlPrefix }) => (
           <Route
             // Route pattern to capture the locale (e.g., /en/, /fr/) and match all subsequent paths
             path={`${urlPrefix}/*`}
             key={locale}
             element={
               <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
             } // Wraps children with locale management
           />
         ))}
       </Routes>
     </BrowserRouter>
   );

   Note: If you use routing.mode: 'no-prefix' | 'search-params', you probably don't need to use the localeMap function.

   Then, you can use the LocaleRouter component in your application:

   src/App.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { LocaleRouter } from "./components/LocaleRouter";
   import type { FC } from "react";
   
   // ... Your AppContent component
   
   const App: FC = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );

   In parallel, you can also use the intlayerProxy to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.

   Note that to use the intlayerProxy in production, you need to switch the vite-intlayer package from devDependencies to dependencies.

   vite.config.ts

   Copy content

   Copy code

   Copy the code to the clipboard

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react-swc";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       intlayerProxy(), // should be placed first
       react(),
       intlayer(),
     ],
   });

8. 8

   Change the URL when the locale changes

   Optional

   To change the URL when the locale changes, you can use the onLocaleChange prop provided by the useLocale hook. In parallel, you can use the useLocation and useNavigate hooks from react-router-dom to update the URL path.

   src/components/LocaleSwitcher.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { useLocation, useNavigate } from "react-router-dom";
   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { type FC } from "react";
   
   const LocaleSwitcher: FC = () => {
     const { pathname, search } = useLocation(); // Get the current URL path. Example: /fr/about?foo=bar
     const navigate = useNavigate();
   
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (locale) => {
         // Construct the URL with the updated locale
         // Example: /es/about?foo=bar
         const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);
   
         // Update the URL path
         navigate(pathWithLocale);
       },
     });
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <a
               href={getLocalizedUrl(location.pathname, localeItem)}
               hrefLang={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={(e) => {
                 e.preventDefault();
                 setLocale(localeItem);
               }}
               key={localeItem}
             >
               <span>
                 {/* Locale - e.g. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Language in its own Locale - e.g. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Language in current Locale - e.g. Francés with current locale set to Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Language in English - e.g. French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </a>
           ))}
         </div>
       </div>
     );
   };

   Documentation references:

   • useLocale hook
   • getLocaleName hook
   • getLocalizedUrl hook
   • getHTMLTextDir hook
   • hrefLang attribute
   • lang attribute
   • dir attribute
   • aria-current attribute

   Below is the updated Step 9 with added explanations and refined code examples:

   ---

9. 9

   Switch the HTML Language and Direction Attributes

   Optional

   When your application supports multiple languages, it's crucial to update the <html> tag's lang and dir attributes to match the current locale. Doing so ensures:

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

   Implementing the Hook

   Create a custom hook to manage the HTML attributes. The hook listens for locale changes and updates the attributes accordingly:

   src/hooks/useI18nHTMLAttributes.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import { useEffect } from "react";
   import { useLocale } from "react-intlayer";
   import { getHTMLTextDir } from "intlayer";
   
   /**
    * Updates the HTML <html> element's `lang` and `dir` attributes based on the current locale.
    * - `lang`: Informs browsers and search engines of the page's language.
    * - `dir`: Ensures the correct reading order (e.g., 'ltr' for English, 'rtl' for Arabic).
    *
    * This dynamic update is essential for proper text rendering, accessibility, and SEO.
    */
   export const useI18nHTMLAttributes = () => {
     const { locale } = useLocale();
   
     useEffect(() => {
       // Update the language attribute to the current locale.
       document.documentElement.lang = locale;
   
       // Set the text direction based on the current locale.
       document.documentElement.dir = getHTMLTextDir(locale);
     }, [locale]);
   };

   Using the Hook in Your Application

   Integrate the hook into your main component so that the HTML attributes update whenever the locale changes:

   src/App.tsx

   Copy content

   Copy code

   Copy the code to the clipboard

   import type { FC } from "react";
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
   import "./App.css";
   
   const AppContent: FC = () => {
     // Apply the hook to update the <html> tag's lang and dir attributes based on the locale.
     useI18nHTMLAttributes();
   
     // ... Rest of your component
   };
   
   const App: FC = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;

   By applying these changes, your application will:

   • Ensure the language (lang) attribute correctly reflects the current locale, which is important for SEO and browser behavior.
   • Adjust the text direction (dir) according to the locale, enhancing readability and usability for languages with different reading orders.
   • Provide a more accessible experience, as assistive technologies depend on these attributes to function optimally.
10. 10

    Creating a Localized Link Component

    Optional

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

    • SEO and User Experience: Localized URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
    • Consistency: By using a localized link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
    • Maintainability: Centralizing the localization logic in a single component simplifies the management of URLs, making your codebase easier to maintain and extend as your application grows.

    Below is the implementation of a localized Link component in TypeScript:

    src/components/Link.tsx

    Copy content

    Copy code

    Copy the code to the clipboard

    import { getLocalizedUrl } from "intlayer";
    import {
      forwardRef,
      type DetailedHTMLProps,
      type AnchorHTMLAttributes,
    } from "react";
    import { useLocale } from "react-intlayer";
    
    export interface LinkProps extends DetailedHTMLProps<
      AnchorHTMLAttributes<HTMLAnchorElement>,
      HTMLAnchorElement
    > {}
    
    /**
     * Utility function to check whether a given URL is external.
     * If the URL starts with http:// or https://, it's considered external.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * A custom Link component that adapts the href attribute based on the current locale.
     * For internal links, it uses `getLocalizedUrl` to prefix the URL with the locale (e.g., /fr/about).
     * This ensures that navigation stays within the same locale context.
     */
    export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
      ({ href, children, ...props }, ref) => {
        const { locale } = useLocale();
        const isExternalLink = checkIsExternalLink(href);
    
        // If the link is internal and a valid href is provided, get the localized URL.
        const hrefI18n =
          href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
    
        return (
          <a href={hrefI18n} ref={ref} {...props}>
            {children}
          </a>
        );
      }
    );
    
    Link.displayName = "Link";

    How It Works

    • Detecting External Links:
      The helper function checkIsExternalLink determines whether a URL is external. External links are left unchanged because they do not need localization.

    • Retrieving the Current Locale:
      The useLocale hook provides the current locale (e.g., fr for French).

    • Localizing the URL:
      For internal links (i.e., non-external), getLocalizedUrl is used to automatically prefix the URL with the current locale. This means that if your user is in French, passing /about as the href will transform it to /fr/about.

    • Returning the Link:
      The component returns an <a> element with the localized URL, ensuring that navigation is consistent with the locale.

    By integrating this Link component across your application, you maintain a coherent and language-aware user experience while also benefitting from improved SEO and usability.

11. 11

    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

    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

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