@intlayer/docs 5.5.9 → 5.5.11

package/docs/en-GB/intlayer_with_vite+react.md

@@ -0,0 +1,1703 @@
+---
+createdAt: 2025-03-07
+updatedAt: 2025-06-29
+title: Translate your React Native and Expo mobile app (i18n)
+description: Discover how to make your React Native and Expo mobile app multilingual. Follow the documentation to internationalise (i18n) and translate it.
+keywords:
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Vite
+  - React
+  - React Native
+  - JavaScript
+slugs:
+  - doc
+  - environment
+  - react-native-and-expo
+---
+
+# Getting Started Internationalising (i18n) with Intlayer and Vite and React
+
+See [Application Template](https://github.com/aymericzip/intlayer-vite-react-template) on GitHub.
+
+## What is Intlayer?
+
+**Intlayer** is an innovative, open-source internationalisation (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 localise 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 Vite and React Application
+
+### Step 1: Install Dependencies
+
+Install the necessary packages using npm:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install --save-dev vite-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+pnpm add --save-dev vite-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer react-intlayer
+yarn add --save-dev vite-intlayer
+```
+
+- **intlayer**
+
+  The core package that provides internationalisation tools for configuration management, translation, [content declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/get_started.md), transpilation, and [CLI commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_cli.md).
+
+- **react-intlayer**
+  The package that integrates Intlayer with React applications. It provides context providers and hooks for React internationalisation.
+
+- **vite-intlayer**
+  Includes the Vite plugin for integrating Intlayer with the [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production), as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.
+
+### Step 2: Configuration of your project
+
+Create a config file to configure the languages of your application:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+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;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> Through this configuration file, you can set up localised 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+
+### Step 3: Integrate Intlayer in Your Vite Configuration
+
+Add the intlayer plugin into your configuration.
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayerPlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), intlayerPlugin()],
+});
+```
+
+```javascript fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayerPlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), intlayerPlugin()],
+});
+```
+
+```javascript fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const react = require("@vitejs/plugin-react-swc");
+const { intlayerPlugin } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [react(), intlayerPlugin()],
+});
+```
+
+> The `intlayerPlugin()` 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 optimise performance.
+
+### Step 4: Declare Your Content
+
+Create and manage your content declarations to store translations:
+
+```tsx fileName="src/app.content.tsx" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+import type { ReactNode } from "react";
+
+const appContent = {
+  key: "app",
+  content: {
+    viteLogo: t({
+      "en-GB": "Vite logo",
+      en: "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    reactLogo: t({
+      "en-GB": "React logo",
+      en: "React logo",
+      fr: "Logo React",
+      es: "Logo React",
+    }),
+
+    title: "Vite + React",
+
+    count: t({
+      "en-GB": "count is ",
+      en: "count is ",
+      fr: "le compte est ",
+      es: "el recuento es ",
+    }),
+
+    edit: t<ReactNode>({
+      "en-GB": (
+        <>
+          Edit <code>src/App.tsx</code> and save to test HMR
+        </>
+      ),
+      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-GB": "Click on the Vite and React logos to learn more",
+      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;
+```
+
+```javascript fileName="src/app.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    viteLogo: t({
+      "en-GB": "Vite logo",
+      en: "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    reactLogo: t({
+      "en-GB": "React logo",
+      en: "React logo",
+      fr: "Logo React",
+      es: "Logo React",
+    }),
+
+    title: "Vite + React",
+
+    count: t({
+      "en-GB": "count is ",
+      en: "count is ",
+      fr: "le compte est ",
+      es: "el recuento es ",
+    }),
+
+    edit:
+      t <
+      ReactNode >
+      {
+        // Remember to import React if you use a React node in your content
+        "en-GB": (
+          <>
+            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-GB": "Click on the Vite and React logos to learn more",
+      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",
+    }),
+  },
+};
+
+export default appContent;
+```
+
+```javascript fileName="src/app.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const appContent = {
+  key: "app",
+  content: {
+    viteLogo: t({
+      "en-GB": "Vite logo",
+      fr: "Logo Vite",
+      es: "Logo Vite",
+    }),
+    reactLogo: t({
+      "en-GB": "React logo",
+      fr: "Logo React",
+      es: "Logo React",
+    }),
+
+    title: "Vite + React",
+
+    count: t({
+      "en-GB": "count is ",
+      fr: "le compte est ",
+      es: "el recuento es ",
+    }),
+
+    edit:
+      t <
+      ReactNode >
+      {
+        // Remember to import React if you use a React node in your content
+        "en-GB": (
+          <>
+            Edit <code>src/App.tsx</code> and save to test HMR
+          </>
+        ),
+        fr: (
+          <>
+            Éditez <code>src/App.tsx</code> et enregistrez pour tester HMR
+          </>
+        ),
+        es: (
+          <>
+            Edit <code>src/App.tsx</code> and save to test HMR
+          </>
+        ),
+      },
+
+    readTheDocs: t({
+      "en-GB": "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",
+    }),
+  },
+};
+
+module.exports = appContent;
+```
+
+```json fileName="src/app.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "app",
+  "content": {
+    "viteLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Vite logo",
+        "fr": "Logo Vite",
+        "es": "Logo Vite"
+      }
+    },
+    "reactLogo": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "React logo",
+        "fr": "Logo React",
+        "es": "Logo React"
+      }
+    },
+    "title": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Vite + React",
+        "fr": "Vite + React",
+        "es": "Vite + React"
+      }
+    },
+    "count": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "count is ",
+        "fr": "le compte est ",
+        "es": "el recuento es "
+      }
+    },
+    "edit": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Edit src/App.tsx and save to test HMR",
+        "fr": "Éditez src/App.tsx et enregistrez pour tester HMR",
+        "es": "Edita src/App.tsx y guarda para probar HMR"
+      }
+    },
+    "readTheDocs": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "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"
+      }
+    }
+  }
+}
+```
+
+> Your content declarations can be defined anywhere in your application as soon as 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,mjx,cjs,cjx}`).
+
+> For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/get_started.md).
+
+> If your content file includes TSX code, you should consider importing `import React from "react";` in your content file.
+
+### Step 5: Utilise Intlayer in Your Code
+
+Access your content dictionaries throughout your application:
+
+```tsx {5,9} fileName="src/App.tsx" codeFormat="typescript"
+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;
+```
+
+```tsx {5,9} fileName="src/App.msx" codeFormat="esm"
+import { useState } from "react";
+import reactLogo from "./assets/react.svg";
+import viteLogo from "/vite.svg";
+import "./App.css";
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+
+const AppContent = () => {
+  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 = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```tsx {5,9} fileName="src/App.csx" codeFormat="commonjs"
+const { useState } = require("react");
+const reactLogo = require("./assets/react.svg");
+const viteLogo = require("/vite.svg");
+require("./App.css");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+
+const AppContent = () => {
+  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 = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+module.exports = App;
+```
+
+> If you want to use your content in a `string` attribute, such as `alt`, `title`, `href`, `aria-label`, etc., you must call the value of the function, like:
+
+> ```jsx
+> <img src={content.image.src.value} alt={content.image.value} />
+> ```
+
+> To learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md).
+
+### (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.
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.msx" codeFormat="esm"
+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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+const { useLocale } = require("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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md).
+
+### (Optional) Step 7: Add localised Routing to your application
+
+The purpose of this step is to create unique routes for each language. This is useful for SEO and SEO-friendly URLs.
+Example:
+
+```plaintext
+- 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 wish to prefix the default locale, you can set the `middleware.prefixDefault` option to `true` in your configuration. See the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md) for more information.
+
+To add localised routing to your application, you can create a `LocaleRouter` component that wraps your application's routes and manages locale-based routing. Here is an example using [React Router](https://reactrouter.com/home):
+
+```tsx fileName="src/components/LocaleRouter.tsx"  codeFormat="typescript"
+// Importing necessary dependencies and functions
+import { type Locales, configuration, getPathWithoutLocale } 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 internationalisation 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 localisation 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 is 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 localised 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>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.mjx" codeFormat="esm"
+// Importing necessary dependencies and functions
+import { configuration, getPathWithoutLocale } from "intlayer"; // Utility functions and types from 'intlayer'
+// Utility functions and types from 'intlayer'
+import { IntlayerProvider } from "react-intlayer"; // Provider for internationalisation 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 localisation and wraps children with the appropriate locale context.
+ * It manages URL-based locale detection and validation.
+ */
+const AppLocalized = ({ 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 is 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 localised components.
+ */
+export const LocaleRouter = ({ 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>
+);
+```
+
+```jsx fileName="src/components/LocaleRouter.cjx" codeFormat="commonjs"
+// Importing necessary dependencies and functions
+const { configuration, getPathWithoutLocale } = require("intlayer"); // Utility functions and types from 'intlayer'
+const { IntlayerProvider, useLocale } = require("react-intlayer"); // Provider for internationalisation context
+const {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} = require("react-router-dom"); // Router components for managing navigation
+
+// Destructuring configuration from Intlayer
+const { internationalisation, middleware } = configuration;
+const { locales, defaultLocale } = internationalisation;
+
+/**
+ * A component that handles localisation and wraps children with the appropriate locale context.
+ * It manages URL-based locale detection and validation.
+ */
+// Importing necessary dependencies and functions
+const { configuration, getPathWithoutLocale } = require("intlayer"); // Utility functions and types from 'intlayer'
+const { IntlayerProvider, useLocale } = require("react-intlayer"); // Provider for internationalisation context
+const {
+  BrowserRouter,
+  Routes,
+  Route,
+  Navigate,
+  useLocation,
+} = require("react-router-dom"); // Router components for managing navigation
+
+// Destructuring configuration from Intlayer
+const { internationalization, middleware } = configuration;
+const { locales, defaultLocale } = internationalization;
+
+/**
+ * A component that handles localisation and wraps children with the appropriate locale context.
+ * It manages URL-based locale detection and validation.
+ */
+const AppLocalized = ({ 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 is 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 localised components.
+ */
+const LocaleRouter = ({ 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:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import { LocaleRouter } from "./components/LocaleRouter";
+import type { FC } from "react";
+
+// ... Your AppContent component
+
+const App: FC = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.mjx" codeFormat="esm"
+import { LocaleRouter } from "./components/LocaleRouter";
+
+// ... Your AppContent component
+
+const App = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+```jsx fileName="src/App.cjx" codeFormat="commonjs"
+const { LocaleRouter } = require("./components/LocaleRouter");
+
+// ... Your AppContent component
+
+const App = () => (
+  <LocaleRouter>
+    <AppContent />
+  </LocaleRouter>
+);
+```
+
+In parallel, you can also use the `intLayerMiddlewarePlugin` 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.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const react = require("@vitejs/plugin-react-swc");
+const { intlayerPlugin, intLayerMiddlewarePlugin } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [react(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+### (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.
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.msx" codeFormat="esm"
+import { useLocation, useNavigate } from "react-router-dom";
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  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>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocation, useNavigate } = require("react-router-dom");
+const {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} = require("intlayer");
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/packages/react-intlayer/useLocale.md)
+> - [`getLocaleName` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/packages/intlayer/getLocaleName.md)
+> - [`getLocalizedUrl` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/packages/intlayer/getLocalizedUrl.md)
+> - [`getHTMLTextDir` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/intlayer/getHTMLTextDir.md)
+> - [`hrefLang` attribute](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
+> - [`lang` attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
+> - [`dir` attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
+> - [`aria-current` attribute`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
+
+Below is the updated **Step 9** with added explanations and refined code examples:
+
+---
+
+### (Optional) Step 9: Switch the HTML Language and Direction Attributes
+
+When your application supports multiple languages, it is crucial to update the `<html>` tag's `lang` and `dir` attributes to correspond with the current locale. Doing so ensures:
+
+- **Accessibility**: Screen readers and assistive technologies depend on the correct `lang` attribute to pronounce and interpret content accurately.
+- **Text Rendering**: The `dir` (direction) attribute guarantees that text is rendered in the correct 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 identify the language of your page, aiding in delivering the appropriate localised 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:
+
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+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]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.msx" codeFormat="esm"
+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]);
+};
+```
+
+```jsx fileName="src/hooks/useI18nHTMLAttributes.csx" codeFormat="commonjs"
+const { useEffect } = require("react");
+const { useLocale } = require("react-intlayer");
+const { getHTMLTextDir } = require("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.
+ */
+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]);
+};
+
+module.exports = { useI18nHTMLAttributes };
+```
+
+#### Using the Hook in Your Application
+
+Integrate the hook into your main component so that the HTML attributes update whenever the locale changes:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+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;
+```
+
+````jsx fileName="src/App.msx" codeFormat="esm"
+#### Using the Hook in Your Application
+
+Integrate the hook into your main component so that the HTML attributes update whenever the locale changes:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+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;
+````
+
+```jsx fileName="src/App.msx" codeFormat="esm"
+import { IntlayerProvider, useIntlayer } from "react-intlayer";
+import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
+import "./App.css";
+
+const AppContent = () => {
+  // Apply the hook to update the <html> tag's lang and dir attributes based on the locale.
+  useI18nHTMLAttributes();
+
+  // ... Rest of your component
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+export default App;
+```
+
+```jsx fileName="src/App.csx" codeFormat="commonjs"
+const { FC } = require("react");
+const { IntlayerProvider, useIntlayer } = require("react-intlayer");
+const { useI18nHTMLAttributes } = require("./hooks/useI18nHTMLAttributes");
+require("./App.css");
+
+const AppContent = () => {
+  // Apply the hook to update the <html> tag's lang and dir attributes based on the locale.
+  useI18nHTMLAttributes();
+
+  // ... Rest of your component
+};
+
+const App = () => (
+  <IntlayerProvider>
+    <AppContent />
+  </IntlayerProvider>
+);
+
+module.exports = 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 behaviour.
+- 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.
+
+### (Optional) Step 10: Creating a Localised Link Component
+
+// Apply the hook to update the <html> tag's lang and dir attributes based on the locale.
+useI18nHTMLAttributes();
+
+// ... Rest of your component
+};
+
+const App = () => (
+<IntlayerProvider>
+<AppContent />
+</IntlayerProvider>
+);
+
+module.exports = 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 behaviour.
+- 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.
+
+### (Optional) Step 10: Creating a Localised Link Component
+
+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. 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 behaviour is useful for several reasons:
+
+- **SEO and User Experience**: Localised URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
+- **Consistency**: By using a localised link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
+- **Maintainability**: Centralising the localisation 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 localised `Link` component in TypeScript:
+
+```tsx fileName="src/components/Link.tsx" codeFormat="typescript"
+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 is 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 remains 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 localised URL.
+    const hrefI18n =
+      href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
+
+    return (
+      <a href={hrefI18n} ref={ref} {...props}>
+        {children}
+      </a>
+    );
+  }
+);
+
+Link.displayName = "Link";
+````
+
+```jsx fileName="src/components/Link.mjx" codeFormat="esm"
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
+import { forwardRef } from "react";
+
+/**
+ * Utility function to check whether a given URL is external.
+ * If the URL starts with http:// or https://, it is 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 remains within the same locale context.
+ */
+export const Link = forwardRef(({ href, children, ...props }, ref) => {
+  const { locale } = useLocale();
+  const isExternalLink = checkIsExternalLink(href);
+
+  // If the link is internal and a valid href is provided, get the localised URL.
+  const hrefI18n =
+    href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
+
+  return (
+    <a href={hrefI18n} ref={ref} {...props}>
+      {children}
+    </a>
+  );
+});
+
+Link.displayName = "Link";
+```
+
+```jsx fileName="src/components/Link.csx" codeFormat="commonjs"
+const { getLocalizedUrl } = require("intlayer");
+const { useLocale } = require("react-intlayer");
+const { forwardRef } = require("react");
+
+/**
+ * Utility function to check whether a given URL is external.
+ * If the URL starts with http:// or https://, it is considered external.
+ */
+const checkIsExternalLink = (href) => /^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 remains within the same locale context.
+ */
+const Link = forwardRef(({ href, children, ...props }, ref) => {
+  const { locale } = useLocale();
+  const isExternalLink = checkIsExternalLink(href);
+
+  // If the link is internal and a valid href is provided, get the localised URL.
+  const localizedHref = isExternalLink ? href : getLocalizedUrl(href, locale);
+
+  return (
+    <a
+      href={localizedHref}
+      ref={ref}
+      {...props}
+      aria-current={isExternalLink ? "external" : undefined}
+    >
+      {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 require localisation.
+
+- **Retrieving the Current Locale**:  
+  The `useLocale` hook provides the current locale (e.g., `fr` for French).
+
+- **Localising 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 localised 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 whilst also benefitting from improved SEO and usability.
+
+### Configure TypeScript
+
+Intlayer uses module augmentation to take advantage of TypeScript and make your codebase stronger.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+
+Ensure your TypeScript configuration includes the autogenerated types.
+
+```json5 fileName="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 prevents you from committing them to your Git repository.
+
+To do this, you can add the following instructions to your `.gitignore` file:
+
+```plaintext
+# Ignore the files generated by Intlayer
+.intlayer
+```
+
+### VS Code Extension
+
+To enhance your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
+
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+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](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Go Further
+
+To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) or externalise your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md).
+
+---
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history