@intlayer/docs 5.8.1-canary.0 → 6.0.0-canary.0

package/docs/en-GB/intlayer_with_tanstack.md

@@ -1,369 +1,438 @@
 ---
-createdAt: 2025-08-11
-updatedAt: 2025-08-11
-title: Getting Started with Intlayer in TanStack Start (React)
-description: Add i18n to your TanStack Start app using Intlayer-component-level dictionaries, localised URLs, and SEO-friendly metadata.
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Getting Started with Intlayer in Tanstack Start
+description: Learn how to add internationalisation (i18n) to your Tanstack Start application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
 keywords:
   - Internationalisation
   - Documentation
   - Intlayer
-  - TanStack Start
-  - TanStack Router
+  - Tanstack Start
   - React
   - i18n
-  - JavaScript
+  - TypeScript
+  - Locale Routing
 slugs:
   - doc
   - environment
+  - vite-and-react
   - tanstack-start
+applicationTemplate: https://github.com/AydinTheFirst/tanstack-start-intlayer
+author: AydinTheFirst
 ---
 
-# Getting Started Internationalising (i18n) with Intlayer and TanStack Start (React)
+# Getting Started Internationalising (i18n) with Intlayer and Tanstack Start
+
+This guide demonstrates how to integrate **Intlayer** for seamless internationalisation in Tanstack Start projects with locale-aware routing, TypeScript support, and modern development practices.
 
 ## What is Intlayer?
 
-**Intlayer** is an open-source i18n toolkit for React apps. It gives you:
+**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications.
 
-- **Component-local dictionaries** with TypeScript safety.
-- **Dynamic metadata & routes** (SEO-ready).
-- **Runtime locale switching** (and helpers to detect/persist locales).
-- **Vite plugin** for build-time transforms + developer experience (DX).
+With Intlayer, you can:
 
-This guide shows how to integrate Intlayer into a **TanStack Start** project (which uses Vite under the hood and TanStack Router for routing/SSR).
+- **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.
+- **Enable locale-aware routing** with Tanstack Start's file-based routing system.
 
 ---
 
-## Step 1: Install Dependencies
+## Step-by-Step Guide to Set Up Intlayer in a Tanstack Start Application
 
-```bash
-# npm
-npm i intlayer react-intlayer
-npm i -D vite-intlayer
+### Step 1: Create Project
 
-# pnpm
-pnpm add intlayer react-intlayer
-pnpm add -D vite-intlayer
+Start by creating a new TanStack Start project by following the [Start new project](https://tanstack.com/start/latest/docs/framework/react/quick-start) guide on the TanStack Start website.
+
+### Step 2: Install Intlayer Packages
 
-# yarn
-yarn add intlayer react-intlayer
-yarn add -D vite-intlayer
+Install the necessary packages using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer react-intlayer
+npm install vite-intlayer --save-dev
 ```
 
-- **intlayer**: core (configuration, dictionaries, CLI/transforms).
-- **react-intlayer**: `<IntlayerProvider>` + hooks for React.
-- **vite-intlayer**: Vite plugin, plus optional middleware for locale detection/redirects (works in development & SSR/preview; move to `dependencies` for production SSR).
+```bash packageManager="pnpm"
+pnpm add intlayer react-intlayer
+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/dictionary/get_started.md), transpilation, and [CLI commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md).
+
+- **react-intlayer**
+  The package that integrates Intlayer with React applications. It provides context providers and hooks for React internationalisation.
 
-## Step 2: Configure Intlayer
+- **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.
 
-Create `intlayer.config.ts` at your project root:
+### Step 3: Configuration of your project
 
-```ts fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
+Create a config file to configure the languages of your application:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+import { Locales } from "intlayer";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
   },
-  // You can also tweak: contentDir, contentFileExtensions, middleware options, etc.
 };
 
 export default config;
 ```
 
-CommonJS/ESM variants are identical to your original doc if you prefer `cjs`/`mjs`.
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+  },
+};
 
-> Full config reference: see Intlayer’s configuration docs.
+export default config;
+```
 
----
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
 
