Easily manage translations using declarative dictionaries at the component level.
Dynamically localize metadata, routes, and content.
Ensure TypeScript support with autogenerated types, improving autocompletion and error detection.
Benefit from advanced features, like dynamic locale detection and switching.

Step-by-Step Guide to Set Up Intlayer in a React Application

Step 1: Install Dependencies

Install the necessary packages using npm:

bash

Copy code

Copy the code to the clipboard

npm install intlayer react-intlayer react-scripts-intlayernpx 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.
react-scripts-intlayer

Includes the react-scripts-intlayer commands and plugins for integrating Intlayer with the Create React App based application. These plugins are based on craco and includes additional configuration for the Webpack bundler.

Step 2: Configuration of your project

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

intlayer.config.ts

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.

Step 3: Integrate Intlayer in Your CRA Configuration

Change your scripts to use react-intlayer

package.json

Copy code

Copy the code to the clipboard

  "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },

react-scripts-intlayer scripts are based on CRACO. You can also implement your own setup based on the intlayer craco plugin. See example here.

Step 4: Declare Your Content

Create and manage your content declarations to store translations:

src/app.content.tsx

Copy code

Copy the code to the clipboard

import { t, type Dictionary } from "intlayer";
import React, { type ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      en: (
        <>
          Edit <code>src/App.tsx</code> and save to reload
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} 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}).

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.

Step 5: Utilize Intlayer in Your Code

Access your content dictionaries throughout your application:

src/App.tsx

Copy code

Copy the code to the clipboard

import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="logo" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

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

(Optional) Step 6: Change the language of your content

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 code

Copy the code to the clipboard

import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  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.

(Optional) Step 7: Add localized Routing to your application

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

Copy the code to the clipboard

// Importing necessary dependencies and functions
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Utility functions and types 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,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Router components for managing navigation

// Destructuring configuration from Intlayer
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * A component that handles localization and wraps children with the appropriate locale context.
 * It manages URL-based locale detection and validation.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Get the current URL path

  // Determine the current locale, falling back to the default if not provided
  const currentLocale = locale ?? defaultLocale;

  // Remove the locale prefix from the path to construct a base path
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Current URL path
  );

  /**
   * If middleware.prefixDefault is true, the default locale should always be prefixed.
   */
  if (middleware.prefixDefault) {
    // Validate the locale
    if (!locale || !locales.includes(locale)) {
      // Redirect to the default locale with the updated path
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Replace the current history entry with the new one
        />
      );
    }

    // Wrap children with the IntlayerProvider and set the current locale
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * When middleware.prefixDefault is false, the default locale is not prefixed.
     * Ensure that the current locale is valid and not the default locale.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Exclude the default locale
        )
        .includes(currentLocale) // Check if the current locale is in the list of valid locales
    ) {
      // Redirect to the path without locale prefix
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Wrap children with the IntlayerProvider and set the current locale
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * 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>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Route pattern to capture the locale (e.g., /en/, /fr/) and match all subsequent paths
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Wraps children with locale management
          />
        ))}

      {
        // If prefixing the default locale is disabled, render the children directly at the root path
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Wraps children with locale management
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

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

src/App.tsx

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>
);

(Optional) Step 8: Change the URL when the locale changes

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

(Optional) Step 9: Switch the HTML Language and Direction Attributes

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

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

Copy code

Copy the code to the clipboard

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

.gitignore

Copy code

Copy the code to the clipboard

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

Analog

React Native and Expo

Creation:2025-08-23Last update:2026-05-06

See the application template on GitHub

This page has an application template available.

Reference this doc to your favorite AI assistant

ChatGPT

Claude

DeepSeek

Google AI mode Gemini

Perplexity Mistral

Grok

Ask your question and get a summary of the document by referencing this page and the AI provider of your choice

Version History

"Update Solid useIntlayer API usage to direct property access"
v8.9.05/4/2026
"Add init command"
v7.5.912/30/2025
"Initial history"
v5.5.106/29/2025

Edit this doc

If you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.

GitHub link to the documentation

Copy

Copy doc Markdown to clipboard

