@intlayer/docs 7.5.11 → 7.5.13

package/docs/en-GB/intlayer_with_nextjs_no_locale_path.md

@@ -0,0 +1,1154 @@
+---
+createdAt: 2026-01-10
+updatedAt: 2026-01-10
+title: How to translate your Next.js 16 app (without [locale] in the page path) – i18n guide 2026
+description: Discover how to make your Next.js 16 website multilingual without [locale] in the page path. Follow the documentation to internationalise (i18n) and translate it.
+keywords:
+  - Internationalisation
+  - Documentation
+  - Intlayer
+  - Next.js 16
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - environment
+  - nextjs
+  - no-locale-path
+applicationTemplate: https://github.com/aymericzip/intlayer-next-no-lolale-path-template
+youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
+history:
+  - version: 1.0.0
+    date: 2026-01-10
+    changes: Initial release
+---
+
+# Translate your Next.js 16 site (without [locale] in the page path) using Intlayer | Internationalisation (i18n)
+
+<Tab defaultTab="video">
+  <TabItem label="Video" value="video">
+  
+<iframe title="The best i18n solution for Next.js? Discover Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
+
+  </TabItem>
+  <TabItem label="Code" value="code">
+
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-next-16-no-locale-path-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to internationalise your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </TabItem>
+</Tab>
+
+See [Application Template](https://github.com/aymericzip/intlayer-next-no-lolale-path-template) on GitHub.
+
+## Table of contents
+
+<TOC/>
+
+## What is Intlayer?
+
+**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications. Intlayer seamlessly integrates with the latest **Next.js 16** framework, including its powerful **App Router**. It is optimised to work with **Server Components** for efficient rendering and is fully compatible with [**Turbopack**](https://nextjs.org/docs/architecture/turbopack).
+
+With Intlayer, you can:
+
+- **Easily manage translations** using declarative dictionaries at the component level.
+- **Dynamically localise metadata, routes, and content.**
+- **Access translations in both client-side and server-side components.**
+- **Ensure TypeScript support** with auto-generated types, improving autocompletion and error detection.
+- **Benefit from advanced features**, like dynamic locale detection and switching.
+
+> Intlayer is compatible with Next.js 12, 13, 14, and 16. If you are using Next.js Page Router, you can refer to this [guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_page_router.md). For Next.js 12, 13, 14 with App Router, refer to this [guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_14.md).
+
+---
+
+## Step-by-Step Guide to Set Up Intlayer in a Next.js Application
+
+### Step 1: Install Dependencies
+
+Install the necessary packages using npm:
+
+```bash packageManager="npm"
+npm install intlayer next-intlayer
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer next-intlayer
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add intlayer next-intlayer
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add intlayer next-intlayer
+bunx intlayer init
+```
+
+- **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/content_file.md), transpilation, and [CLI commands](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/index.md).
+
+- **next-intlayer**
+
+  The package that integrates Intlayer with Next.js. It provides context providers and hooks for Next.js internationalisation. Additionally, it includes the Next.js plugin for integrating Intlayer with [Webpack](https://webpack.js.org/) or [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), as well as a proxy for detecting the user's preferred locale, managing cookies, and handling URL redirects.
+
+### Step 2: Configure Your Project
+
+Here is the final structure we will create:
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── layout.tsx
+│   │   ├── page.content.ts
+│   │   └── page.tsx
+│   ├── components
+│   │   ├── clientComponentExample
+│   │   │   ├── client-component-example.content.ts
+│   │   │   └── ClientComponentExample.tsx
+│   │   ├── localeSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   └── serverComponentExample
+│   │       ├── server-component-example.content.ts
+│   │       └── ServerComponentExample.tsx
+│   └── proxy.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+> If you do not want locale routing, intlayer can be used as a simple provider or hook. See [this guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/{{locale}}/intlayer_with_nextjs_no_locale_path.md) for more details.
+
+Create a config file to configure the languages used by 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,
+  },
+  routing: {
+    mode: "search-params", // or `no-prefix` — useful for middleware detection
+  },
+};
+
+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,
+  },
+  routing: {
+    mode: "search-params", // or `no-prefix` — useful for middleware detection
+  },
+};
+
+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,
+  },
+  routing: {
+    mode: "search-params", // or `no-prefix` - useful for middleware detection
+  },
+};
+
+module.exports = config;
+```
+
+> Through this configuration file, you can set up localised URLs, proxy 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 into your Next.js configuration
+
+Configure your Next.js setup to use Intlayer:
+
+```typescript fileName="next.config.ts" codeFormat="typescript"
+import type { NextConfig } from "next";
+import { withIntlayer } from "next-intlayer/server";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default withIntlayer(nextConfig);
+```
+
+```typescript fileName="next.config.mjs" codeFormat="esm"
+import { withIntlayer } from "next-intlayer/server";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* configuration options go here */
+};
+
+export default withIntlayer(nextConfig);
+```
+
+```typescript fileName="next.config.cjs" codeFormat="commonjs"
+const { withIntlayer } = require("next-intlayer/server");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* configuration options go here */
+};
+
+module.exports = withIntlayer(nextConfig);
+```
+
+> The `withIntlayer()` Next.js plugin is used to integrate Intlayer with Next.js. It builds content declaration files and watches them in development mode. It defines Intlayer environment variables within the [Webpack](https://webpack.js.org/) or [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) environments. Additionally, it provides aliases to optimise performance and ensures compatibility with server components.
+
+> The `withIntlayer()` function returns a promise. It allows you to prepare the Intlayer dictionaries before the build starts. If you want to use it with other plugins, you can await it. Example:
+>
+> ```ts
+> const nextConfig = await withIntlayer(nextConfig);
+> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
+>
+> export default nextConfigWithOtherPlugins;
+> ```
+>
+> If you want to use it synchronously, use the `withIntlayerSync()` function. For example:
+>
+> ```ts
+> const nextConfig = withIntlayerSync(nextConfig);
+> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
+>
+> export default nextConfigWithOtherPlugins;
+> ```
+>
+> Intlayer automatically detects whether your project is using **webpack** or **Turbopack** based on the command-line flags `--webpack`, `--turbo`, or `--turbopack`, as well as your current **Next.js version**.
+>
+> Since `next>=16`, if you are using **Rspack**, you must explicitly force Intlayer to use the webpack configuration by disabling Turbopack:
+>
+> ```ts
+> withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
+> ```
+
+### Step 4: Define dynamic locale routes
+
+Remove everything from `RootLayout` and replace it with the following code:
+
+```tsx {3} fileName="src/app/layout.tsx" codeFormat="typescript"
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async ({
+  params,
+}: LocalPromiseParams): Promise<Metadata> => {
+  const { locale } = await params;
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <IntlayerClientProvider defaultLocale={locale}>
+        <body>{children}</body>
+      </IntlayerClientProvider>
+    </html>
+  );
+};
+
+export default RootLayout;
+```
+
+```jsx {3} fileName="src/app/layout.mjx" codeFormat="esm"
+import "./globals.css";
+import { IntlayerClientProvider } from "next-intlayer";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async ({ params }) => {
+  const { locale } = await params;
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({ children }) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <IntlayerClientProvider defaultLocale={locale}>
+        <body>{children}</body>
+      </IntlayerClientProvider>
+    </html>
+  );
+};
+
+export default RootLayout;
+```
+
+```jsx {1,8} fileName="src/app/layout.csx" codeFormat="commonjs"
+require("./globals.css");
+const { IntlayerClientProvider } = require("next-intlayer");
+const { getHTMLTextDir, getIntlayer } = require("intlayer");
+const { getLocale } = require("next-intlayer/server");
+const { generateStaticParams } = require("next-intlayer");
+
+const generateMetadata = async ({ params }) => {
+  const { locale } = await params;
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({ children }) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <IntlayerClientProvider defaultLocale={locale}>
+        <body>{children}</body>
+      </IntlayerClientProvider>
+    </html>
+  );
+};
+
+module.exports = {
+  default: RootLayout,
+  generateStaticParams,
+  generateMetadata,
+};
+```
+
+### Step 5: Declare your content
+
+Create and manage your content declarations to store translations:
+
+```tsx fileName="src/app/metadata.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+import { Metadata } from "next";
+
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      "en-GB": "My Project Title",
+      en: "My Project Title",
+      fr: "Le Titre de mon Projet",
+      es: "El Título de mi Proyecto",
+    }),
+
+    description: t({
+      "en-GB":
+        "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
+      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
+    }),
+
+    keywords: t({
+      "en-GB": ["innovation", "productivity", "workflow", "SaaS"],
+      en: ["innovation", "productivity", "workflow", "SaaS"],
+      "en-GB": ["innovation", "productivity", "workflow", "SaaS"],
+      fr: ["innovation", "productivité", "flux de travail", "SaaS"],
+      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
+    }),
+  },
+} as Dictionary<Metadata>;
+
+export default metadataContent;
+```
+
+```tsx fileName="src/app/metadata.content.mjs" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      "en-GB": "My Project Title",
+      en: "My Project Title",
+      fr: "Le Titre de mon Projet",
+      es: "El Título de mi Proyecto",
+    }),
+
+    description: t({
+      "en-GB":
+        "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      "en-GB":
+        "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
+      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
+    }),
+
+    keywords: t({
+      "en-GB": ["innovation", "productivity", "workflow", "SaaS"],
+      en: ["innovation", "productivity", "workflow", "SaaS"],
+      fr: ["innovation", "productivité", "flux de travail", "SaaS"],
+      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
+    }),
+  },
+};
+
+export default metadataContent;
+```
+
+```javascript fileName="src/app/metadata.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      "en-GB": "My Project Title",
+      en: "My Project Title",
+      fr: "Le Titre de mon Projet",
+      es: "El Título de mi Proyecto",
+    }),
+
+    description: t({
+      "en-GB":
+        "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+      fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
+      es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
+    }),
+
+    keywords: t({
+      "en-GB": ["innovation", "productivity", "workflow", "SaaS"],
+      en: ["innovation", "productivity", "workflow", "SaaS"],
+      fr: ["innovation", "productivité", "flux de travail", "SaaS"],
+      es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
+    }),
+  },
+};
+
+module.exports = metadataContent;
+```
+
+```json fileName="src/app/metadata.content.json" contentDeclarationFormat="json"
+{
+  "key": "metadata",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "My Project Title",
+        "en": "My Project Title",
+        "fr": "Le Titre de mon Projet",
+        "es": "El Título de mi Proyecto"
+      }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+        "en": "Discover our innovative platform designed to streamline your workflow and boost productivity.",
+        "fr": "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
+        "es": "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad."
+      }
+    },
+    "keywords": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": ["innovation", "productivity", "workflow", "SaaS"],
+        "en": ["innovation", "productivity", "workflow", "SaaS"],
+        "fr": ["innovation", "productivité", "flux de travail", "SaaS"],
+        "es": ["innovación", "productividad", "flujo de trabajo", "SaaS"]
+      }
+    }
+  }
+}
+```
+
+```tsx fileName="src/app/page.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const pageContent = {
+  key: "page",
+  content: {
+    getStarted: {
+      main: t({
+        "en-GB": "Get started by editing",
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+  },
+} satisfies Dictionary;
+
+export default pageContent;
+```
+
+```javascript fileName="src/app/page.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const pageContent = {
+  key: "page",
+  content: {
+    getStarted: {
+      main: t({
+        "en-GB": "Get started by editing",
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+  },
+};
+
+export default pageContent;
+```
+
+```javascript fileName="src/app/page.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const pageContent = {
+  key: "page",
+  content: {
+    getStarted: {
+      main: t({
+        "en-GB": "Get started by editing",
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+  },
+};
+
+module.exports = pageContent;
+```
+
+```json fileName="src/app/page.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "page",
+  "content": {
+    "getStarted": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Get started by editing",
+        "en": "Get started by editing",
+        "fr": "Commencez par éditer",
+        "es": "Comience por editar"
+      }
+    },
+    "pageLink": "src/app/page.tsx"
+  }
+}
+```
+
+> Your content declarations can be defined anywhere in your application, provided they are placed in the `contentDir` directory (by default, `./src`) and use the content declaration file extensions (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/content_file.md).
+
+### Step 6: Utilise Content in Your Code
+
+Access your content dictionaries throughout your application:
+
+```tsx fileName="src/app/page.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
+import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
+import {
+  IntlayerServerProvider,
+  useIntlayer,
+  getLocale,
+} from "next-intlayer/server";
+import { NextPage } from "next";
+import { headers, cookies } from "next/headers";
+
+const PageContent: FC = () => {
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+
+const Page: NextPage = async () => {
+  const locale = await getLocale();
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <PageContent />
+      <ServerComponentExample />
+      <ClientComponentExample />
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```jsx fileName="src/app/page.mjx" codeFormat="esm"
+import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
+import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
+import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
+import { getLocale } from "intlayer";
+import { headers, cookies } from "next/headers";
+import { NextPage } from "next";
+
+const Page: NextPage = async () => {
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+
+const Page = async () => {
+
+  const locale = await getLocale();
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <PageContent />
+      <ServerComponentExample />
+      <ClientComponentExample />
+    </IntlayerServerProvider>
+  );
+};
+
+export default Page;
+```
+
+```jsx fileName="src/app/page.csx" codeFormat="commonjs"
+import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
+import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
+import { IntlayerServerProvider, useIntlayer, getLocale } from "next-intlayer/server";
+import { NextPage } from "next";
+import { headers, cookies } from "next/headers";
+
+const Page: NextPage = async () => {
+  const content = useIntlayer("page");
+
+  return (
+    <>
+      <p>{content.getStarted.main}</p>
+      <code>{content.getStarted.pageLink}</code>
+    </>
+  );
+};
+
+const Page: NextPage = async () => {
+  const locale = await getLocale();
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <PageContent />
+      <ServerComponentExample />
+      <ClientComponentExample />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+- **`IntlayerClientProvider`** is used to provide the locale to client-side components. It can be placed in any parent component, including the layout. However, placing it in a layout is recommended because Next.js shares layout code across pages, making it more efficient. By using `IntlayerClientProvider` in the layout, you avoid reinitialising it for every page, improving performance and maintaining a consistent localisation context throughout your application.
+- **`IntlayerServerProvider`** is used to provide the locale to the server-side children. It cannot be set in the layout.
+
+  > Layouts and pages cannot share a common server context because the server context system is based on a per-request data store (via [React's cache](https://react.dev/reference/react/cache) mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.
+
+```tsx {4,7} fileName="src/components/clientComponentExample/ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => {
+  const content = useIntlayer("client-component-example"); // Declare related content
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/clientComponentExample/ClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample = () => {
+  const content = useIntlayer("client-component-example"); // Declare related content
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/clientComponentExample/ClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ClientComponentExample = () => {
+  const content = useIntlayer("client-component-example"); // Create the related content declaration
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```tsx {2} fileName="src/components/serverComponentExample/ServerComponentExample.tsx"  codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => {
+  const content = useIntlayer("server-component-example"); // Create the related content declaration
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx {1} fileName="src/components/serverComponentExample/ServerComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("server-component-example"); // Create a related content declaration
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx {1} fileName="src/components/serverComponentExample/ServerComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer/server");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("server-component-example"); // Create a related content declaration
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+> 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, for example:
+
+> ```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/next-intlayer/useIntlayer.md).
+
+### (Optional) Step 7: Configure Proxy for Locale Detection
+
+Set up the proxy to detect the user's preferred locale:
+
+```typescript fileName="src/proxy.ts" codeFormat="typescript"
+export { intlayerProxy as proxy } from "next-intlayer/proxy";
+
+export const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+```
+
+```javascript fileName="src/proxy.mjs" codeFormat="esm"
+export { intlayerProxy as proxy } from "next-intlayer/proxy";
+
+export const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+```
+
+```javascript fileName="src/proxy.cjs" codeFormat="commonjs"
+const { intlayerProxy } = require("next-intlayer/proxy");
+
+const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+
+module.exports = { proxy: intlayerProxy, config };
+```
+
+> The `intlayerProxy` is used to detect the user's preferred locale and redirect them to the appropriate URL as specified in the [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md). Additionally, it allows saving the user's preferred locale in a cookie.
+
+> If you need to chain several proxies together (for example, `intlayerProxy` with authentication or custom proxies), Intlayer now provides a helper called `multipleProxies`.
+
+```ts
+import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";
+import { customProxy } from "@utils/customProxy";
+
+export const proxy = multipleProxies([intlayerProxy, customProxy]);
+```
+
+### (Optional) Step 8: Change the language of your content
+
+To change the language of your content in Next.js, the recommended approach is to use the `Link` component to navigate users to the appropriate localised page. The `Link` component enables prefetching of the page, which helps avoid a full page reload.
+
+```tsx fileName="src/components/localeSwitcher/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const LocaleSwitcher: FC = () => {
+  const { locale, availableLocales, setLocale } = useLocale({
+    onChange: () => window.location.reload(),
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <button
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocale(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 the 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>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/localeSwitcher/LocaleSwitcher.msx" codeFormat="esm"
+"use client";
+
+import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const LocaleSwitcher = () => {
+  const { locale, availableLocales, setLocale } = useLocale({
+    onChange: () => window.location.reload(),
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <button
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocale(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 the current locale — e.g. Francés when the current locale is set to Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Language in English — e.g. French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/localeSwitcher/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales, getHTMLTextDir, getLocaleName } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+export const LocaleSwitcher = () => {
+  const path
+  const { locale availableLocales, setLocale } = useLocale({
+       onChange: ()=> window.location.reload(),
+  });
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <button
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocale(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 the current locale — e.g. Francés when current locale is Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Language in English — e.g. French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+> An alternative is to use the `setLocale` function provided by the `useLocale` hook. This function does not allow prefetching the page. See the [`useLocale` hook documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/next-intlayer/useLocale.md) for more details.
+
+> Documentation references:
+>
+> - [`useLocale` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/next-intlayer/useLocale.md)
+> - [`getLocaleName` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/next-intlayer/getLocaleName.md)
+> - [`getLocalizedUrl` hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/next-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)
+
+### (Optional) Step 9: Get the current locale in Server Actions
+
+If you need the active locale inside a Server Action (e.g., to localise emails or run locale-aware logic), call `getLocale` from `next-intlayer/server`:
+
+```tsx fileName="src/app/actions/getLocale.ts" codeFormat="typescript"
+"use server";
+
+import { getLocale } from "next-intlayer/server";
+
+export const myServerAction = async () => {
+  const locale = await getLocale();
+
+  // Do something with the locale
+};
+```
+
+> The `getLocale` function follows a cascading strategy to determine the user's locale:
+>
+> 1. First, it checks the request headers for a locale value that may have been set by a proxy
+> 2. If no locale is found in the headers, it looks for a locale stored in cookies.
+> 3. If no cookie is present, it attempts to detect the user's preferred language from the browser's settings.
+> 4. As a last resort, it falls back to the application's configured default locale.
+>
+> This ensures the most appropriate locale is selected based on the available context.
+
+### (Optional) Step 10: Optimise your bundle size
+
+When using `next-intlayer`, dictionaries are included in the bundle for every page by default. To optimise bundle size, Intlayer provides an optional SWC plugin that intelligently replaces `useIntlayer` calls using macros. This ensures dictionaries are only included in bundles for pages that actually use them.
+
+To enable this optimisation, install the `@intlayer/swc` package. Once installed, `next-intlayer` will automatically detect and use the plugin:
+
+```bash packageManager="npm"
+npm install @intlayer/swc --save-dev
+npx intlayer init
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/swc --save-dev
+pnpm intlayer init
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/swc --save-dev
+yarn intlayer init
+```
+
+```bash packageManager="bun"
+bun add @intlayer/swc --dev
+bunx intlayer init
+```
+
+> Note: This optimisation is only available for Next.js 13 and above.
+
+> Note: This package is not installed by default because SWC plugins are still experimental in Next.js. This may change in the future.
+
+> Note: If you set the option to `importMode: 'dynamic'` or `importMode: 'live'`, it will rely on Suspense, so you will need to wrap your `useIntlayer` calls in a `Suspense` boundary. That means you will not be able to use `useIntlayer` directly at the top level of your page or layout component.
+
+### Watch dictionary changes on Turbopack
+
+When using Turbopack as your development server with the `next dev` command, dictionary changes won't be detected automatically by default.
+
+This limitation occurs because Turbopack cannot run webpack plugins in parallel to monitor changes to your content files. As a workaround, you'll need to use the `intlayer watch` command to run both the development server and the Intlayer build watcher simultaneously.
+
+```json5 fileName="package.json"
+{
+  // ... Your existing package.json configuration
+  "scripts": {
+    // ... Your existing scripts configuration
+    "dev": "intlayer watch --with 'next dev'",
+  },
+}
+```
+
+> If you are using next-intlayer@<=6.x.x, you must keep the `--turbopack` flag to make the Next.js 16 application work correctly with Turbopack. We recommend using next-intlayer@>=7.x.x to avoid this limitation.
+
+### Configure TypeScript
+
+Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase more robust.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Ensure your TypeScript configuration includes the auto-generated types.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Your existing TypeScript configuration
+  "include": [
+    // ... Your existing TypeScript configuration
+    ".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 entries to your `.gitignore` file:
+
+```plaintext fileName=".gitignore"
+# 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).
+
+### Going 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).