@intlayer/docs 5.8.1 → 6.0.0-canary.1

package/docs/en/intlayer_with_tanstack.md

@@ -1,364 +1,435 @@
 ---
-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, localized 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 internationalization (i18n) to your Tanstack Start application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
 keywords:
   - Internationalization
   - 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 Internationalizing (i18n) with Intlayer and TanStack Start (React)
+# Getting Started Internationalizing (i18n) with Intlayer and Tanstack Start
+
+This guide demonstrates how to integrate **Intlayer** for seamless internationalization 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 internationalization (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 + dev DX.
+With Intlayer, you can:
 
-This guide shows how to wire 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 localize metadata**, routes, and content.
+- **Ensure TypeScript support** with autogenerated types, improving autocompletion and error detection.
+- **Benefit from advanced features**, like dynamic locale detection and switching.
+- **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 (config, dictionaries, CLI/transforms).
-- **react-intlayer**: `<IntlayerProvider>` + hooks for React.
-- **vite-intlayer**: Vite plugin, plus optional middleware for locale detection/redirects (works in dev & 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 internationalization 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 application. It provides context providers and hooks for React internationalization.
+
+- **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 3: Configuration of your project
 
-## Step 2: Configure Intlayer
+Create a config file to configure the languages of your application:
 
-Create `intlayer.config.ts` at your project root:
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
 
-```ts fileName="intlayer.config.ts"
-import { Locales, 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";
 
-> Full config reference: see Intlayer’s configuration docs.
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+  },
+};
 
----
+export default config;
+```
 
-## Step 3: Add the Vite Plugin (and optional middleware)
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
 
-**TanStack Start uses Vite**, so add Intlayer’s plugin(s) to your `vite.config.ts`:
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    defaultLocale: Locales.ENGLISH,
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+  },
+};
 
-```ts fileName="vite.config.ts"
+module.exports = config;
+```
+
+> Through this configuration file, you can set up localized URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+
+### 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 optimize performance.
 
----
+### Step 5: Create Layout Components
 
-## Step 4: Declare Your Content
+Set up your root layout and locale-specific layouts:
 
-Place your dictionaries anywhere under `./src` (default `contentDir`). Example:
+#### Root Layout
 
-```tsx fileName="src/app.content.tsx"
-import { t, type Dictionary } from "intlayer";
-import type { ReactNode } from "react";
+```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>
+  );
+}
+```
+
+### Step 6: Declare Your Content
+
+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: "Vite logo", fr: "Logo Vite", es: "Logo Vite" }),
-    reactLogo: t({ en: "React logo", fr: "Logo React", es: "Logo React" }),
+    links: {
+      about: t({
+        en: "About",
+        es: "Acerca de",
+        fr: "À propos",
+      }),
+      home: t({
+        en: "Home",
+        es: "Inicio",
+        fr: "Accueil",
+      }),
+    },
+    meta: {
+      description: t({
+        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: "TanStack Start + React",
-      fr: "TanStack Start + React",
-      es: "TanStack Start + React",
-    }),
-    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),
-    edit: t<ReactNode>({
-      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: "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: "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 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}`).
 
-> 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/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`, …) need `.value`:
->
-> ```jsx
-> <img alt={c.reactLogo.value} />
-> ```
+Create a `useLocalizedNavigate` hook for programmatic navigation:
 
----
-
-## (Optional) Step 6: Locale Switching (Client)
-
-```tsx fileName="src/components/LocaleSwitcher.tsx"
-import { Locales } from "intlayer";
+```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";
 
-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>
-  );
-}
-```
+type LocalizedNavigateOptions = {
+  to: string;
+} & Omit<NavigateOptions, "to">;
 
