@intlayer/docs 6.1.6-canary.0 → 7.0.0-canary.0

package/docs/en-GB/intlayer_with_react_router_v7.md

@@ -1,7 +1,7 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2025-09-04
-title: Getting Started with Intlayer in React Router v7
+updatedAt: 2025-10-03
+title: How to translate your React Router v7 app – i18n guide 2025
 description: Learn how to add internationalisation (i18n) to your React Router v7 application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
 keywords:
   - Internationalisation
@@ -17,8 +17,14 @@ slugs:
   - environment
   - vite-and-react
   - react-router-v7
-applicationTemplate: https://github.com/AydinTheFirst/react-router-intlayer
-author: AydinTheFirst
+applicationTemplate: https://github.com/aymericzip/intlayer-react-router-v7-template
+history:
+  - version: 6.1.5
+    date: 2025-10-03
+    changes: Updated doc
+  - version: 5.8.2
+    date: 2025-09-04
+    changes: Added for React Router v7
 ---
 
 # Getting Started Internationalising (i18n) with Intlayer and React Router v7
@@ -57,10 +63,10 @@ pnpm add vite-intlayer --save-dev
 
 - **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).
+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.
+  The package that integrates Intlayer with a React application. 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.
@@ -75,10 +81,7 @@ import { type IntlayerConfig, Locales } from "intlayer";
 const config: IntlayerConfig = {
   internationalization: {
     defaultLocale: Locales.ENGLISH,
-    locales: [Locales.ENGLISH, Locales.TURKISH],
-  },
-  middleware: {
-    prefixDefault: true, // Always prefix default locale in URLs
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
   },
 };
 
@@ -92,10 +95,7 @@ import { Locales } from "intlayer";
 const config = {
   internationalization: {
     defaultLocale: Locales.ENGLISH,
-    locales: [Locales.ENGLISH, Locales.TURKISH],
-  },
-  middleware: {
-    prefixDefault: true,
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
   },
 };
 
@@ -109,10 +109,7 @@ const { Locales } = require("intlayer");
 const config = {
   internationalization: {
     defaultLocale: Locales.ENGLISH,
-    locales: [Locales.ENGLISH, Locales.TURKISH],
-  },
-  middleware: {
-    prefixDefault: true,
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
   },
 };
 
@@ -121,58 +118,55 @@ 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: Configure React Router v7 Routes
-
-Set up your routing configuration with locale-aware routes:
-
-```typescript fileName="app/routes.ts" codeFormat="typescript"
-import { layout, route, type RouteConfig } from "@react-router/dev/routes";
-
-export default [
-  layout("routes/layout.tsx", [
-    route("/", "routes/page.tsx"), // Root page - redirects to locale
-    route("/:lang", "routes/[lang]/page.tsx"), // Localised home page
-    route("/:lang/about", "routes/[lang]/about/page.tsx"), // Localised about page
-  ]),
-] satisfies RouteConfig;
-```
-
-### Step 4: Integrate Intlayer in Your Vite Configuration
+### Step 3: Integrate Intlayer in Your Vite Configuration
 
 Add the intlayer plugin into your configuration:
 