Translate your Create React App website using Intlayer | Internationalization (i18n)

ide.intlayer.org

See Application Template on GitHub.

What is Intlayer?

Intlayer is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications.

With Intlayer, you can:

Easily manage translations using declarative dictionaries at the component level.
Dynamically localize metadata, routes, and content.
Ensure TypeScript support with autogenerated types, improving autocompletion and error detection.
Benefit from advanced features, like dynamic locale detection and switching.

Step-by-Step Guide to Set Up Intlayer in a React Application

Step 1: Install Dependencies

Install the necessary packages using npm:

bash

Copy code

Copy the code to the clipboard

npm install intlayer react-intlayer react-scripts-intlayernpx intlayer init

npm install intlayer react-intlayer react-scripts-intlayernpx 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.
react-scripts-intlayer

Includes the react-scripts-intlayer commands and plugins for integrating Intlayer with the Create React App based application. These plugins are based on craco and includes additional configuration for the Webpack bundler.

Step 2: Configuration of your project

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

intlayer.config.ts

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.

Step 3: Integrate Intlayer in Your CRA Configuration

Change your scripts to use react-intlayer

package.json

Copy code

Copy the code to the clipboard

  "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },

  "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },

react-scripts-intlayer scripts are based on CRACO. You can also implement your own setup based on the intlayer craco plugin. See example here.

Step 4: Declare Your Content

Create and manage your content declarations to store translations:

src/app.content.tsx

Copy code

Copy the code to the clipboard

import { t, type Dictionary } from "intlayer";
import React, { type ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      en: (
        <>
          Edit <code>src/App.tsx</code> and save to reload
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} 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}).

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.

Step 5: Utilize Intlayer in Your Code

Access your content dictionaries throughout your application:

src/App.tsx

Copy code

Copy the code to the clipboard

import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="logo" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

Note: 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 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)}" />

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

(Optional) Step 6: Change the language of your content

src/components/LocaleSwitcher.tsx

Copy code

Copy the code to the clipboard

import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  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.

(Optional) Step 7: Add localized Routing to your application

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 code

Copy the code to the clipboard

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

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

Copy the code to the clipboard

// Importing necessary dependencies and functions
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Utility functions and types 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,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Router components for managing navigation

// Destructuring configuration from Intlayer
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * A component that handles localization and wraps children with the appropriate locale context.
 * It manages URL-based locale detection and validation.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Get the current URL path

  // Determine the current locale, falling back to the default if not provided
  const currentLocale = locale ?? defaultLocale;

  // Remove the locale prefix from the path to construct a base path
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Current URL path
  );

  /**
   * If middleware.prefixDefault is true, the default locale should always be prefixed.
   */
  if (middleware.prefixDefault) {
    // Validate the locale
    if (!locale || !locales.includes(locale)) {
      // Redirect to the default locale with the updated path
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Replace the current history entry with the new one
        />
      );
    }

    // Wrap children with the IntlayerProvider and set the current locale
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * When middleware.prefixDefault is false, the default locale is not prefixed.
     * Ensure that the current locale is valid and not the default locale.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Exclude the default locale
        )
        .includes(currentLocale) // Check if the current locale is in the list of valid locales
    ) {
      // Redirect to the path without locale prefix
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Wrap children with the IntlayerProvider and set the current locale
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * 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>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Route pattern to capture the locale (e.g., /en/, /fr/) and match all subsequent paths
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Wraps children with locale management
          />
        ))}

      {
        // If prefixing the default locale is disabled, render the children directly at the root path
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Wraps children with locale management
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

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

src/App.tsx

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>
);

(Optional) Step 8: Change the URL when the locale changes

src/components/LocaleSwitcher.tsx

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

(Optional) Step 9: Switch the HTML Language and Direction Attributes

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

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

Copy code

Copy the code to the clipboard

{  // ... Your existing TypeScript configurations  "include": [    // ... Your existing TypeScript configurations    ".intlayer/**/*.ts", // Include the auto-generated 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:

.gitignore

Copy code

Copy the code to the clipboard

# Ignore the files generated by Intlayer.intlayer

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

Analog

React Native and Expo