@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en-GB/intlayer_with_nextjs_16.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2026-05-06
-title: Next.js i18n - How to translate an Next.js 16 app in 2026
-description: Discover how to make your Next.js 16 website multilingual. Follow the documentation to internationalise (i18n) and translate it.
+updatedAt: 2026-05-31
+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
@@ -70,27 +70,66 @@ See [Application Template](https://github.com/aymericzip/intlayer-next-16-templa
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**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).
+Compared to main solutions like `next-intl` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **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 autogenerated types, improving autocompletion and error detection.
-- **Benefit from advanced features**, like dynamic locale detection and switching.
+<Accordion header="Full Next.js coverage">
 
-> 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).
-> 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-GB/intlayer_with_nextjs_no_locale_path.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).
+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/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
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -122,7 +161,9 @@ bun x intlayer init
 
   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 proxy for detecting the user's preferred locale, managing cookies, and handling URL redirection.
 
-### Step 2: Configure Your Project
+</Step>
+
+<Step number={2} title="Configure Your Project">
 
 Here is the final structure that we will make:
 
@@ -174,7 +215,9 @@ 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 3: Integrate Intlayer in Your Next.js Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Next.js Configuration">
 
 Configure your Next.js setup to use Intlayer:
 
@@ -217,7 +260,9 @@ export default withIntlayer(nextConfig);
 > withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
 > ```
 
-### Step 4: Define Dynamic Locale Routes
+</Step>
+
+<Step number={4} title="Define Dynamic Locale Routes">
 
 Remove everything from `RootLayout` and replace it with the following code:
 
@@ -280,7 +325,9 @@ export default LocaleLayout;
 
 > Intlayer works with `export const dynamic = 'force-static';` to ensure that the pages are pre-built for all locales.
 
-### Step 5: Declare Your Content
+</Step>
+
+<Step number={5} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -326,7 +373,9 @@ export default pageContent;
 
 > 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
+</Step>
+
+<Step number={6} title="Utilise Content in Your Code">
 
 Access your content dictionaries throughout your application:
 
@@ -413,7 +462,9 @@ export const ServerComponentExample: FC = () => {
 
 > 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
+</Step>
+
+<Step number={7} title="Configure Proxy for Locale Detection" isOptional={true}>
 
 Set up proxy to detect the user's preferred locale:
 
@@ -437,7 +488,9 @@ import { customProxy } from "@utils/customProxy";
 export const proxy = multipleProxies([intlayerProxy, customProxy]);
 ```
 
-### (Optional) Step 8: Internationalisation of your metadata
+</Step>
+
+<Step number={8} title="Internationalisation of your metadata" isOptional={true}>
 
 In the case you want to internationalise your metadata, such as the title of your page, you can use the `generateMetadata` function provided by Next.js. Inside, you can retrieve the content from the `getIntlayer` function to translate your metadata.
 