-```typescript fileName="vite.config.ts" codeFormat="typescript"
+```typescript fileName="vite.config.ts"
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
-import { intlayerMiddlewarePlugin, intlayer } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 import tsconfigPaths from "vite-tsconfig-paths";
 
 export default defineConfig({
-  plugins: [
-    reactRouter(),
-    tsconfigPaths(),
-    intlayer(),
-    intlayerMiddlewarePlugin(),
-  ],
+  plugins: [reactRouter(), tsconfigPaths(), intlayer()],
 });
 ```
 
 > The `intlayer()` Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Vite application. Additionally, it provides aliases to optimise performance.
 
+### Step 4: Configure React Router v7 Routes
+
+Set up your routing configuration with locale-aware routes:
+
+```typescript fileName="app/routes.ts"
+import { layout, route, type RouteConfig } from "@react-router/dev/routes";
+
+export default [
+  layout("routes/layout.tsx", [
+    route("/:lang?", "routes/page.tsx"), // Localised home page
+    route("/:lang?/about", "routes/about/page.tsx"), // Localised about page
+  ]),
+] satisfies RouteConfig;
+```
+
 ### Step 5: Create Layout Components
 
 Set up your root layout and locale-specific layouts:
 
 #### Root Layout
 
-```tsx fileName="app/routes/layout.tsx" codeFormat="typescript"
-// app/routes/layout.tsx
-import { Outlet } from "react-router";
+```tsx fileName="app/routes/layout.tsx"
 import { IntlayerProvider } from "react-intlayer";
+import { Outlet } from "react-router";
+
+import type { Route } from "./+types/layout";
+
+export default function RootLayout({ params }: Route.ComponentProps) {
+  const { locale } = params;
 
-export default function RootLayout() {
   return (
-    <IntlayerProvider>
+    <IntlayerProvider locale={locale}>
       <Outlet />
     </IntlayerProvider>
   );
@@ -183,7 +177,7 @@ export default function RootLayout() {
 
 Create and manage your content declarations to store translations:
 
-```tsx fileName="app/routes/[lang]/page.content.ts" contentDeclarationFormat="typescript"
+```tsx fileName="app/routes/[lang]/page.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 const pageContent = {
@@ -191,21 +185,23 @@ const pageContent = {
   content: {
     title: t({
       en: "Welcome to React Router v7 + Intlayer",
-      tr: "React Router v7 + Intlayer'a Hoş Geldiniz",
+      es: "Bienvenido a React Router v7 + Intlayer",
+      fr: "Bienvenue sur React Router v7 + Intlayer",
     }),
     description: t({
       en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
-      tr: "React Router v7 ve Intlayer kullanarak kolayca çok dilli uygulamalar geliştirin.",
+      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
+      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
     }),
     aboutLink: t({
-      "en-GB": "Learn About Us",
       en: "Learn About Us",
-      tr: "Hakkımızda Öğrenin",
+      es: "Aprender Sobre Nosotros",
+      fr: "En savoir plus sur nous",
     }),
     homeLink: t({
-      "en-GB": "Home",
       en: "Home",
-      tr: "Ana Sayfa",
+      es: "Inicio",
+      fr: "Accueil",
     }),
   },
 } satisfies Dictionary;
@@ -213,7 +209,7 @@ const pageContent = {
 export default pageContent;
 ```
 
-> Your content declarations can be defined anywhere in your application as soon as they are included into the `contentDir` directory (by default, `./app`). And match the content declaration file extension (by default, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+> Your content declarations can be defined anywhere in your application as soon as they are included in the `contentDir` directory (by default, `./app`). 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).
 
@@ -221,96 +217,82 @@ export default pageContent;
 
 Create a `LocalizedLink` component for locale-aware navigation:
 
-```tsx fileName="app/components/localized-link.tsx" codeFormat="typescript"
-// app/components/localized-link.tsx
-import { getLocalizedUrl } from "intlayer";
-import { useLocale } from "react-intlayer";
-import React from "react";
-import { Link, useLocation } from "react-router";
-
-type RouterLinkProps = React.ComponentProps<typeof Link>;
+```tsx fileName="app/components/localized-link.tsx"
+import type { FC } from "react";
 
-export default function LocalizedLink({ to, ...props }: RouterLinkProps) {
-  const { locale } = useLocale();
-  const location = useLocation();
+import { getLocalizedUrl, type LocalesValues } from "intlayer";
+import { useLocale } from "react-intlayer";
+import { Link, type LinkProps, type To } from "react-router";
 
-  const isExternal = (path: string) =>
-    /^([a-z][a-z0-9+.-]*:)?\/\//i.test(path) || path.startsWith("mailto:");
+const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);
 
