@intlayer/docs 9.4.4 → 9.5.0

package/docs/en-GB/intlayer_with_nextjs_no_locale_path.md

@@ -1,986 +0,0 @@
----
-createdAt: 2026-01-10
-updatedAt: 2026-08-30
-title: "Next.js 16 i18n - Complete guide to translate your app"
-description: "No more i18next. The 2026 guide to building a multilingual (i18n) Next.js 16 app. Translate with AI agents and optimise bundle size, SEO and performances."
-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: 8.9.0
-    date: 2026-05-04
-    changes: "Update Solid useIntlayer API usage to direct property access"
-  - version: 1.0.0
-    date: 2026-01-10
-    changes: "Initial release"
-author: aymericzip
----
-
-# Translate your Next.js 16 site (without [locale] in the page path) using Intlayer | Internationalisation (i18n)
-
-<Tabs defaultTab="video">
-  <Tab 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=https://intlayer.org&amp;controls=0&amp;rel=1"/>
-
-  </Tab>
-  <Tab label="Code" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-next-16-no-locale-path-template?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"
-/>
-
-  </Tab>
-</Tabs>
-
-See [Application Template](https://github.com/aymericzip/intlayer-next-no-lolale-path-template) on GitHub.
-
-## Table of contents
-
-<TOC/>
-
-## Why Intlayer over alternatives?
-
-Compared to main solutions like `next-intl` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
-
-<AccordionGroup>
-<Accordion header="Full Next.js coverage">
-
-Intlayer is optimized to work with **Server Components** for efficient rendering and is fully compatible with [**Turbopack**](https://nextjs.org/docs/architecture/turbopack). It does not block static rendering and offers middleware as well as all the features needed for scaling internationalization (i18n).
-
-> Intlayer is compatible with Next.js 12, 13, 14, 15, and 16. If you are using the Next.js Pages Router, you can refer to this [guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_page_router.md).
-> Locale routing is useful for SEO, bundle size, and performance. If you don't need it, you can refer to this [guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md).
-> For Next.js 12, 13, 14, and 15 with the App Router, refer to this [guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_14.md).
-
-</Accordion>
-
-<Accordion header="Bundle size">
-
-Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
-
-</Accordion>
-
-<Accordion header="Maintainability">
-
-Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
-
-</Accordion>
-
-<Accordion header="AI Agent">
-
-Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
-
-</Accordion>
-
-<Accordion header="Automation">
-
-Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
-
-</Accordion>
-
-<Accordion header="Performance">
-
-Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
-
-</Accordion>
-
-<Accordion header="Scaling with none-dev">
-
-More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
-
-</Accordion>
-</AccordionGroup>
-
----
-
-## Step-by-Step Guide to Set Up Intlayer in a Next.js Application
-
-<Steps>
-
-<Step number={1} title="Install Dependencies">
-
-Install the necessary packages using npm:
-
-```bash packageManager="npm"
-npx intlayer init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer init --interactive
-```
-
-> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
-
-> This command will detect your environment and install the required packages. For example:
-
-```bash packageManager="npm"
-npm install intlayer next-intlayer
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer next-intlayer
-```
-
-```bash packageManager="yarn"
-yarn add intlayer next-intlayer
-```
-
-```bash packageManager="bun"
-bun add intlayer next-intlayer
-```
-
-- **intlayer**
-
-  The core package that provides internationalisation tools for configuration management, translation, [content declaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/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>
-
-<Step number={2} title="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", "esm", "commonjs"]}
-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;
-```
-
-> 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>
-
-<Step number={3} title="Integrate Intlayer into your Next.js configuration">
-
-Configure your Next.js setup to use Intlayer:
-
-```typescript fileName="next.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { NextConfig } from "next";
-import { withIntlayer } from "next-intlayer/server";
-
-const nextConfig: NextConfig = {/* config options here */};
-
-export default 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 is a promise function. 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, you can use the `withIntlayerSync()` function. Example:
->
-> ```ts
-> const nextConfig = withIntlayerSync(nextConfig);
-> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
->
-> export default nextConfigWithOtherPlugins;
-> ```
-
-> 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>
-
-<Step number={4} title="Define dynamic locale routes">
-
-Remove everything from `RootLayout` and replace it with the following code:
-
-<Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
-
-```tsx {5} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
-import type { Metadata } from "next";
-import type { ReactNode } from "react";
-import "./globals.css";
-import { getHTMLTextDir, getIntlayer } from "intlayer";
-import { getLocale, IntlayerProvider } from "next-intlayer/server";
-export { generateStaticParams } from "next-intlayer";
-
-export const generateMetadata = async (): Promise<Metadata> => {
-  const locale = await getLocale();
-  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)}>
-      <body>
-        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
-      </body>
-    </html>
-  );
-};
-
-export default RootLayout;
-```
-
-> A single `IntlayerProvider` covers both halves of the tree: it seeds the request-scoped server context read by the server hooks, and mounts the client provider so client components receive the same locale.
-
- </Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
-
-```tsx {3} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
-import type { Metadata } from "next";
-import type { ReactNode } from "react";
-import "./globals.css";
-import { IntlayerProvider, LocalPromiseParams } from "next-intlayer";
-import { getHTMLTextDir, getIntlayer } from "intlayer";
-import { getLocale } from "next-intlayer/server";
-export { generateStaticParams } from "next-intlayer";
-
-export const generateMetadata = async (): Promise<Metadata> => {
-  const locale = await getLocale();
-  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)}>
-      <body>
-        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
-      </body>
-    </html>
-  );
-};
-
-export default RootLayout;
-```
-
-</Tab>
-</Tabs>
-
-</Step>
-
-<Step number={5} title="Declare your content">
-
-Create and manage your content declarations to store translations:
-
-```tsx fileName="src/app/metadata.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-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;
-```
-
-```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", "esm", "commonjs"]}
-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;
-```
-
-```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,cjs,md,mdx,yaml,yml}`).
-
-> 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>
-
-<Step number={6} title="Utilise Content in Your Code">
-
-Access your content dictionaries throughout your application:
-
-<Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
-
-```tsx fileName="src/app/page.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
-import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
-import { useIntlayer } from "next-intlayer";
-import { NextPage } from "next";
-
-const PageContent: FC = () => {
-  const content = useIntlayer("page");
-
-  return (
-    <>
-      <p>{content.getStarted.main}</p>
-      <code>{content.getStarted.pageLink}</code>
-    </>
-  );
-};
-
-const Page: NextPage = () => (
-  <>
-    <PageContent />
-    <ServerComponentExample />
-    <ClientComponentExample />
-  </>
-);
-
-export default Page;
-```
-
-- **`IntlayerProvider`** is mounted once, in the root layout. It provides the locale to both server and client components, so pages no longer wrap themselves.
-- Without a `[locale]` path segment the locale always comes from the request — the `x-intlayer-locale` header set by the Intlayer proxy, then the locale cookie — which the server hooks read on their own when the provider has not run.
-
- </Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
-
-```tsx fileName="src/app/page.tsx" codeFormat={["typescript", "esm"]}
-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;
-```
-
-- **`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.
-
- </Tab>
-</Tabs>
-
-```tsx {4,7} fileName="src/components/clientComponentExample/ClientComponentExample.tsx" codeFormat={["typescript", "esm"]}
-"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>
-  );
-};
-```
-
-<Tabs>
- <Tab label='Intlayer >=9.4' value='>=9.4'>
-
-```tsx {2} fileName="src/components/serverComponentExample/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "next-intlayer";
-
-export const ServerComponentExample: FC = () => {
-  const content = useIntlayer("server-component-example"); // Create related content declaration
-
-  return (
-    <div>
-      <h2>{content.title}</h2>
-      <p>{content.content}</p>
-    </div>
-  );
-};
-```
-
-> `next-intlayer` is the isomorphic import path: the `react-server` export condition gives server components the ambient-locale implementation, whilst client components get the context-backed one. The same call works on both sides.
-
-</Tab>
- <Tab label='Intlayer <9.4' value='<9.4'>
-
-```tsx {2} fileName="src/components/serverComponentExample/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
-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>
-  );
-};
-```
-
-</Tab>
-</Tabs>
-
-> If you want to use your content in a `string` attribute, such as `alt`, `title`, `href`, `aria-label`, etc., you can use the value of the function, for example:
-
-> ```html
-> <img src="{content.image.src.value}" alt="{content.image.value}" />
-> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
-> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
-> ```
-
-> 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).
-
-</Step>
-
-<Step number={7} title="Configure Proxy for Locale Detection" isOptional={true}>
-
-Set up the proxy to detect the user's preferred locale:
-
-```typescript fileName="src/proxy.ts" codeFormat={["typescript", "esm", "commonjs"]}
-export { intlayerProxy as proxy } from "next-intlayer/proxy";
-
-export const config = {
-  matcher:
-    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
-};
-```
-
-> 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.
-
-> Since Intlayer v9, this middleware respects the `routing.enableProxy` option (`true` by default). Set `routing.enableProxy: false` in your configuration to turn it into a pass-through without removing this file. See the [v9 release notes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/releases/v9.md).
-
-> 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]);
-```
-
-</Step>
-
-<Step number={8} title="Change the language of your content" isOptional={true}>
-
-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", "esm"]}
-"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();
-
-  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>
-  );
-};
-```
-
-> 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)
-
-</Step>
-
-<Step number={9} title="Get the current locale in Server Actions" isOptional={true}>
-
-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.
-
-</Step>
-
-<Step number={10} title="Optimise your bundle size" isOptional={true}>
-
-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
-```
-
-```bash packageManager="pnpm"
-pnpm add @intlayer/swc --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add @intlayer/swc --save-dev
-```
-
-```bash packageManager="bun"
-bun add @intlayer/swc --dev
-```
-
-> 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: 'fetch'` (in the `dictionary` configuration), 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.
-
-</Step>
-
-</Steps>
-
-### 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).
-
-## Frequently Asked Questions
-
-<FAQ>
-
-<Question title="What are the different solutions available to internationalize a Next.js app?">
-
-The `i18n` field of `next.config.js` does not apply to the App Router, so the localization layer is always a library choice:
-
-- **`next-intl`**, **`next-i18next` / `i18next`** and **`react-intl`**: JSON or ICU catalogues loaded per namespace.
-- **`Lingui`**: extraction driven, with ICU messages compiled at build time.
-- **`Intlayer`**: the most advanced solution. Content declared anywhere in your codebase ([next to each component or centralized](https://intlayer.org/blog/per-component-vs-centralized-i18n)) and compiled per component, fully typed, with AI translation, a visual editor and a CMS.
-
-This guide covers the setup without a locale in the path. See [why Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/interest_of_intlayer.md) and the [Next.js i18n benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/nextjs.md).
-
-</Question>
-
-<Question title="How much does i18n add to my Next.js bundle size?">
-
-Much less than a namespace based setup, because a page never downloads a catalogue it does not render. Server Components resolve their content on the server, and the build time compiler replaces `useIntlayer` calls with the exact dictionary entries a component uses, so unused keys and unused languages are dropped, and [dynamic dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dynamic_dictionaries/index.md) split the rest per locale. Measured against the usual alternatives, Intlayer reduces bundle and page size by up to 50%. See [bundle optimization](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/bundle_optimization.md) and the [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/benchmark/nextjs.md).
-
-</Question>
-
-<Question title="Can I migrate from `next-intl`, `next-i18next` or `i18next` without rewriting my components?">
-
-Yes, and there are two paths. You can migrate the content progressively with the [next-intl migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_next-intl_to_intlayer.md) or the [i18next migration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/migration_from_i18next_to_intlayer.md). Or you can keep your current API entirely: the [compat adapters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compat/index.md) expose the exact same API as `next-intl`, `react-i18next` and `react-intl`, but served by Intlayer dictionaries, so imports change and component code does not.
-
-</Question>
-
-<Question title="Can I keep my existing JSON translation files?">
-
-Yes. The [sync JSON plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-json.md) keeps your `/messages/{locale}/{namespace}.json` files as the source of truth and generates Intlayer dictionaries from them, in both directions. A [sync PO plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/plugins/sync-po.md) does the same for gettext catalogues, and [per locale files](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/per_locale_file.md) let you split content by language instead of grouping locales in one file.
-
-</Question>
-
-<Question title="Do I have to move my content key by key?">
-
-No. Run `npx intlayer extract` and Intlayer reads your components, pulls the user facing strings out and writes a `.content` file next to each one, so you review a diff instead of copying strings into a catalogue one at a time.
-
-For a fully automated pipeline, the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) does the same at build time: it scans your JSX, TSX, Vue and Svelte source on every change, generates the dictionaries and keeps them in sync through hot module replacement, so there are no keys to maintain by hand at all.
-
-Two limits are worth knowing before you turn the compiler on. It works by static analysis, so strings that only exist at runtime, such as API error codes or CMS fields, stay out of reach. And it has to tell user facing text apart from application logic like `className="active"` or a status code, which needs a few annotations in a large codebase. The [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md) avoids both by keeping you in the loop.
-
-</Question>
-
-<Question title="What editor and AI agent tooling is available?">
-
-Five pieces, all optional:
-
-- **[VS Code extension](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/vs_code_extension.md)**: jump from a `useIntlayer` key to the content file that declares it, extract content from a component, and run build, fill, test, push and pull from the command palette or a dedicated Intlayer tab.
-- **[LSP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/lsp.md)**: the same awareness in any editor that speaks LSP, with go to definition, find all references, hover previews of a translated value, autocompletion of keys and fields, and a warning when a key is not declared anywhere. It also resolves `i18next`, `react-i18next`, `next-intl` and `use-intl` calls, which helps while you migrate.
-- **[MCP server](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md)**: exposes the Intlayer documentation and CLI to Cursor, VS Code, Claude Desktop, Claude Code and ChatGPT, so an assistant answers from current docs instead of guessing, and can run commands such as `intlayer fill` itself.
-- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/agent_skills.md)**: focused skills such as `intlayer-config`, `intlayer-cli` and `intlayer-content`, plus one per framework, that teach an agent your routing setup and the content node types.
-- **[ESLint plugin](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/eslint.md)**: `no-raw-text` flags hardcoded strings, with further rules for static dictionary keys and unused content.
-
-</Question>
-
-<Question title="Why would I serve my app without a locale in the URL?">
-
-Because the locale is not always part of the page identity. An authenticated dashboard, an internal tool or an app behind a login has no reason to expose `/fr/` in every URL: the language is a user preference, not a different document. Dropping the prefix also keeps your routes, your links and your analytics on a single set of paths.
-
-</Question>
-
-<Question title="What are the SEO consequences of not having a locale in the URL?">
-
-They are real, so choose deliberately. Without a distinct URL per language, search engines have no separate page to index for each locale, `hreflang` has nothing to point at, and a crawler sees only the language your default detection serves it. That is fine for content behind a login, which is not indexed anyway, and a poor fit for a public marketing site or documentation. If organic traffic per language matters, use the prefixed setup in the [Next.js 16 guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_nextjs_16.md) instead.
-
-</Question>
-
-<Question title="What is the difference between the `no-prefix` and `search-params` modes?">
-
-`"no-prefix"` keeps the locale entirely out of the URL and resolves it from a cookie, a header or a domain, so every language shares one address. `"search-params"` puts it in the query string as `/dashboard?locale=fr`, which still gives each language a distinct, linkable and bookmarkable URL without changing your route tree. Prefer `"search-params"` when you want shareable links per language.
-
-</Question>
-
-<Question title="How is the locale detected then?">
-
-From the sources listed in `routing.storage`, by default a cookie first and then the `Accept-Language` header, falling back to your default locale. Step 7 adds the proxy that applies it. A language the user picks explicitly is persisted, so it survives the next visit. See the [configuration reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
-
-</Question>
-
-<Question title="Can I map each language to its own domain instead?">
-
-Yes, and it is the option to consider when you dropped the prefix for cosmetic reasons but still want the SEO. `routing.domains` maps a locale to a hostname, so the domain identifies the language, no prefix is added to the path, and every language gets an indexable URL that `hreflang` can point at.
-
-</Question>
-
-<Question title="How do I translate the app automatically with AI?">
-
-Run `npx intlayer fill`. It fills missing translations with the LLM of your choice, using your own provider and API key, and `--git-diff` limits the run to the content changed on the branch. See the [fill command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/fill.md) and [CI/CD integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/CI_CD.md).
-
-</Question>
-
-<Question title="Does Intlayer support plurals, gender and rich text?">
-
-Yes: [plural forms](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/plurial.md), [gender based content](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/gender.md), conditions, [insertions](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/insertion.md), [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/markdown.md) and [formatters](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/formatters.md) for numbers, dates and currencies.
-
-</Question>
-
-<Question title="How can translators edit the content without touching the code?">
-
-Through the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md), which runs on your own infrastructure and lets anyone edit text in place on the running app, or the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md), which externalizes content so it can change without a deployment.
-
-</Question>
-
-<Question title="Is Intlayer free and open source?">
-
-Yes, under the Apache 2.0 licence, commercial use included. The hosted CMS is an optional paid service that can also be [self hosted](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md).
-
-</Question>
-
-</FAQ>