@@ -572,7 +625,9 @@ export const generateMetadata = async ({
 
 > Learn more about the metadata optimisation [on the official Next.js documentation](https://nextjs.org/docs/app/building-your-application/optimizing/metadata).
 
-### (Optional) Step 9: Internationalisation of your sitemap.xml and robots.txt
+</Step>
+
+<Step number={9} title="Internationalisation of your sitemap.xml and robots.txt" isOptional={true}>
 
 To internationalise your `sitemap.xml` and `robots.txt`, you can use the `getMultilingualUrls` function provided by Intlayer. This function allows you to generate multilingual URLs for your sitemap.
 
@@ -635,7 +690,9 @@ export default robots;
 
 > Learn more about the sitemap optimisation [on the official Next.js documentation](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap). Learn more about the robots.txt optimisation [on the official Next.js documentation](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots).
 
-### (Optional) Step 10: Change the language of your content
+</Step>
+
+<Step number={10} title="Change the language of your content" isOptional={true}>
 
 To change the language of your content in Next.js, the recommended way is to use the `Link` component to redirect users to the appropriate localised page. The `Link` component enables prefetching of the page, which helps avoid a full page reload.
 
@@ -728,7 +785,9 @@ return (
 > - [`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 11: Creating a Localised Link Component
+</Step>
+
+<Step number={11} title="Creating a Localised Link Component" isOptional={true}>
 
 To ensure that your application's navigation respects the current locale, you can create a custom `Link` component. This component automatically prefixes internal URLs with the current language. For example, when a French-speaking user clicks on a link to the "About" page, they are redirected to `/fr/about` instead of `/about`.
 
@@ -796,7 +855,9 @@ export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
 
 By integrating this `Link` component across your application, you maintain a coherent and language-aware user experience while also benefitting from improved SEO and usability.
 
-### (Optional) Step 12: Get the current locale in Server Actions
+</Step>
+
+<Step number={12} 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`:
 
@@ -821,7 +882,9 @@ export const myServerAction = async () => {
 >
 > This ensures the most appropriate locale is selected based on available context.
 
-### (Optional) Step 13: Optimise your bundle size
+</Step>
+
+<Step number={13} 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 replace `useIntlayer` calls using macros. This ensures dictionaries are only included in bundles for pages that actually use them.
 
@@ -848,6 +911,9 @@ bun add @intlayer/swc --dev
 > Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.
 
 > Note: If you set the option as `importMode: 'dynamic'` or `importMode: 'fetch'` (in the `dictionary` configuration), it will rely on Suspense, so you will have to wrap your `useIntlayer` calls in a `Suspense` boundary. That means, you will not be able to use the `useIntlayer` directly at the top level of your Page / Layout component.
+> </Step>
+
+</Steps>
 
 ### Watch dictionaries changes on Turbopack
 

package/docs/en-GB/intlayer_with_nextjs_compiler.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-01-10
-updatedAt: 2026-05-06
-title: Next.js i18n - Transform an existing Next.js app into a multilingual app (i18n guide 2026)
-description: Discover how to make your existing Next.js application multilingual using Intlayer Compiler. Follow the documentation to internationalise (i18n) and translate it with AI.
+updatedAt: 2026-05-31
+title: "Next.js i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Next.js app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -81,7 +81,9 @@ To mitigate this impact during development, you can configure the compiler to ru
 
 ## Step-by-Step Guide to Set Up Intlayer in a Next.js Application
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -117,7 +119,9 @@ bun x intlayer init
 
   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 proxy for detecting the user's preferred locale, managing cookies, and handling URL redirection.
 
-### Step 2: Configure Your Project
+</Step>
+
+<Step number={2} title="Configure Your Project">
 
 Create a config file to configure the languages of your application:
 
@@ -168,7 +172,9 @@ 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 3: Integrate Intlayer in Your Next.js Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Next.js Configuration">
 
 Configure your Next.js setup to use Intlayer:
 
@@ -185,7 +191,9 @@ export default withIntlayer(nextConfig);
 
 > The `withIntlayer()` Next.js plugin is used to integrate Intlayer with Next.js. It ensures the building of content declaration files and monitors 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.
 
-### Step 4: Configure Babel
+</Step>
+
+<Step number={4} title="Configure Babel">
 
 The Intlayer compiler requires Babel to extract and optimise your content. Update your `babel.config.js` (or `babel.config.json`) to include the Intlayer plugins:
 
@@ -206,7 +214,9 @@ module.exports = {
 };
 ```
 
-### Step 5: Detect Locale in your pages
+</Step>
+
+<Step number={5} title="Detect Locale in your pages">
 
 Remove everything from `RootLayout` and replace it with the following code:
 
@@ -249,7 +259,9 @@ const RootLayout = async ({
 export default RootLayout;
 ```
 
-### Step 6: Compile your components
+</Step>
+
+<Step number={6} title="Compile your components">
 
 With the compiler enabled, you **no longer need** to manually declare content dictionaries (like `.content.ts` files).
 
@@ -345,7 +357,9 @@ export default async function Page() {
 
   > Layout and page 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.
 
-### (Optional) Step 7: Fill missing translation
+</Step>
+
+<Step number={7} title="Fill missing translation" isOptional={true}>
 
 Intlayer provide a CLI tool to help you fill missing translations. You can use the `intlayer` command to test and fill missing translations from your code.
 
@@ -383,7 +397,9 @@ bun x intlayer fill         # Fill missing translations
 
 > For more details, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/ci.md)
 
-### (Optional) Step 8: Configure Proxy for Locale Detection
+</Step>
+
+<Step number={8} title="Configure Proxy for Locale Detection" isOptional={true}>
 
 Set up proxy to detect the user's preferred locale:
 
@@ -398,7 +414,9 @@ export const 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 enables saving the user's preferred locale in a cookie.
 
-### (Optional) Step 8: Change the language of your content
+</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 way is to use the `Link` component to redirect users to the appropriate localised page. The `Link` component enables prefetching of the page, which helps avoid a full page reload.
 
@@ -448,7 +466,9 @@ export const LocaleSwitcher: FC = () => {
 
 > An alternative way is to use the `setLocale` function provided by the `useLocale` hook. This function will 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.
 
-### (Optional) Step 10: Optimise your bundle size
+</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 replace `useIntlayer` calls using macros. This ensures dictionaries are only included in bundles for pages that actually use them.
 
@@ -475,6 +495,9 @@ bun add @intlayer/swc --dev
 > Note: This package is not installed by default because SWC plugins are still experimental on Next.js. It may change in the future.
 
 > Note: If you set the option as `importMode: 'dynamic'` or `importMode: 'fetch'` (in the `dictionary` configuration), it will rely on Suspense, so you will have to wrap your `useIntlayer` calls in a `Suspense` boundary. That means, you will not be able to use the `useIntlayer` directly at the top level of your Page / Layout component.
+> </Step>
+
+</Steps>
 
 ### Configure TypeScript
 

package/docs/en-GB/intlayer_with_nextjs_no_locale_path.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-01-10
-updatedAt: 2026-05-06
-title: Next.js i18n - How to translate an Next.js 16 app (without [locale] in the page path) in 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.
+updatedAt: 2026-05-31
+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
@@ -53,25 +53,66 @@ See [Application Template](https://github.com/aymericzip/intlayer-next-no-lolale
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**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).
+Compared to main solutions like `next-intl` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **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.
+<Accordion header="Full Next.js coverage">
 
-> 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).
+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/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
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -103,7 +144,9 @@ bun x intlayer init
 
   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
+</Step>
+
+<Step number={2} title="Configure Your Project">
 
 Here is the final structure we will create:
 
@@ -158,7 +201,9 @@ 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 3: Integrate Intlayer into your Next.js configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer into your Next.js configuration">
 
 Configure your Next.js setup to use Intlayer:
 
@@ -201,7 +246,9 @@ export default withIntlayer(nextConfig);
 > withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
 > ```
 
-### Step 4: Define dynamic locale routes
+</Step>
+
+<Step number={4} title="Define dynamic locale routes">
 
 Remove everything from `RootLayout` and replace it with the following code:
 
@@ -244,7 +291,9 @@ const RootLayout = async ({
 export default RootLayout;
 ```
 
-### Step 5: Declare your content
+</Step>
+
+<Step number={5} title="Declare your content">
 
 Create and manage your content declarations to store translations:
 
@@ -362,7 +411,9 @@ export default pageContent;
 
 > 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
+</Step>
+
+<Step number={6} title="Utilise Content in Your Code">
 
 Access your content dictionaries throughout your application:
 
@@ -453,7 +504,9 @@ export const ServerComponentExample: FC = () => {
 
 > 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
+</Step>
+
+<Step number={7} title="Configure Proxy for Locale Detection" isOptional={true}>
 
 Set up the proxy to detect the user's preferred locale:
 
@@ -477,7 +530,9 @@ import { customProxy } from "@utils/customProxy";
 export const proxy = multipleProxies([intlayerProxy, customProxy]);
 ```
 
-### (Optional) Step 8: Change the language of your content
+</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.
 
@@ -538,7 +593,9 @@ export const LocaleSwitcher: FC = () => {
 > - [`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
+</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`:
 
@@ -563,7 +620,9 @@ export const myServerAction = async () => {
 >
 > This ensures the most appropriate locale is selected based on the available context.
 
-### (Optional) Step 10: Optimise your bundle size
+</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.
 
@@ -590,6 +649,9 @@ bun add @intlayer/swc --dev
 > 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