-## Step 3: Add the Vite Plugin (and optional middleware)
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+  },
+};
+
+module.exports = config;
+```
 
-**TanStack Start uses Vite**, so add Intlayer’s plugin(s) to your `vite.config.ts`:
+> 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).
 
-```ts fileName="vite.config.ts"
+### Step 4: Integrate Intlayer in Your Vite Configuration
+
+Add the intlayer plugin into your configuration:
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react-swc";
-import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";
+import tsconfigPaths from "vite-tsconfig-paths";
 
 export default defineConfig({
   plugins: [
-    react(),
+    reactRouter(),
+    tsconfigPaths(),
     intlayerPlugin(),
-    // Optional but recommended for locale detection, cookies & redirects:
-    intLayerMiddlewarePlugin(),
+    intlayerMiddlewarePlugin(),
   ],
 });
 ```
 
-> If you deploy SSR, move `vite-intlayer` to `dependencies` so the middleware runs in production.
+> 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 5: Create Layout Components
+
+Set up your root layout and locale-specific layouts:
+
+#### Root Layout
 
-## Step 4: Declare Your Content
+```tsx fileName="src/routes/{-$locale}/route.tsx" codeFormat="typescript"
+// src/routes/{-$locale}/route.tsx
+import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";
+import { configuration } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";
+
+export const Route = createFileRoute("/{-$locale}")({
+  component: LayoutComponent,
+});
+
+function LayoutComponent() {
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
 
-Place your dictionaries anywhere under `./src` (default `contentDir`). Example:
+### Step 6: Declare Your Content
 
-```tsx fileName="src/app.content.tsx"
-import { t, type Dictionary } from "intlayer";
-import type { ReactNode } from "react";
+Create and manage your content declarations to store translations:
+
+```tsx fileName="src/contents/page.content.ts" contentDeclarationFormat="typescript"
+import type { Dictionary } from "intlayer";
+
+import { t } from "intlayer";
 
 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",
-    }),
+    links: {
+      about: t({
+        en: "About",
+        es: "Acerca de",
+        fr: "À propos",
+      }),
+      home: t({
+        "en-GB": "Home",
+        en: "Home",
+        es: "Inicio",
+        fr: "Accueil",
+      }),
+    },
+    meta: {
+      description: t({
+        "en-GB": "This is an example of using Intlayer with TanStack Router",
+        en: "This is an example of using Intlayer with TanStack Router",
+        es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
+        fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
+      }),
+    },
     title: t({
-      "en-GB": "TanStack Start + React",
-      en: "TanStack Start + React",
-      fr: "TanStack Start + React",
-      es: "TanStack Start + 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/routes/index.tsx</code> and save to test HMR
-        </>
-      ),
-      en: (
-        <>
-          Edit <code>src/routes/index.tsx</code> and save to test HMR
-        </>
-      ),
-      fr: (
-        <>
-          Éditez <code>src/routes/index.tsx</code> et enregistrez pour tester
-          HMR
-        </>
-      ),
-      es: (
-        <>
-          Edita <code>src/routes/index.tsx</code> y guarda para probar HMR
-        </>
-      ),
-    }),
-    readTheDocs: t({
-      "en-GB": "Click the logos to learn more",
-      en: "Click the logos to learn more",
-      fr: "Cliquez sur les logos pour en savoir plus",
-      es: "Haz clic en los logotipos para saber más",
+      "en-GB": "Welcome to Intlayer + TanStack Router",
+      en: "Welcome to Intlayer + TanStack Router",
+      es: "Bienvenido a Intlayer + TanStack Router",
+      fr: "Bienvenue à Intlayer + TanStack Router",
     }),
   },
+  key: "app",
 } satisfies Dictionary;
 
 export default appContent;
 ```
 
-JSON/ESM/CJS variants work the same as in your original doc.
+> 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}`).
 
-> TSX content? Don’t forget `import React from "react"` if your setup needs it.
+> For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/get_started.md).
 
----
+### Step 7: Create Locale-Aware Components and Hooks
 
-## Step 5: Wrap TanStack Start with Intlayer
+Create a `LocalizedLink` component for locale-aware navigation:
 
