@intlayer/docs 7.0.3 → 7.0.4-canary.0

package/blog/en/intlayer_with_next-intl.md

@@ -1,16 +1,18 @@
 ---
 createdAt: 2025-01-02
 updatedAt: 2025-10-29
-title: Intlayer and next-intl
-description: Integrate Intlayer with next-intl for the internationalization (i18n) of a React app
+title: Next.js Internationalization (i18n) with next-intl and Intlayer
+description: Integrate Intlayer with next-intl for enhanced internationalization in Next.js applications. Learn how to structure translations, manage content, and leverage the best of both libraries.
 keywords:
   - next-intl
   - Intlayer
   - Internationalization
+  - i18n
   - Blog
   - Next.js
   - JavaScript
   - React
+  - TypeScript
 slugs:
   - blog
   - intlayer-with-next-intl
@@ -22,106 +24,129 @@ history:
 
 # Next.js Internationalization (i18n) with next-intl and Intlayer
 
-Both next-intl and Intlayer are open-source internationalization (i18n) frameworks designed for Next.js applications. They are widely used for managing translations, localization, and language switching in software projects.
+## What is next-intl?
 
-They share three principal notions:
+**[next-intl](https://github.com/amannn/next-intl)** is a popular open-source internationalization (i18n) library designed specifically for Next.js applications. It provides a comprehensive solution for managing translations, formatting dates and numbers, and handling locale routing.
 
-1. **Dictionary**: The method for defining the translatable content of your application.
-   - Named `content declaration file` in Intlayer, which can be a JSON, JS, or TS file exporting the structured data. See [Intlayer documentation](https://intlayer.org/fr/doc/concept/content) for more information.
-   - Named `messages` or `locale messages` in next-intl, usually in JSON files. See [next-intl documentation](https://github.com/amannn/next-intl) for more information.
+Key features of next-intl include:
 
-2. **Utilities**: Tools to build and interpret content declarations in the application, such as `useIntlayer()` or `useLocale()` for Intlayer, and `useTranslations()` for next-intl.
+- **Server-side rendering support** for both App Router and Pages Router
+- **Flexible message structure** using JSON files
+- **Type-safe translations** with TypeScript support
+- **Middleware for automatic locale detection** and routing
+- **Rich formatting capabilities** for dates, times, numbers, and relative time
 
-3. **Plugins and Middlewares**: Features for managing URL redirection, bundling optimization, and more e.g., `intlayerMiddleware` for Intlayer or [`createMiddleware`](https://github.com/amannn/next-intl) for next-intl.
+## What is Intlayer?
+
+**[Intlayer](https://intlayer.org)** is an innovative, open-source internationalization (i18n) library that takes a different approach to content management. Instead of separating translations into JSON files, Intlayer allows you to declare your multilingual content directly alongside your components.
+
+Key advantages of Intlayer include:
+
+- **Flexible content placement**: Declare translations right next to the components that use them
+- **Type-safe translations**: Automatic TypeScript type generation with full autocompletion
+- **Rich content support**: Handle complex content structures including React components, dates, and more
+- **Visual editor integration**: Manage translations through a visual interface
+- **Advanced features**: Dynamic locale detection, SEO optimization, and more
 
 ## Table of Contents
 
-<TOC>
+<TOC/>
 
 ## Intlayer vs. next-intl: Key Differences
 
-For a deeper analysis of how Intlayer compares to other i18n libraries for Next.js (such as next-intl), check out the [next-i18next vs. next-intl vs. Intlayer blog post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18next_vs_next-intl_vs_intlayer.md).
+Both next-intl and Intlayer are excellent i18n solutions for Next.js, but they take different approaches:
 
-## How to Generate next-intl Messages with Intlayer
+### Content Organization
+
+**next-intl**: Uses centralized JSON files for each locale, typically organized like:
+
+```
+messages/
+├── en.json
+├── fr.json
+└── es.json
+```
+
+**Intlayer**: Allows you to declare content alongside your components:
+
+```
+components/
+└── MyComponent/
+    ├── index.tsx
+    └── index.content.ts  # Translations for this component
+```
 
-### Why Use Intlayer with next-intl?
+### Flexibility
 
-Intlayer content declaration files generally offer a better developer experience. They are more flexible and maintainable due to two main advantages:
+**next-intl**: Great for traditional key-value translation patterns with JSON files.
 
-1. **Flexible Placement**: You can place an Intlayer content declaration file anywhere in your application’s file tree. This makes it easy to rename or delete components without leaving unused or dangling message files.
+**Intlayer**: Offers more flexibility with support for complex content structures, React components in translations, and powerful content management features.
 
-   Example file structures:
+### TypeScript Support
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Content declaration file
-               └── index.tsx
-   ```
+**next-intl**: Provides type safety through TypeScript integration.
 
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Content declaration file
-               └── index.mjx
-   ```
+**Intlayer**: Offers automatic type generation from your content declarations, ensuring complete type safety and better developer experience with autocompletion.
 
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Content declaration file
-               └── index.cjx
-   ```
+For a detailed comparison of Intlayer with other i18n libraries including next-intl, check out the [next-i18next vs. next-intl vs. Intlayer blog post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md).
 
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Content declaration file
-               └── index.jsx
-   ```
+## Why Use Intlayer with next-intl?
 
-2. **Centralized Translations**: Intlayer stores all translations in a single content declaration, ensuring no translation is missing. In TypeScript projects, missing translations are flagged automatically as type errors, providing immediate feedback to developers.
+While you can choose to use either library exclusively, combining them can be beneficial in certain scenarios:
 
-### Installation
+1. **Gradual Migration**: If you have an existing next-intl project and want to leverage Intlayer's features
+2. **Component-Centric Workflow**: Use Intlayer's flexible content declaration alongside next-intl's infrastructure
+3. **Best of Both Worlds**: Leverage next-intl's proven routing and formatting with Intlayer's developer experience
 
-To use Intlayer and next-intl together, install both libraries:
+This guide shows you how to use Intlayer to generate next-intl compatible messages, allowing you to benefit from Intlayer's content declaration approach while maintaining compatibility with next-intl.
+
+---
+
+## Step-by-Step Guide to Set Up Intlayer with next-intl
+
+### Step 1: Install Dependencies
+
+Install the necessary packages:
 
 ```bash packageManager="npm"
 npm install intlayer next-intl @intlayer/sync-json-plugin
 ```
 
+```bash packageManager="pnpm"
+pnpm add intlayer next-intl @intlayer/sync-json-plugin
+```
+
 ```bash packageManager="yarn"
 yarn add intlayer next-intl @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer next-intl @intlayer/sync-json-plugin
-```
+**Package descriptions:**
 
-### Configuring Intlayer to Export next-intl Messages
+- **intlayer**: Core library for internationalization management, content declaration, and building
+- **next-intl**: The next-intl library for Next.js internationalization
+- **@intlayer/sync-json-plugin**: Plugin to export Intlayer content declarations to next-intl compatible JSON format
 
-> **Note:** Exporting messages from Intlayer for next-intl can introduce slight differences in structure. If possible, keep an Intlayer-only or next-intl-only flow to simplify the integration. If you do need to generate next-intl messages from Intlayer, follow the steps below.
+### Step 2: Configure Your Project
 
-Create or update an `intlayer.config.ts` file (or `.mjs` / `.cjs`) in the root of your project:
+Create a configuration file to set up the locales and integration:
 
-```typescript fileName="intlayer.config.ts"
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
 import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Add your other locales
+    ],
     defaultLocale: Locales.ENGLISH,
   },
   plugins: [
     syncJSON({
+      // Configure where next-intl message files should be generated
       source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
     }),
   ],
@@ -130,80 +155,540 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Dictionary
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Add your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+const { syncJSON } = require("@intlayer/sync-json-plugin");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Add your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+module.exports = config;
+```
+
+> The `syncJSON` plugin tells Intlayer to export your content declarations to next-intl compatible JSON files. This allows you to write content using Intlayer's flexible format while consuming it through next-intl.
+
+### Step 3: Integrate Intlayer in Your Next.js Configuration
+
+If you plan to use additional Intlayer features beyond just generating next-intl messages, you can integrate Intlayer into your Next.js configuration:
+
+```typescript fileName="next.config.ts" codeFormat="typescript"
+import type { NextConfig } from "next";
+import { withIntlayer } from "next-intlayer/server";
+
+const nextConfig: NextConfig = {
+  /* your config options here */
+};
+
+export default withIntlayer(nextConfig);
+```
+
+```javascript fileName="next.config.mjs" codeFormat="esm"
+import { withIntlayer } from "next-intlayer/server";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* your config options here */
+};
+
+export default withIntlayer(nextConfig);
+```
+
+```javascript fileName="next.config.cjs" codeFormat="commonjs"
+const { withIntlayer } = require("next-intlayer/server");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* your config options here */
+};
+
+module.exports = withIntlayer(nextConfig);
+```
+
+> **Note**: This step is optional if you're only using Intlayer to generate next-intl messages. If you want to use Intlayer's hooks and components directly in your application, this integration is required.
+
+### Step 4: Configure next-intl Middleware
+
+Set up next-intl's middleware for automatic locale detection and routing:
+
+```typescript fileName="src/middleware.ts" codeFormat="typescript"
+import createMiddleware from "next-intl/middleware";
+
+export default createMiddleware({
+  // List of all supported locales
+  locales: ["en", "fr", "es"],
+
+  // Default locale when no preferred locale can be detected
+  defaultLocale: "en",
+
+  // Whether to redirect to the default locale
+  localePrefix: "as-needed",
+});
+
+export const config = {
+  // Matcher configuration to exclude specific paths
+  matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
+};
+```
+
+```javascript fileName="src/middleware.mjs" codeFormat="esm"
+import createMiddleware from "next-intl/middleware";
+
+export default createMiddleware({
+  locales: ["en", "fr", "es"],
+  defaultLocale: "en",
+  localePrefix: "as-needed",
+});
+
+export const config = {
+  matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
+};
+```
+
+```javascript fileName="src/middleware.cjs" codeFormat="commonjs"
+const createMiddleware = require("next-intl/middleware");
+
+module.exports = createMiddleware({
+  locales: ["en", "fr", "es"],
+  defaultLocale: "en",
+  localePrefix: "as-needed",
+});
+
+module.exports.config = {
+  matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
+};
+```
+
+> This middleware handles automatic locale detection from the user's browser settings and manages locale-based routing. For more details, see the [next-intl middleware documentation](https://next-intl-docs.vercel.app/docs/routing/middleware).
+
+### Step 5: Define Dynamic Locale Routes
+
+Set up your application structure to support dynamic locale routing. For the App Router (Next.js 13+):
+
+Remove everything from your root `RootLayout` and replace it with:
+
+```tsx fileName="src/app/layout.tsx" codeFormat="typescript"
+import type { PropsWithChildren, FC } from "react";
+import "./globals.css";
+
+const RootLayout: FC<PropsWithChildren> = ({ children }) => children;
+
+export default RootLayout;
+```
+
+```jsx fileName="src/app/layout.mjx" codeFormat="esm"
+import "./globals.css";
+
+const RootLayout = ({ children }) => children;
+
+export default RootLayout;
+```
+
+```jsx fileName="src/app/layout.csx" codeFormat="commonjs"
+require("./globals.css");
+
+const RootLayout = ({ children }) => children;
+
+module.exports = RootLayout;
+```
+
+Then create a locale-specific layout in `[locale]` directory:
+
+```tsx fileName="src/app/[locale]/layout.tsx" codeFormat="typescript"
+import { NextIntlClientProvider } from "next-intl";
+import { getMessages } from "next-intl/server";
+import { notFound } from "next/navigation";
+import { routing } from "@/i18n/routing";
+import type { ReactNode } from "react";
+
+export default async function LocaleLayout({
+  children,
+  params: { locale },
+}: {
+  children: ReactNode;
+  params: { locale: string };
+}) {
+  // Ensure the incoming locale is valid
+  if (!routing.locales.includes(locale as any)) {
+    notFound();
+  }
+
+  // Providing all messages to the client side is the easiest way to get started
+  const messages = await getMessages();
+
+  return (
+    <html lang={locale}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```jsx fileName="src/app/[locale]/layout.mjx" codeFormat="esm"
+import { NextIntlClientProvider } from "next-intl";
+import { getMessages } from "next-intl/server";
+import { notFound } from "next/navigation";
+import { routing } from "@/i18n/routing";
+
+export default async function LocaleLayout({ children, params: { locale } }) {
+  if (!routing.locales.includes(locale)) {
+    notFound();
+  }
+
+  const messages = await getMessages();
+
+  return (
+    <html lang={locale}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```jsx fileName="src/app/[locale]/layout.csx" codeFormat="commonjs"
+const { NextIntlClientProvider } = require("next-intl");
+const { getMessages } = require("next-intl/server");
+const { notFound } = require("next/navigation");
+const { routing } = require("@/i18n/routing");
+
+async function LocaleLayout({ children, params: { locale } }) {
+  if (!routing.locales.includes(locale)) {
+    notFound();
+  }
+
+  const messages = await getMessages();
+
+  return (
+    <html lang={locale}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}
+
+module.exports = LocaleLayout;
+```
+
+Create the routing configuration file:
+
+```typescript fileName="src/i18n/routing.ts" codeFormat="typescript"
+import { defineRouting } from "next-intl/routing";
+import { createSharedPathnamesNavigation } from "next-intl/navigation";
+
+export const routing = defineRouting({
+  locales: ["en", "fr", "es"],
+  defaultLocale: "en",
+});
+
+export const { Link, redirect, usePathname, useRouter } =
+  createSharedPathnamesNavigation(routing);
+```
+
+```javascript fileName="src/i18n/routing.mjs" codeFormat="esm"
+import { defineRouting } from "next-intl/routing";
+import { createSharedPathnamesNavigation } from "next-intl/navigation";
+
+export const routing = defineRouting({
+  locales: ["en", "fr", "es"],
+  defaultLocale: "en",
+});
+
+export const { Link, redirect, usePathname, useRouter } =
+  createSharedPathnamesNavigation(routing);
+```
+
+```javascript fileName="src/i18n/routing.cjs" codeFormat="commonjs"
+const { defineRouting } = require("next-intl/routing");
+const { createSharedPathnamesNavigation } = require("next-intl/navigation");
+
+const routing = defineRouting({
+  locales: ["en", "fr", "es"],
+  defaultLocale: "en",
+});
+
+const { Link, redirect, usePathname, useRouter } =
+  createSharedPathnamesNavigation(routing);
+
+module.exports = { routing, Link, redirect, usePathname, useRouter };
+```
+
+Create the next-intl configuration file:
+
+```typescript fileName="src/i18n/request.ts" codeFormat="typescript"
+import { getRequestConfig } from "next-intl/server";
+import { routing } from "./routing";
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  // This typically corresponds to the `[locale]` segment
+  let locale = await requestLocale;
+
+  // Ensure a valid locale is used
+  if (!locale || !routing.locales.includes(locale as any)) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    messages: (await import(`../../intl/messages/${locale}.json`)).default,
+  };
+});
+```
+
+```javascript fileName="src/i18n/request.mjs" codeFormat="esm"
+import { getRequestConfig } from "next-intl/server";
+import { routing } from "./routing";
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  let locale = await requestLocale;
+
+  if (!locale || !routing.locales.includes(locale)) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    messages: (await import(`../../intl/messages/${locale}.json`)).default,
+  };
+});
+```
+
+```javascript fileName="src/i18n/request.cjs" codeFormat="commonjs"
+const { getRequestConfig } = require("next-intl/server");
+const { routing } = require("./routing");
+
+module.exports = getRequestConfig(async ({ requestLocale }) => {
+  let locale = await requestLocale;
+
+  if (!locale || !routing.locales.includes(locale)) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    messages: (await import(`../../intl/messages/${locale}.json`)).default,
+  };
+});
+```
+
+Update your Next.js config to use the next-intl plugin:
+
+```typescript fileName="next.config.ts" codeFormat="typescript"
+import type { NextConfig } from "next";
+import createNextIntlPlugin from "next-intl/plugin";
+
+const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
+
+const nextConfig: NextConfig = {
+  /* your config options here */
+};
+
+export default withNextIntl(nextConfig);
+```
+
+```javascript fileName="next.config.mjs" codeFormat="esm"
+import createNextIntlPlugin from "next-intl/plugin";
+
+const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* your config options here */
+};
 
-Below are examples of content declaration files in multiple formats. Intlayer will compile these into message files that next-intl can consume.
+export default withNextIntl(nextConfig);
+```
+
+```javascript fileName="next.config.cjs" codeFormat="commonjs"
+const createNextIntlPlugin = require("next-intl/plugin");
+
+const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  /* your config options here */
+};
 
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
+module.exports = withNextIntl(nextConfig);
+```
+
+### Step 6: Declare Your Content
+
+Create content declarations using Intlayer's flexible format:
+
+```typescript fileName="src/app/[locale]/page.content.ts" contentDeclarationFormat="typescript"
 import { t, type Dictionary } from "intlayer";
 
-const content = {
-  key: "my-component",
+const pageContent = {
+  key: "page",
   content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
+    getStarted: {
+      main: t({
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+    documentationLink: {
+      text: t({
+        en: "Read our documentation",
+        fr: "Lisez notre documentation",
+        es: "Lea nuestra documentación",
+      }),
+      href: "https://intlayer.org",
+    },
   },
 } satisfies Dictionary;
 
-export default content;
+export default pageContent;
 ```
 
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
+```javascript fileName="src/app/[locale]/page.content.mjs" contentDeclarationFormat="esm"
 import { t } from "intlayer";
 
 /** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
+const pageContent = {
+  key: "page",
   content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
+    getStarted: {
+      main: t({
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+    documentationLink: {
+      text: t({
+        en: "Read our documentation",
+        fr: "Lisez notre documentation",
+        es: "Lea nuestra documentación",
+      }),
+      href: "https://intlayer.org",
+    },
   },
 };
 
-export default content;
+export default pageContent;
 ```
 
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
+```javascript fileName="src/app/[locale]/page.content.cjs" contentDeclarationFormat="commonjs"
 const { t } = require("intlayer");
 
-module.exports = {
-  key: "my-component",
+/** @type {import('intlayer').Dictionary} */
+const pageContent = {
+  key: "page",
   content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
+    getStarted: {
+      main: t({
+        en: "Get started by editing",
+        fr: "Commencez par éditer",
+        es: "Comience por editar",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+    documentationLink: {
+      text: t({
+        en: "Read our documentation",
+        fr: "Lisez notre documentation",
+        es: "Lea nuestra documentación",
+      }),
+      href: "https://intlayer.org",
+    },
   },
 };
+
+module.exports = pageContent;
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
+```json fileName="src/app/[locale]/page.content.json" contentDeclarationFormat="json"
 {
   "$schema": "https://intlayer.org/schema.json",
-  "key": "my-component",
+  "key": "page",
   "content": {
-    "helloWorld": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
+    "getStarted": {
+      "main": {
+        "nodeType": "translation",
+        "translation": {
+          "en": "Get started by editing",
+          "fr": "Commencez par éditer",
+          "es": "Comience por editar"
+        }
+      },
+      "pageLink": "src/app/page.tsx"
+    },
+    "documentationLink": {
+      "text": {
+        "nodeType": "translation",
+        "translation": {
+          "en": "Read our documentation",
+          "fr": "Lisez notre documentation",
+          "es": "Lea nuestra documentación"
+        }
+      },
+      "href": "https://intlayer.org"
     }
   }
 }
 ```
 
-### Build the next-intl Messages
+> Your content declarations can be defined anywhere in your application as long as they are included in the `contentDir` directory (by default, `./src`) and match the content declaration file extension (by default, `.content.{ts,tsx,js,jsx,mjs,cjs,json}`).
+
+> For more details about content declaration, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
 
-To build the message files for next-intl, run:
+### Step 7: Build and Generate next-intl Messages
+
+Build your content declarations to generate next-intl compatible message files:
 
 ```bash packageManager="npm"
 npx intlayer build
@@ -217,149 +702,433 @@ yarn intlayer build
 pnpm intlayer build
 ```
 
-This will generate resources in the `./intl/messages` directory (as configured in `intlayer.config.*`). The expected output:
+This will generate resources in the `./intl/messages` directory. The expected output:
 
 ```bash
 .
 └── intl
     └── messages
-       └── en
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
-```
-
-Each file includes compiled messages from all Intlayer content declarations. The top-level keys typically match your `content.key` fields.
-
-### Using next-intl in Your Next.js App
-
-> For more details, see the official [next-intl usage docs](https://github.com/amannn/next-intl#readme).
-
-1. **Create a Middleware (optional):**  
-   If you want to manage automatic locale detection or redirection, use next-intl’s [createMiddleware](https://github.com/amannn/next-intl#createMiddleware).
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["en", "fr", "es"],
-     defaultLocale: "en",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **Create a `layout.tsx` or `_app.tsx` to Load Messages:**  
-   If you’re using the App Router (Next.js 13+), create a layout:
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
-
-
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
-
-     return (
-       <html lang={params.locale}>
-         <body>
-           <NextIntlClientProvider locale={params.locale} messages={messages}>
-             {children}
-           </NextIntlClientProvider>
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   If you’re using the Pages Router (Next.js 12 or below), load messages in `_app.tsx`:
-
-   ```typescript fileName="pages/_app.tsx"
-   import type { AppProps } from 'next/app';
-   import { NextIntlProvider } from 'next-intl';
-
-   function MyApp({ Component, pageProps }: AppProps) {
-     return (
-       <NextIntlProvider locale={pageProps.locale} messages={pageProps.messages}>
-         <Component {...pageProps} />
-       </NextIntlProvider>
-     );
-   }
-
-   export default MyApp;
-   ```
-
-3. **Fetch Messages Server-Side (Pages Router example):**
-
-   ```typescript fileName="pages/index.tsx"
-   import { GetServerSideProps } from "next";
-   import HomePage from "../components/HomePage";
-
-   export default HomePage;
-
-   export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
-     const messages = (await import(`../intl/messages/${locale}.json`)).default;
-
-     return {
-       props: {
-         locale,
-         messages,
-       },
-     };
-   };
-   ```
-
-### Using Content in Next.js Components
-
-Once the messages are loaded into next-intl, you can use them in your components via the `useTranslations()` hook:
+        ├── en.json
+        ├── fr.json
+        └── es.json
+```
+
+Each JSON file contains compiled messages from all Intlayer content declarations, structured for next-intl consumption.
 
-```typescript fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
+### Step 8: Utilize Content in Your Code
+
+Access your translations in your components using next-intl's hooks:
+
+```tsx fileName="src/app/[locale]/page.tsx" codeFormat="typescript"
 import type { FC } from "react";
-import { useTranslations } from 'next-intl';
+import { useTranslations } from "next-intl";
 
-const MyComponent: FC = () => {
-  const t = useTranslations('my-component');
-  // 'my-component' corresponds to the content key in Intlayer
+const Page: FC = () => {
+  const t = useTranslations("page");
 
   return (
     <div>
-      <h1>{t('helloWorld')}</h1>
+      <h1>{t("getStarted.main")}</h1>
+      <code>{t("getStarted.pageLink")}</code>
+
+      <a href={t("documentationLink.href")}>{t("documentationLink.text")}</a>
     </div>
   );
 };
 
-export default MyComponent;
+export default Page;
 ```
 
-```jsx fileName="src/components/MyComponent/index.jsx" codeFormat="esm"
+```jsx fileName="src/app/[locale]/page.mjx" codeFormat="esm"
 import { useTranslations } from "next-intl";
 
-export default function MyComponent() {
-  const t = useTranslations("my-component");
+export default function Page() {
+  const t = useTranslations("page");
 
   return (
     <div>
-      <h1>{t("helloWorld")}</h1>
+      <h1>{t("getStarted.main")}</h1>
+      <code>{t("getStarted.pageLink")}</code>
+
+      <a href={t("documentationLink.href")}>{t("documentationLink.text")}</a>
     </div>
   );
 }
 ```
 
-**That’s it!** Whenever you update or add new Intlayer content declaration files, re-run the `intlayer build` command to regenerate your next-intl JSON messages. next-intl will pick up the updated content automatically.
+```jsx fileName="src/app/[locale]/page.csx" codeFormat="commonjs"
+const { useTranslations } = require("next-intl");
+
+function Page() {
+  const t = useTranslations("page");
+
+  return (
+    <div>
+      <h1>{t("getStarted.main")}</h1>
+      <code>{t("getStarted.pageLink")}</code>
+
+      <a href={t("documentationLink.href")}>{t("documentationLink.text")}</a>
+    </div>
+  );
+}
+
+module.exports = Page;
+```
+
+> The first parameter of `useTranslations` corresponds to the `key` in your Intlayer content declaration. The nested properties are accessed using dot notation.
+
+### (Optional) Step 9: Internationalization of Your Metadata
+
+For metadata like page titles and descriptions:
+
+```typescript fileName="src/app/[locale]/metadata.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+import type { Metadata } from "next";
+
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      en: "My Application",
+      fr: "Mon Application",
+      es: "Mi Aplicación",
+    }),
+    description: t({
+      en: "Welcome to my Next.js application",
+      fr: "Bienvenue dans mon application Next.js",
+      es: "Bienvenido a mi aplicación Next.js",
+    }),
+  },
+} satisfies Dictionary<Metadata>;
+
+export default metadataContent;
+```
+
+```javascript fileName="src/app/[locale]/metadata.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      en: "My Application",
+      fr: "Mon Application",
+      es: "Mi Aplicación",
+    }),
+    description: t({
+      en: "Welcome to my Next.js application",
+      fr: "Bienvenue dans mon application Next.js",
+      es: "Bienvenido a mi aplicación Next.js",
+    }),
+  },
+};
+
+export default metadataContent;
+```
+
+```javascript fileName="src/app/[locale]/metadata.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "metadata",
+  content: {
+    title: t({
+      en: "My Application",
+      fr: "Mon Application",
+      es: "Mi Aplicación",
+    }),
+    description: t({
+      en: "Welcome to my Next.js application",
+      fr: "Bienvenue dans mon application Next.js",
+      es: "Bienvenido a mi aplicación Next.js",
+    }),
+  },
+};
+
+module.exports = metadataContent;
+```
+
+Use in your layout or page:
+
+```tsx fileName="src/app/[locale]/layout.tsx" codeFormat="typescript"
+import { getTranslations } from "next-intl/server";
+import type { Metadata } from "next";
+
+export async function generateMetadata({
+  params: { locale },
+}: {
+  params: { locale: string };
+}): Promise<Metadata> {
+  const t = await getTranslations({ locale, namespace: "metadata" });
+
+  return {
+    title: t("title"),
+    description: t("description"),
+  };
+}
+
+// ... rest of your layout
+```
+
+### (Optional) Step 10: Internationalization of sitemap.xml and robots.txt
+
+For SEO optimization, internationalize your sitemap and robots files:
+
+```typescript fileName="src/app/sitemap.ts" codeFormat="typescript"
+import { MetadataRoute } from "next";
+import { routing } from "@/i18n/routing";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return [
+    {
+      url: "https://example.com",
+      lastModified: new Date(),
+      alternates: {
+        languages: Object.fromEntries(
+          routing.locales.map((locale) => [
+            locale,
+            `https://example.com/${locale}`,
+          ])
+        ),
+      },
+    },
+  ];
+}
+```
+
+```javascript fileName="src/app/sitemap.mjs" codeFormat="esm"
+import { routing } from "@/i18n/routing";
+
+export default function sitemap() {
+  return [
+    {
+      url: "https://example.com",
+      lastModified: new Date(),
+      alternates: {
+        languages: Object.fromEntries(
+          routing.locales.map((locale) => [
+            locale,
+            `https://example.com/${locale}`,
+          ])
+        ),
+      },
+    },
+  ];
+}
+```
+
+```javascript fileName="src/app/sitemap.cjs" codeFormat="commonjs"
+const { routing } = require("@/i18n/routing");
+
+function sitemap() {
+  return [
+    {
+      url: "https://example.com",
+      lastModified: new Date(),
+      alternates: {
+        languages: Object.fromEntries(
+          routing.locales.map((locale) => [
+            locale,
+            `https://example.com/${locale}`,
+          ])
+        ),
+      },
+    },
+  ];
+}
+
+module.exports = sitemap;
+```
+
+### (Optional) Step 11: Change the Language of Your Content
+
+Create a language switcher component:
+
+```tsx fileName="src/components/LanguageSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import { useLocale } from "next-intl";
+import { useRouter, usePathname } from "@/i18n/routing";
+import { routing } from "@/i18n/routing";
+import type { FC } from "react";
+
+export const LanguageSwitcher: FC = () => {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const handleLocaleChange = (newLocale: string) => {
+    router.replace(pathname, { locale: newLocale });
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {routing.locales.map((loc) => (
+        <option key={loc} value={loc}>
+          {loc.toUpperCase()}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LanguageSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { useLocale } from "next-intl";
+import { useRouter, usePathname } from "@/i18n/routing";
+import { routing } from "@/i18n/routing";
+
+export const LanguageSwitcher = () => {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const handleLocaleChange = (newLocale) => {
+    router.replace(pathname, { locale: newLocale });
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {routing.locales.map((loc) => (
+        <option key={loc} value={loc}>
+          {loc.toUpperCase()}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LanguageSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { useLocale } = require("next-intl");
+const { useRouter, usePathname } = require("@/i18n/routing");
+const { routing } = require("@/i18n/routing");
+
+const LanguageSwitcher = () => {
+  const locale = useLocale();
+  const router = useRouter();
+  const pathname = usePathname();
+
+  const handleLocaleChange = (newLocale) => {
+    router.replace(pathname, { locale: newLocale });
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {routing.locales.map((loc) => (
+        <option key={loc} value={loc}>
+          {loc.toUpperCase()}
+        </option>
+      ))}
+    </select>
+  );
+};
+
+module.exports = { LanguageSwitcher };
+```
+
+### (Optional) Step 12: Creating a Localized Link Component
+
+For locale-aware navigation, use the `Link` component from your routing configuration:
+
+```tsx fileName="src/components/LocalizedLink.tsx" codeFormat="typescript"
+import { Link } from "@/i18n/routing";
+import type { ComponentProps, FC } from "react";
+
+export const LocalizedLink: FC<ComponentProps<typeof Link>> = (props) => {
+  return <Link {...props} />;
+};
+```
+
+```jsx fileName="src/components/LocalizedLink.mjx" codeFormat="esm"
+import { Link } from "@/i18n/routing";
+
+export const LocalizedLink = (props) => {
+  return <Link {...props} />;
+};
+```
+
+```jsx fileName="src/components/LocalizedLink.csx" codeFormat="commonjs"
+const { Link } = require("@/i18n/routing");
+
+const LocalizedLink = (props) => {
+  return <Link {...props} />;
+};
+
+module.exports = { LocalizedLink };
+```
+
+Use it in your application:
+
+```tsx
+import { LocalizedLink } from "@/components/LocalizedLink";
+
+export default function Navigation() {
+  return (
+    <nav>
+      <LocalizedLink href="/">Home</LocalizedLink>
+      <LocalizedLink href="/about">About</LocalizedLink>
+      <LocalizedLink href="/contact">Contact</LocalizedLink>
+    </nav>
+  );
+}
+```
+
+---
+
+## Updating or Adding New Translations
+
+1. **Add or modify** content in any `*.content.*` file
+2. Run `intlayer build` to regenerate the JSON files
+3. Next.js (and next-intl) will automatically pick up the changes on the next rebuild or in development mode
+
+---
+
+## TypeScript Configuration
+
+Intlayer provides **autogenerated type definitions** for your content. Ensure TypeScript picks them up:
+
+```json5 fileName="tsconfig.json"
+{
+  "compilerOptions": {
+    // ... your other compiler options
+  },
+  "include": [
+    "src",
+    ".intlayer/**/*.ts", // Include Intlayer auto-generated types
+  ],
+}
+```
+
+This provides autocompletion and type checking for your translation keys.
+
+---
+
+## Git Configuration
+
+It's recommended to ignore auto-generated Intlayer files:
+
+```plaintext fileName=".gitignore"
+# Ignore files generated by Intlayer
+.intlayer
+intl
+```
+
+These files can be regenerated during your build process and don't need to be committed to version control.
+
+---
+
+## Further Resources and Learning
+
+- **[Intlayer Documentation](https://intlayer.org)**: Comprehensive guides and API reference
+- **[next-intl Documentation](https://next-intl-docs.vercel.app)**: Official next-intl documentation
+- **[Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)**: Manage translations through a visual interface
+- **[Intlayer CLI Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md)**: Command-line tools for managing translations
+
+By combining Intlayer's flexible content declaration approach with next-intl's proven routing and middleware capabilities, you can create a powerful internationalization solution for your Next.js application. This hybrid approach allows you to leverage the best features of both libraries while maintaining a clean, maintainable codebase.