+export const locacalizeTo = (to: To, locale: LocalesValues): To => {
   if (typeof to === "string") {
-    if (to.startsWith("/") && !isExternal(to)) {
-      return <Link to={getLocalizedUrl(to, locale)} {...props} />;
+    if (isExternalLink(to)) {
+      return to;
     }
-    return <Link to={to} {...props} />;
+
+    return getLocalizedUrl(to, locale);
   }
 
-  if (to && typeof to === "object") {
-    const pathname = (to as { pathname?: string }).pathname;
-    if (pathname && pathname.startsWith("/") && !isExternal(pathname)) {
-      return (
-        <Link
-          to={{ ...to, pathname: getLocalizedUrl(pathname, locale) }}
-          {...props}
-        />
-      );
-    }
-    return <Link to={to} {...props} />;
+  if (isExternalLink(to.pathname ?? "")) {
+    return to;
   }
 
-  return (
-    <Link
-      to={getLocalizedUrl(location.pathname + location.search, locale)}
-      {...props}
-    />
-  );
-}
-```
+  return {
+    ...to,
+    pathname: getLocalizedUrl(to.pathname ?? "", locale),
+  };
+};
 
-### Step 8: Utilise Intlayer in Your Pages
+export const LocalizedLink: FC<LinkProps> = (props) => {
+  const { locale } = useLocale();
 
-Access your content dictionaries throughout your application:
+  return <Link {...props} to={locacalizeTo(props.to, locale)} />;
+};
+```
 
-#### Root Redirect Page
+If you want to navigate to the localised routes, you can use the `useLocalizedNavigate` hook:
 
-```tsx fileName="app/routes/page.tsx" codeFormat="typescript"
-// app/routes/page.tsx
-import { useLocale } from "react-intlayer";
-import { Navigate } from "react-router";
+```tsx fileName="app/hooks/useLocalizedNavigate.ts"
+import { useLocale } from "intlayer";
+import { type NavigateOptions, type To, useNavigate } from "react-router";
 
-export default function Page() {
+import { locacalizeTo } from "~/components/localized-link";
+
+export const useLocalizedNavigate = () => {
+  const navigate = useNavigate();
   const { locale } = useLocale();
 
-  return <Navigate replace to={locale} />;
-}
+  const localisedNavigate = (to: To, options?: NavigateOptions) => {
+    const localedTo = locacalizeTo(to, locale);
+
+    navigate(localedTo, options);
+  };
+
+  return localisedNavigate;
+};
 ```
 
+### Step 8: Utilise Intlayer in Your Pages
+
+Access your content dictionaries throughout your application:
+
 #### Localised Home Page
 
-```tsx fileName="app/routes/[lang]/page.tsx" codeFormat="typescript"
-import { useIntlayer } from "react-intlayer";
-import LocalizedLink from "~/components/localized-link";
+```tsx fileName="app/routes/[lang]/page.tsx"
+import { useIntlayer } from "intlayer";
+import { LocalizedLink } from "~/components/localized-link";
 
 export default function Page() {
-  const content = useIntlayer("page");
+  const { title, description, aboutLink } = useIntlayer("page");
 
   return (
-    <div style={{ padding: "2rem", textAlign: "center" }}>
-      <h1>{content.title}</h1>
-      <p>{content.description}</p>
-      <nav style={{ marginTop: "2rem" }}>
-        <LocalizedLink
-          to="/about"
-          style={{
-            display: "inline-block",
-            padding: "0.5rem 1rem",
-            backgroundColor: "#007bff",
-            colour: "white",
-            textDecoration: "none",
-            borderRadius: "4px",
-          }}
-        >
-          {content.aboutLink}
-        </LocalizedLink>
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+      <nav>
+        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
       </nav>
     </div>
   );
@@ -323,43 +305,58 @@ export default function Page() {
 
 Create a component to allow users to change languages:
 
-```tsx fileName="app/components/locale-switcher.tsx" codeFormat="typescript"
-import { getLocalizedUrl, getLocaleName } from "intlayer";
-import { useLocale } from "react-intlayer";
-import { useLocation, useNavigate } from "react-router";
+```tsx fileName="app/components/locale-switcher.tsx"
+import type { FC } from "react";
 
-export default function LocaleSwitcher() {
-  const { locale, availableLocales, setLocale } = useLocale();
-  const location = useLocation();
-  const navigate = useNavigate();
+import {
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+  getPathWithoutLocale,
+} from "intlayer";
+import { setLocaleCookie, useIntlayer, useLocale } from "react-intlayer";
+import { Link, useLocation } from "react-router";
 
-  const handleLocaleChange = (newLocale: string) => {
-    const localizedUrl = getLocalizedUrl(
-      location.pathname + location.search,
-      newLocale
-    );
-    setLocale(newLocale);
-    navigate(localizedUrl);
-  };
+export const LocaleSwitcher: FC = () => {
+  const { localeSwitcherLabel } = useIntlayer("locale-switcher");
+  const { pathname } = useLocation();
+
+  const { availableLocales, locale } = useLocale();
+
+  const pathWithoutLocale = getPathWithoutLocale(pathname);
 
   return (
-    <div style={{ margin: "1rem 0" }}>
-      <label htmlFor="locale-select">Choose Language: </label>
-      <select
-        id="locale-select"
-        value={locale}
-        onChange={(e) => handleLocaleChange(e.target.value)}
-        style={{ padding: "0.25rem", marginLeft: "0.5rem" }}
-      >
-        {availableLocales.map((availableLocale) => (
-          <option key={availableLocale} value={availableLocale}>
-            {getLocaleName(availableLocale)}
-          </option>
-        ))}
-      </select>
-    </div>
+    <ol>
+      {availableLocales.map((localeItem) => (
+        <li key={localeItem}>
+          <Link
+            aria-current={localeItem === locale ? "page" : undefined}
+            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
+            onClick={() => setLocaleCookie(localeItem)}
+            to={getLocalizedUrl(pathWithoutLocale, 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>
+          </Link>
+        </li>
+      ))}
+    </ol>
   );
-}
+};
 ```
 
 > 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).
@@ -368,8 +365,7 @@ export default function LocaleSwitcher() {
 
 Create a hook to manage HTML lang and dir attributes:
 
-```tsx fileName="app/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
-// app/hooks/useI18nHTMLAttributes.tsx
+```tsx fileName="app/hooks/useI18nHTMLAttributes.tsx"
 import { getHTMLTextDir } from "intlayer";
 import { useEffect } from "react";
 import { useLocale } from "react-intlayer";
@@ -386,8 +382,7 @@ export const useI18nHTMLAttributes = () => {
 
 Then use it in your root component:
 
-```tsx fileName="app/root.tsx" codeFormat="typescript"
-// app/routes/layout.tsx
+```tsx fileName="app/routes/layout.tsx"
 import { Outlet } from "react-router";
 import { IntlayerProvider } from "react-intlayer";
 
@@ -404,35 +399,26 @@ export default function RootLayout() {
 }
 ```
 
-### Step 11: Build and Run Your Application
+### Step 11: Add middleware (Optional)
 
-Build the content dictionaries and run your application:
+You can also use the `intlayerMiddleware` 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.
 
-```bash packageManager="npm"
-# Build Intlayer dictionaries
-npm run intlayer:build
-
-# Start development server
-npm run dev
-```
+> Note that to use the `intlayerMiddleware` in production, you need to switch the `vite-intlayer` package from `devDependencies` to `dependencies`.
 
-```bash packageManager="pnpm"
-# Build Intlayer dictionaries
-pnpm intlayer:build
+```typescript {3,7} fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import { intlayer, intlayerMiddleware } from "vite-intlayer";
 
-# Start development server
-pnpm dev
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react(), intlayer(), intlayerMiddleware()],
+});
 ```
 
-```bash packageManager="yarn"
-# Build Intlayer dictionaries
-yarn intlayer:build
-
-# Start development server
-yarn dev
-```
+---
 
-### Step 12: Configure TypeScript (Optional)
+## Configure TypeScript
 
 Intlayer uses module augmentation to benefit from TypeScript and strengthen your codebase.
 
@@ -440,9 +426,7 @@ Ensure your TypeScript configuration includes the autogenerated types:
 
 ```json5 fileName="tsconfig.json"
 {
-  compilerOptions: {
-    // ... your existing TypeScript configurations
-  },
+  // ... your existing configurations
   include: [
     // ... your existing includes
     ".intlayer/**/*.ts", // Include the auto-generated types
@@ -450,7 +434,9 @@ Ensure your TypeScript configuration includes the autogenerated types:
 }
 ```
 
-### Git Configuration
+---
+
+## Git Configuration
 
 It is recommended to ignore the files generated by Intlayer. This prevents you from committing them to your Git repository.
 
@@ -463,35 +449,6 @@ To do this, you can add the following instructions to your `.gitignore` file:
 
 ---
 
-## Production Deployment
-
-When deploying your application:
-
-1. **Build your application:**
-
-   ```bash
-   npm run build
-   ```
-
-2. **Build Intlayer dictionaries:**
-
-   ```bash
-   npm run intlayer:build
-   ```
-
-3. **Move `vite-intlayer` to dependencies** if using middleware in production:
-   ```bash
-   npm install vite-intlayer --save
-   ```
-
-Your application will now support:
-
-- **URL Structure**: `/en`, `/en/about`, `/tr`, `/tr/about`
-- **Automatic locale detection** based on browser preferences
-- **Locale-aware routing** with React Router v7
-- **TypeScript support** with auto-generated types
-- **Server-side rendering** with proper locale handling
-
 ## VS Code Extension
 
 To enhance your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
@@ -511,7 +468,7 @@ For more details on how to use the extension, refer to the [Intlayer VS Code Ext
 
 ## Go Further
 
-To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/intlayer_visual_editor.md) or externalise your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/intlayer_CMS.md).
+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).
 
 ---
 
@@ -519,15 +476,9 @@ To go further, you can implement the [visual editor](https://github.com/aymericz
 
 - [Intlayer Documentation](https://intlayer.org)
 - [React Router v7 Documentation](https://reactrouter.com/)
-- [useIntlayer hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/packages/react-intlayer/useIntlayer.md)
-- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/packages/react-intlayer/useLocale.md)
-- [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/dictionary/get_started.md)
-- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/configuration.md)
+- [useIntlayer hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md)
+- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md)
+- [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/get_started.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)
 
 This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalised application with locale-aware routing and TypeScript support.
-
-## Doc History
-
-| Version | Date      | Changes                   |
-| ------- | --------- | ------------------------- |
-| 5.8.2   | 2025-09-4 | Added for React Router v7 |