-With TanStack Start, your **root route** is the right place to set providers.
+```tsx fileName="src/components/localized-link.tsx" codeFormat="typescript"
+// src/components/localized-link.tsx
+// eslint-disable-next-line no-restricted-imports
+import { Link, type LinkProps } from "@tanstack/react-router";
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
 
-```tsx fileName="src/routes/__root.tsx"
-import {
-  Outlet,
-  createRootRoute,
-  Link as RouterLink,
-} from "@tanstack/react-router";
-import { IntlayerProvider, useIntlayer } from "react-intlayer";
-
-function AppShell() {
-  // Example of using a dictionary at the top level:
-  const content = useIntlayer("app");
+type LocalizedLinkProps = {
+  to: string;
+} & Omit<LinkProps, "to">;
 
-  return (
-    <div>
-      <nav className="flex gap-3 p-3">
-        <RouterLink to="/">Home</RouterLink>
-        <RouterLink to="/about">About</RouterLink>
-      </nav>
-      <main className="p-6">
-        <h1>{content.title}</h1>
-        <Outlet />
-      </main>
-    </div>
-  );
-}
+export function LocalizedLink(props: LocalizedLinkProps) {
+  const { locale } = useLocale();
 
-export const Route = createRootRoute({
-  component: () => (
-    <IntlayerProvider>
-      <AppShell />
-    </IntlayerProvider>
-  ),
-});
-```
+  const isExternal = (to: string) => {
+    return /^(https?:)?\/\//.test(to);
+  };
 
-Then use your content in pages:
+  const to = isExternal(props.to)
+    ? props.to
+    : getLocalizedUrl(props.to, locale);
 
-```tsx fileName="src/routes/index.tsx"
-import { createFileRoute } from "@tanstack/react-router";
-import { useIntlayer } from "react-intlayer";
-import reactLogo from "../assets/react.svg";
-
-export const Route = createFileRoute("/")({
-  component: () => {
-    const content = useIntlayer("app");
-    return (
-      <>
-        <button>{content.count}0</button>
-        <p>{content.edit}</p>
-        <img
-          src={reactLogo}
-          alt={content.reactLogo.value}
-          width={48}
-          height={48}
-        />
-        <p className="opacity-70">{content.readTheDocs}</p>
-      </>
-    );
-  },
-});
+  return <Link {...props} to={to as LinkProps["to"]} />;
+}
 ```
 
-> String attributes (`alt`, `title`, `aria-label`, …) require `.value`:
->
-> ```jsx
-> <img alt={c.reactLogo.value} />
-> ```
+Create a `useLocalizedNavigate` hook for programme navigation:
 
----
+```tsx fileName="src/hooks/useLocalizedNavigate.tsx" codeFormat="typescript"
+// src/hooks/useLocalizedNavigate.tsx
+// eslint-disable-next-line no-restricted-imports
+import { NavigateOptions, useNavigate } from "@tanstack/react-router";
+import { getLocalizedUrl } from "intlayer";
+import { useLocale } from "react-intlayer";
 
-## (Optional) Step 6: Locale Switching (Client)
+type LocalizedNavigateOptions = {
+  to: string;
+} & Omit<NavigateOptions, "to">;
 
-```tsx fileName="src/components/LocaleSwitcher.tsx"
-import { Locales } from "intlayer";
-import { useLocale } from "react-intlayer";
+export const useLocalizedNavigate = () => {
+  const navigate = useNavigate();
+  const { locale } = useLocale();
 
-export function LocaleSwitcher() {
-  const { setLocale } = useLocale();
-  return (
-    <div className="flex gap-2">
-      <button onClick={() => setLocale(Locales.ENGLISH)}>English</button>
-      <button onClick={() => setLocale(Locales.FRENCH)}>Français</button>
-      <button onClick={() => setLocale(Locales.SPANISH)}>Español</button>
-    </div>
-  );
-}
+  const isExternal = (to: string) => {
+    return /^(https?:)?\/\//.test(to);
+  };
+
+  const localizedNavigate = (options: LocalizedNavigateOptions) => {
+    const to = isExternal(options.to)
+      ? options.to
+      : getLocalizedUrl(options.to, locale);
+
+    navigate({ ...options, to: to as NavigateOptions["to"] });
+  };
+
+  return localizedNavigate;
+};
 ```
 