----
+export const useLocalizedNavigate = () => {
+  const navigate = useNavigate();
+  const { locale } = useLocale();
 
-## (Optional) Step 7: Localized Routing (SEO-friendly URLs)
+  const isExternal = (to: string) => {
+    return /^(https?:)?\/\//.test(to);
+  };
 
-You have **two good patterns** with TanStack Start. Pick one.
+  const localizedNavigate = (options: LocalizedNavigateOptions) => {
+    const to = isExternal(options.to)
+      ? options.to
+      : getLocalizedUrl(options.to, locale);
 
-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.
+    navigate({ ...options, to: to as NavigateOptions["to"] });
+  };
 
----
+  return localizedNavigate;
+};
+```
+
+### Step 8: Utilize Intlayer in Your Pages
 
-## (Optional) Step 8: Update the URL when switching locale
+Access your content dictionaries throughout your application:
 
-With Pattern A (basepath), switching locales means **navigating to a different basepath**:
+#### Root Redirect Page
 
-```tsx fileName="src/components/LocaleSwitcherNavigate.tsx"
-import { useRouter } from "@tanstack/react-router";
-import { Locales, getLocalizedUrl } from "intlayer";
+```tsx fileName="src/routes/page.tsx" codeFormat="typescript"
+// src/routes/page.tsx
 import { useLocale } from "react-intlayer";
+import { Navigate } from "react-router";
 
-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);
-  };
+export default function Page() {
+  const { locale } = useLocale();
 
-  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>
-  );
+  return <Navigate replace to={locale} />;
 }
 ```
 
----
+#### Localized Home Page
 
-## (Optional) Step 9: `<html lang>` and `dir` (TanStack Start Document)
+```tsx fileName="src/routes/{-$locale}/index.tsx" codeFormat="typescript"
+import { createFileRoute } from "@tanstack/react-router";
+import { getIntlayer } from "intlayer";
+import { useIntlayer } from "react-intlayer";
 
-TanStack Start exposes a **Document** (root HTML shell) you can customize. Set `lang` and `dir` for accessibility/SEO:
+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" },
+      ],
+    };
+  },
+});
 
-```tsx fileName="src/routes/__root.tsx" {4,15}
-import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
-import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
+function RouteComponent() {
+  const content = useIntlayer("app");
+  const navigate = useLocalizedNavigate();
 
-import Header from "../components/Header";
+  return (
+    <div className="grid place-items-center h-screen">
+      <div className="flex flex-col gap-4 items-center text-center">
+        {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>
+  );
+}
+```
 
-import { IntlayerProvider } from "react-intlayer";
-import appCss from "../styles.css?url";
+> To Learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useIntlayer.md).
 
-export const Route = createRootRoute({
-  head: () => ({
-    meta: [
-      {
-        charSet: "utf-8",
-      },
-      {
-        name: "viewport",
-        content: "width=device-width, initial-scale=1",
-      },
-      {
-        title: "TanStack Start Starter",
-      },
-    ],
-    links: [
-      {
-        rel: "stylesheet",
-        href: appCss,
-      },
-    ],
-  }),
+### Step 9: Create a Locale Switcher Component
 
-  shellComponent: RootDocument,
-});
+Create a component to allow users to change languages:
+
+```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 RootDocument({ children }: { children: React.ReactNode }) {
   return (
-    <IntlayerProvider>
-      <html lang="en">
-        <head>
-          <HeadContent />
-        </head>
-        <body>
-          <Header />
-          {children}
-          <TanStackRouterDevtools />
-          <Scripts />
-        </body>
-      </html>
-    </IntlayerProvider>
+    <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>
   );
 }
 ```
 
-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/packages/react-intlayer/useLocale.md).
 
-```tsx fileName="src/hooks/useI18nHTMLAttributes.ts"
+### Step 10: Add HTML Attributes Management (Optional)
+
+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);
@@ -366,87 +437,185 @@ export const useI18nHTMLAttributes = () => {
 };
 ```
 
----
+Then use it in your root component:
 
-## (Optional) Step 10: Localized 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 get benefits of TypeScript and make your codebase stronger.
+
+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 allows you to avoid committing them to your Git repository.
 
-Ignore Intlayer’s generated artifacts:
+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/intlayer_visual_editor.md) or externalize your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/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/packages/react-intlayer/useIntlayer.md)
+- [useLocale hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/useLocale.md)
+- [Content Declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/get_started.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+
+This comprehensive guide provides everything you need to integrate Intlayer with Tanstack Start for a fully internationalized 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 |