----
+### Step 8: Utilise Intlayer in Your Pages
 
-## (Optional) Step 7: Localised Routing (SEO-friendly URLs)
+Access your content dictionaries throughout your application:
 
-You have **two good patterns** with TanStack Start. Pick one.
+#### Root Redirect Page
 
-Create a dynamic segment folder `src/routes/$locale/` so your URLs are `/:locale/...`. In the `$locale` layout, validate the `params.locale`, set `<IntlayerProvider locale=...>`, and render an `<Outlet />`. This approach is straightforward, but you’ll mount the rest of your routes beneath `$locale`, and you’ll need an extra non-prefixed tree if you _don’t_ want the default locale prefixed.
+```tsx fileName="src/routes/page.tsx" codeFormat="typescript"
+// src/routes/page.tsx
+import { useLocale } from "react-intlayer";
+import { Navigate } from "react-router";
 
----
+export default function Page() {
+  const { locale } = useLocale();
 
-## (Optional) Step 8: Update the URL when switching locale
+  return <Navigate replace to={locale} />;
+}
+```
 
-With Pattern A (basepath), switching locales means **navigating to a different basepath**:
+#### Localised Home Page
 
-```tsx fileName="src/components/LocaleSwitcherNavigate.tsx"
-import { useRouter } from "@tanstack/react-router";
-import { Locales, getLocalizedUrl } from "intlayer";
-import { useLocale } from "react-intlayer";
+```tsx fileName="src/routes/{-$locale}/index.tsx" codeFormat="typescript"
+import { createFileRoute } from "@tanstack/react-router";
+import { getIntlayer } from "intlayer";
+import { useIntlayer } from "react-intlayer";
 
-export function LocaleSwitcherNavigate() {
-  const router = useRouter();
-  const { locale, setLocale } = useLocale();
-
-  const change = async (next: Locales) => {
-    if (next === locale) return;
-    const nextPath = getLocalizedUrl(
-      window.location.pathname + window.location.search,
-      next
-    );
-    await router.navigate({ to: nextPath }); // preserves history
-    setLocale(next);
-  };
+import LocaleSwitcher from "@/components/locale-switcher";
+import { LocalizedLink } from "@/components/localized-link";
+import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: ({ params }) => {
+    const { locale } = params;
+    const metaContent = getIntlayer("app", locale);
+
+    return {
+      meta: [
+        { title: metaContent.title },
+        { content: metaContent.meta.description, name: "description" },
+      ],
+    };
+  },
+});
+
+function RouteComponent() {
+  const content = useIntlayer("app");
+  const navigate = useLocalizedNavigate();
 
   return (
-    <div className="flex gap-2">
-      <button onClick={() => change(Locales.ENGLISH)}>English</button>
-      <button onClick={() => change(Locales.FRENCH)}>Français</button>
-      <button onClick={() => change(Locales.SPANISH)}>Español</button>
+    <div className="grid place-items-center h-screen">
+      <div className="flex flex-col gap-4 items-center text-centre">
+        {content.title}
+        <LocaleSwitcher />
+        <div className="flex gap-4">
+          <a href="/">Index</a>
+          <LocalizedLink to="/">{content.links.home}</LocalizedLink>
+          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
+        </div>
+        <div className="flex gap-4">
+          <button onClick={() => navigate({ to: "/" })}>
+            {content.links.home}
+          </button>
+          <button onClick={() => navigate({ to: "/about" })}>
+            {content.links.about}
+          </button>
+        </div>
+      </div>
     </div>
   );
 }
 ```
 
----
+> 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 9: `<html lang>` and `dir` (TanStack Start Document)
+### Step 9: Create a Locale Switcher Component
 
-TanStack Start exposes a **Document** (root HTML shell) you can customise. Set `lang` and `dir` for accessibility/SEO:
+Create a component to allow users to change languages:
 
-```tsx fileName="src/routes/__root.tsx" {4,15}
-import { Outlet, createRootRoute } from "@tanstack/react-router";
-import { IntlayerProvider } from "react-intlayer";
-import { getHTMLTextDir } from "intlayer";
+```tsx fileName="src/components/locale-switcher.tsx" codeFormat="typescript"
+import { useLocation } from "@tanstack/react-router";
+import {
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+  Locales,
+} from "intlayer";
+import { useIntlayer, useLocale } from "react-intlayer";
+
+export default function LocaleSwitcher() {
+  const { pathname, searchStr } = useLocation();
+  const content = useIntlayer("locale-switcher");
+
+  const { availableLocales, locale, setLocale } = useLocale({
+    onLocaleChange: (newLocale) => {
+      const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale);
+      location.replace(pathWithLocale);
+    },
+  });
 
-function Document({
-  locale,
-  children,
-}: {
-  locale: string;
-  children: React.ReactNode;
-}) {
   return (
-    <html lang={locale} dir={getHTMLTextDir(locale)}>
-      <head>
-        <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
-        {/* ... */}
-      </head>
-      <body>{children}</body>
-    </html>
+    <select
+      aria-label={content.label.toString()}
+      onChange={(e) => setLocale(e.target.value)}
+      value={locale}
+    >
+      {availableLocales.map((localeItem) => (
+        <option
+          dir={getHTMLTextDir(localeItem)}
+          key={localeItem}
+          lang={localeItem}
+          value={localeItem}
+        >
+          {/* Example: Français (French) */}
+          {getLocaleName(localeItem, locale)} (
+          {getLocaleName(localeItem, Locales.ENGLISH)})
+        </option>
+      ))}
+    </select>
   );
 }
-
-export const Route = createRootRoute({
-  component: () => (
-    <IntlayerProvider>
-      {/* If you compute locale on server, pass it into Document; otherwise client will correct post-hydration */}
-      <Document locale={document?.documentElement?.lang || "en-GB"}>
-        <Outlet />
-      </Document>
-    </IntlayerProvider>
-  ),
-});
 ```
 
-For client-side correction, you can also keep your small hook:
+> 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).
+
+### Step 10: Add HTML Attributes Management (Optional)
 
-```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx"
+Create a hook to manage HTML lang and dir attributes:
+
+```tsx fileName="src/hooks/useI18nHTMLAttributes.tsx" codeFormat="typescript"
+// src/hooks/useI18nHTMLAttributes.tsx
+import { getHTMLTextDir } from "intlayer";
 import { useEffect } from "react";
 import { useLocale } from "react-intlayer";
-import { getHTMLTextDir } from "intlayer";
 
 export const useI18nHTMLAttributes = () => {
   const { locale } = useLocale();
+
   useEffect(() => {
     document.documentElement.lang = locale;
     document.documentElement.dir = getHTMLTextDir(locale);
@@ -371,87 +440,185 @@ export const useI18nHTMLAttributes = () => {
 };
 ```
 
----
+Then use it in your root component:
 
-## (Optional) Step 10: Localised Link component
+```tsx fileName="src/routes/{-$locale}/index.tsx" codeFormat="typescript"
+import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";
+import { configuration } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
 
-TanStack Router provides a `<Link/>`, but if you ever need a plain `<a>` that auto-prefixes internal URLs:
+import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // import the hook
 
-```tsx fileName="src/components/Link.tsx"
-import { getLocalizedUrl } from "intlayer";
-import {
-  forwardRef,
-  type AnchorHTMLAttributes,
-  type DetailedHTMLProps,
-} from "react";
-import { useLocale } from "react-intlayer";
+export const Route = createFileRoute("/{-$locale}")({
+  component: LayoutComponent,
+});
 
-export interface LinkProps
-  extends DetailedHTMLProps<
-    AnchorHTMLAttributes<HTMLAnchorElement>,
-    HTMLAnchorElement
-  > {}
-
-const isExternal = (href?: string) => /^https?:\/\//.test(href ?? "");
-
-export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
-  ({ href, children, ...props }, ref) => {
-    const { locale } = useLocale();
-    const hrefI18n =
-      href && !isExternal(href) ? getLocalizedUrl(href, locale) : href;
-    return (
-      <a href={hrefI18n} ref={ref} {...props}>
-        {children}
-      </a>
-    );
-  }
-);
-Link.displayName = "Link";
+function LayoutComponent() {
+  useI18nHTMLAttributes(); // add this line
+
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
 ```
 
-> If you use Pattern A (basepath), TanStack’s `<Link to="/about" />` already resolves to `/fr/about` via `basepath`, so a custom link is optional.
+### Step 11: Build and Run Your Application
 
----
+Build the content dictionaries and run your application:
 
-## TypeScript
+```bash packageManager="npm"
+# Build Intlayer dictionaries
+npm run intlayer:build
 
-Include Intlayer’s generated types:
+# Start development server
+npm run dev
+```
+
+```bash packageManager="pnpm"
+# Build Intlayer dictionaries
+pnpm intlayer:build
+
+# Start development server
+pnpm dev
+```
+
+```bash packageManager="yarn"
+# Build Intlayer dictionaries
+yarn intlayer:build
+
+# Start development server
+yarn dev
+```
+
+### Step 12: Configure TypeScript (Optional)
+
+Intlayer uses module augmentation to gain the benefits of TypeScript and strengthen your codebase.
+
+Ensure your TypeScript configuration includes the autogenerated types:
 
 ```json5 fileName="tsconfig.json"
 {
-  "include": ["src", ".intlayer/**/*.ts"],
+  compilerOptions: {
+    // ... your existing TypeScript configurations
+  },
+  include: [
+    // ... your existing includes
+    ".intlayer/**/*.ts", // Include the auto-generated types
+  ],
 }
 ```
 
----
+### Git Configuration
 
-## Git
+It is recommended to ignore the files generated by Intlayer. This prevents you from committing them to your Git repository.
 
-Ignore Intlayer’s generated artefacts:
+To do this, you can add the following instructions to your `.gitignore` file:
 
-```gitignore
+```plaintext fileName=".gitignore"
+# Ignore the files generated by Intlayer
 .intlayer
 ```
 
 ---
 
+### Step 13: Create Redirection (Optional)
+
+```typescript fileName="src/routes/{-$locale}/rotue.tsx" codeFormat="typescript"
+function LayoutComponent() {
+  useI18nHTMLAttributes();
+
+  const { locale } = Route.useParams();
+  const { locale: selectedLocale } = useLocale();
+  const { defaultLocale } = configuration.internationalization;
+  const { prefixDefault } = configuration.middleware;
+
+  // Redirect to the default locale if no locale is present in the URL when prefixDefault is true
+  if (selectedLocale === defaultLocale && !locale && prefixDefault) {
+    return <Navigate replace to={defaultLocale} />;
+  }
+
+  // Redirect to the selected locale if the locale in the URL does not match the selected locale
+  if (selectedLocale !== defaultLocale && !locale) {
+    return <Navigate replace to={selectedLocale} />;
+  }
+
+  return (
+    <IntlayerProvider locale={locale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+```
+
+## 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 Tanstack Start
+- **TypeScript support** with auto-generated types
+- **Server-side rendering** with proper locale handling
+
 ## VS Code Extension
 
-- **Intlayer VS Code Extension** → autocompletion, errors, inline previews, quick actions.
-  Marketplace: `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](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
 
-- Visual Editor
-- CMS mode
-- Locale detection on the edge / adapters
+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).
 
 ---
 
+## Documentation References
+
+- [Intlayer Documentation](https://intlayer.org)
+- [Tanstack Start Documentation](https://reactrouter.com/)
+- [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 Tanstack Start for a fully internationalised application with locale-aware routing and TypeScript support.
+
 ## Doc History
 
-| Version | Date       | Changes                         |
-| ------- | ---------- | ------------------------------- |
-| 1.0.0   | 2025-08-11 | TanStack Start adaptation added |
+| Version | Date       | Changes                  |
+| ------- | ---------- | ------------------------ |
+| 5.8.1   | 2025-09-09 | Added for Tanstack Start |