@intlayer/docs 7.0.3-canary.1 → 7.0.4-canary.0

package/blog/en/intlayer_with_react-i18next.md

@@ -1,17 +1,19 @@
 ---
 createdAt: 2025-01-02
 updatedAt: 2025-10-29
-title: Intlayer and react-i18next
-description: Compare Intlayer with react-i18next for a React app
+title: How to use Intlayer with react-i18next – Complete i18n Guide 2025
+description: Learn how to integrate Intlayer with react-i18next to build a fully internationalized React application. Comprehensive guide with step-by-step instructions, code examples, and best practices.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - Internationalization
+  - i18n
   - Blog
-  - Next.js
-  - JavaScript
   - React
+  - JavaScript
+  - TypeScript
+  - Content Management
 slugs:
   - blog
   - intlayer-with-react-i18next
@@ -23,108 +25,159 @@ history:
 
 # React Internationalization (i18n) with react-i18next and Intlayer
 
-## Overview
+## Table of Contents
 
-- **Intlayer** helps you manage translations via **component-level** content declaration files.
-- **react-i18next** is a popular React integration for **i18next** that provides hooks like `useTranslation` to fetch localized strings in your components.
+<TOC/>
 
-When combined, Intlayer can **export** dictionaries in **i18next-compatible JSON** so that react-i18next can **consume** them at runtime.
+## What is Intlayer?
 
-## Table of Contents
+**Intlayer** is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications. Intlayer seamlessly integrates with popular frameworks like **React**, **Next.js**, **Vue**, and many others.
+
+With Intlayer, you can:
 
-<TOC>
+- **Easily manage translations** using declarative dictionaries at the component level.
+- **Dynamically localize content** with a flexible architecture.
+- **Access translations** with full TypeScript support and autogenerated types.
+- **Benefit from advanced features**, like dynamic locale detection, switching, and content externalization.
+- **Integrate with existing i18n solutions** like react-i18next, next-intl, and react-intl.
+
+---
 
 ## Why Use Intlayer with react-i18next?
 
-**Intlayer** content declaration files offer a better developer experience because they are:
+**react-i18next** is one of the most popular React integrations for **i18next**, providing hooks like `useTranslation` to fetch localized strings in your components. While powerful, react-i18next traditionally relies on JSON files organized in a centralized structure, which can lead to maintenance challenges as your application grows.
 
-1. **Flexible in File Placement**  
-   Put each content declaration file right next to the component that needs it. This structure allows you to keep translations co-located, preventing orphaned translations when components move or get deleted.
+**Intlayer** enhances this workflow by offering:
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Content declaration file
-               └── index.tsx
-   ```
+### 1. **Flexible Component-Level Content Declaration**
 
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Content declaration file
-               └── index.mjx
-   ```
+With Intlayer, you can place content declaration files right next to the components that need them. This co-location prevents orphaned translations when components are moved or deleted.
 
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Content declaration file
-               └── index.cjx
-   ```
+**Example Structure:**
 
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Content declaration file
-               └── index.jsx
-   ```
+```bash codeFormat="typescript"
+.
+└── src
+    └── components
+        └── MyComponent
+            ├── index.content.ts # Content declaration file
+            └── index.tsx
+```
 
-2. **Centralized Translations**  
-   A single content declaration file collects all necessary translations for a component, making missing translations easier to catch.  
-   With TypeScript, you even get compile-time errors if translations are missing.
+```bash codeFormat="esm"
+.
+└── src
+    └── components
+        └── MyComponent
+            ├── index.content.mjs # Content declaration file
+            └── index.mjx
+```
 
-## Installation
+```bash codeFormat="commonjs"
+.
+└── src
+    └── components
+        └── MyComponent
+            ├── index.content.cjs # Content declaration file
+            └── index.cjx
+```
 
-In a Create React App project, install these dependencies:
+```bash codeFormat="json"
+.
+└── src
+    └── components
+        └── MyComponent
+            ├── index.content.json # Content declaration file
+            └── index.jsx
+```
 
-```bash
-# With npm
+### 2. **Centralized Translations per Component**
+
+A single content declaration file collects all necessary translations for a component. This makes missing translations easier to catch, especially when combined with TypeScript, which provides compile-time validation.
+
+### 3. **Automated Dictionary Building**
+
+Intlayer automatically transpiles your content declarations into i18next-compatible JSON files, eliminating manual JSON management.
+
+### 4. **Enhanced Developer Experience**
+
+- **Type Safety**: Autogenerated TypeScript types ensure autocompletion and error detection.
+- **Better Organization**: Keep translations close to their usage, improving code readability and maintainability.
+- **Scalability**: Easily scale your internationalization strategy as your application grows.
+
+---
+
+## Intlayer vs. react-i18next: Key Differences
+
+For a comprehensive comparison of Intlayer with other i18n libraries for React (including react-i18next and react-intl), check out the [react-i18next vs. react-intl vs. Intlayer blog post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/react-i18next_vs_react-intl_vs_intlayer.md).
+
+**Key Takeaways:**
+
+- **Intlayer** focuses on **component-level** content management, while react-i18next typically uses centralized JSON files.
+- **Intlayer** offers built-in **TypeScript support** with autogenerated types, whereas react-i18next requires additional configuration for type safety.
+- **Intlayer** can integrate with react-i18next to provide the best of both worlds: component-level content management with the robust runtime features of i18next.
+
+---
+
+## Step-by-Step Guide to Set Up Intlayer with react-i18next
+
+### Step 1: Install Dependencies
+
+Install the necessary packages using your preferred package manager:
+
+```bash packageManager="npm"
 npm install intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
 ```
 
-```bash
-# With yarn
-yarn add intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
+```bash packageManager="pnpm"
+pnpm add intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
 ```
 
-```bash
-# With pnpm
-pnpm add intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
+```bash packageManager="yarn"
+yarn add intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
 ```
 
-### What Are These Packages?
+#### What Are These Packages?
+
+- **intlayer**  
+  The core library that provides internationalization tools for configuration management, translation, content declaration, transpilation, and CLI commands.
+
+- **react-i18next**  
+  React-specific integration library for i18next, including the `useTranslation` hook and other React bindings.
 
-- **intlayer** – The CLI and core library for managing i18n configurations, content declarations, and building dictionary outputs.
-- **react-intlayer** – React-specific integration for Intlayer, providing notably some script to automate the build of dictionaries.
-- **react-i18next** – React-specific integration library for i18next, including the `useTranslation` hook.
-- **i18next** – The underlying framework for translation handling.
-- **i18next-resources-to-backend** – An i18next backend that dynamically imports JSON resources.
-- **@intlayer/sync-json-plugin** – A plugin for Intlayer that syncs JSON files to dictionaries.
+- **i18next**  
+  The underlying framework for translation handling. It provides the core internationalization functionality.
+
+- **i18next-resources-to-backend**  
+  An i18next backend that dynamically imports JSON resources, enabling efficient lazy-loading of translations.
+
+- **@intlayer/sync-json-plugin**  
+  A plugin for Intlayer that automatically exports your content declarations as i18next-compatible JSON files.
+
+---
 
-## Configuring Intlayer to Export i18next Dictionaries
+### Step 2: Configure Your Project
 
-Create (or update) your `intlayer.config.ts` in the root of your project:
+Create a configuration file to define the languages and settings for your application:
 
-```typescript title="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: {
-    // Add as many locales as you wish
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Add your other locales
+    ],
     defaultLocale: Locales.ENGLISH,
   },
   plugins: [
     syncJSON({
-      source: ({ key, locale }) => `./i18next/resources/${locale}/${key}.json`,
+      // Adjust the source path to match your desired output structure
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
     }),
   ],
 };
@@ -132,50 +185,106 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> **Note**: If you’re not using TypeScript, you can create this config file as `.cjs`, `.mjs`, or `.js` (see the [Intlayer docs](https://intlayer.org/en/doc/concept/configuration) for details).
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-## Building the i18next Resources
+/** @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`,
+    }),
+  ],
+};
 
-Once your content declarations are in place (next section), run the **Intlayer build command**:
+export default config;
+```
 
-```bash
-# With npm
-npx run intlayer build
+```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;
 ```
 
-```bash
-# With yarn
-yarn intlayer build
+> **Note**: Through this configuration file, you can customize content directory location, file extensions, output paths, and more. For a complete list of available parameters, refer to the [Intlayer configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
+
+---
+
+### Step 3: Build the i18next Resources
+
+Once your content declarations are in place (covered in Step 5), run the **Intlayer build command** to generate i18next-compatible JSON files:
+
+```bash packageManager="npm"
+npx intlayer build
 ```
 
-```bash
-# With pnpm
+```bash packageManager="pnpm"
 pnpm intlayer build
 ```
 
-> This will generate your i18next resources inside the `./i18next/resources` directory by default.
+```bash packageManager="yarn"
+yarn intlayer build
+```
 
-A typical output might look like this:
+> This command will scan your project for `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` files, compile them, and write the output to the directory specified in your `intlayer.config.*` (by default, `./intl/messages`).
+
+**Expected Output:**
 
 ```bash
 .
-└── i18next
-    └── resources
-       ├── en
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
+└── intl
+    └── messages
+        ├── en
+        │   ├── my-component.json
+        │   └── another-component.json
+        ├── fr
+        │   ├── my-component.json
+        │   └── another-component.json
+        └── es
+            ├── my-component.json
+            └── another-component.json
 ```
 
-Where each **Intlayer** declaration key is used as an **i18next namespace** (e.g., `my-content.json`).
+Each file corresponds to an **i18next namespace**, derived from the `key` in your Intlayer content declarations.
 
-## Importing Dictionaries into Your react-i18next Configuration
+---
 
-To dynamically load these resources at runtime, use [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend). For instance, create an `i18n.ts` (or `.js`) file in your project:
+### Step 4: Integrate i18next in Your React Application
 
-```typescript title="i18n.ts"
+Configure i18next to load the generated JSON resources dynamically. Use the [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend) package for this purpose.
+
+Create an `i18n` initialization file (e.g., `src/i18n.ts` or `src/i18n.js`):
+
+```typescript fileName="src/i18n.ts" codeFormat="typescript"
 import i18next from "i18next";
 import { initReactI18next } from "react-i18next";
 import resourcesToBackend from "i18next-resources-to-backend";
@@ -183,11 +292,11 @@ import resourcesToBackend from "i18next-resources-to-backend";
 i18next
   // react-i18next plugin
   .use(initReactI18next)
-  // dynamically load resources
+  // Dynamically load resources
   .use(
     resourcesToBackend((language: string, namespace: string) => {
-      // Adjust the import path to your resources directory
-      return import(`../i18next/resources/${language}/${namespace}.json`);
+      // Adjust the import path to match your output directory
+      return import(`../intl/messages/${language}/${namespace}.json`);
     })
   )
   // Initialize i18next
@@ -195,14 +304,23 @@ i18next
     // Fallback locale
     fallbackLng: "en",
 
-    // You can add other i18next config options here, see:
-    // https://www.i18next.com/overview/configuration-options
+    // Enable debug mode during development
+    debug: process.env.NODE_ENV === "development",
+
+    // Namespaces to load by default (optional)
+    // defaultNS: "common",
+
+    // Other i18next configuration options
+    // See: https://www.i18next.com/overview/configuration-options
+    interpolation: {
+      escapeValue: false, // React already escapes values
+    },
   });
 
 export default i18next;
 ```
 
-```javascript title="i18n.js"
+```javascript fileName="src/i18n.js" codeFormat="esm"
 import i18next from "i18next";
 import { initReactI18next } from "react-i18next";
 import resourcesToBackend from "i18next-resources-to-backend";
@@ -212,19 +330,47 @@ i18next
   .use(
     resourcesToBackend(
       (language, namespace) =>
-        import(`../i18next/resources/${language}/${namespace}.json`)
+        import(`../intl/messages/${language}/${namespace}.json`)
     )
   )
   .init({
     fallbackLng: "en",
+    debug: process.env.NODE_ENV === "development",
+    interpolation: {
+      escapeValue: false,
+    },
   });
 
 export default i18next;
 ```
 
-Then, in your **root** or **index** file (e.g., `src/index.tsx`), import this `i18n` setup **before** rendering the `App`:
+```javascript fileName="src/i18n.cjs" codeFormat="commonjs"
+const i18next = require("i18next");
+const { initReactI18next } = require("react-i18next");
+const resourcesToBackend = require("i18next-resources-to-backend");
+
+i18next
+  .use(initReactI18next)
+  .use(
+    resourcesToBackend(
+      (language, namespace) =>
+        import(`../intl/messages/${language}/${namespace}.json`)
+    )
+  )
+  .init({
+    fallbackLng: "en",
+    debug: process.env.NODE_ENV === "development",
+    interpolation: {
+      escapeValue: false,
+    },
+  });
 
-```typescript
+module.exports = i18next;
+```
+
+Then, import this i18n setup **before** rendering your application. In your root/index file (e.g., `src/index.tsx`):
+
+```typescript fileName="src/index.tsx" codeFormat="typescript"
 import React from "react";
 import ReactDOM from "react-dom/client";
 // Initialize i18n before anything else
@@ -238,47 +384,167 @@ ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
 );
 ```
 
-## Creating and Managing Your Dictionarys
+```javascript fileName="src/index.jsx" codeFormat="esm"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import "./i18n";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const React = require("react");
+const ReactDOM = require("react-dom/client");
+require("./i18n");
+const App = require("./App");
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  React.createElement(React.StrictMode, null, React.createElement(App))
+);
+```
+
+---
+
+### Step 5: Declare Your Content
+
+Create and manage your content declarations to store translations. Intlayer content declaration files can be placed anywhere in your project, as long as they match the configured file pattern.
 
-Intlayer extracts translations from “content declaration files” located anywhere under `./src` (by default).  
-Here’s a minimal example in TypeScript:
+**Example Content Declaration:**
 
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
+```typescript fileName="src/components/MyComponent/MyComponent.content.ts" contentDeclarationFormat="typescript"
 import { t, type Dictionary } from "intlayer";
 
-const content = {
-  // The "key" will be your i18next namespace (e.g., "my-component")
+const myComponentContent = {
+  // The "key" becomes the i18next namespace
   key: "my-component",
   content: {
-    // Each "t" call is a separate translation node
+    // Each call to "t" defines a translation node
     heading: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
+      en: "Welcome to My Component",
+      fr: "Bienvenue dans mon composant",
+      es: "Bienvenido a mi componente",
     }),
     description: t({
-      en: "My i18n description text...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
+      en: "This is a description of my component.",
+      fr: "Ceci est une description de mon composant.",
+      es: "Esta es una descripción de mi componente.",
+    }),
+    buttonText: t({
+      en: "Click Me",
+      fr: "Cliquez-moi",
+      es: "Haz clic en mí",
     }),
   },
 } satisfies Dictionary;
 
-export default content;
+export default myComponentContent;
 ```
 
-If you prefer JSON, `.cjs`, or `.mjs`, refer to the [Intlayer docs](https://intlayer.org/en/doc/concept/content).
+```javascript fileName="src/components/MyComponent/MyComponent.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
 
-> By default, valid content declarations match the file extension pattern:
+/** @type {import('intlayer').Dictionary} */
+const myComponentContent = {
+  key: "my-component",
+  content: {
+    heading: t({
+      en: "Welcome to My Component",
+      fr: "Bienvenue dans mon composant",
+      es: "Bienvenido a mi componente",
+    }),
+    description: t({
+      en: "This is a description of my component.",
+      fr: "Ceci est une description de mon composant.",
+      es: "Esta es una descripción de mi componente.",
+    }),
+    buttonText: t({
+      en: "Click Me",
+      fr: "Cliquez-moi",
+      es: "Haz clic en mí",
+    }),
+  },
+};
 
-> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
+export default myComponentContent;
+```
 
-## Using the Translations in React Components
+```javascript fileName="src/components/MyComponent/MyComponent.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
 
-After you’ve **built** your Intlayer resources and configured react-i18next, you can directly use the `useTranslation` hook from **react-i18next**.  
-For instance:
+/** @type {import('intlayer').Dictionary} */
+const myComponentContent = {
+  key: "my-component",
+  content: {
+    heading: t({
+      en: "Welcome to My Component",
+      fr: "Bienvenue dans mon composant",
+      es: "Bienvenido a mi componente",
+    }),
+    description: t({
+      en: "This is a description of my component.",
+      fr: "Ceci est une description de mon composant.",
+      es: "Esta es una descripción de mi componente.",
+    }),
+    buttonText: t({
+      en: "Click Me",
+      fr: "Cliquez-moi",
+      es: "Haz clic en mí",
+    }),
+  },
+};
 
-```tsx title="src/components/MyComponent/MyComponent.tsx"
+module.exports = myComponentContent;
+```
+
+```json fileName="src/components/MyComponent/MyComponent.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my-component",
+  "content": {
+    "heading": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Welcome to My Component",
+        "fr": "Bienvenue dans mon composant",
+        "es": "Bienvenido a mi componente"
+      }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "This is a description of my component.",
+        "fr": "Ceci est une description de mon composant.",
+        "es": "Esta es una descripción de mi componente."
+      }
+    },
+    "buttonText": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Click Me",
+        "fr": "Cliquez-moi",
+        "es": "Haz clic en mí"
+      }
+    }
+  }
+}
+```
+
+> **Note**: 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, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
+
+---
+
+### Step 6: Utilize Content in Your Code
+
+Access your content dictionaries throughout your application using the `useTranslation` hook from react-i18next:
+
+```tsx fileName="src/components/MyComponent/MyComponent.tsx" codeFormat="typescript"
 import type { FC } from "react";
 import { useTranslation } from "react-i18next";
 
@@ -293,6 +559,7 @@ const MyComponent: FC = () => {
     <div>
       <h1>{t("heading")}</h1>
       <p>{t("description")}</p>
+      <button>{t("buttonText")}</button>
     </div>
   );
 };
@@ -300,53 +567,284 @@ const MyComponent: FC = () => {
 export default MyComponent;
 ```
 
-> Note that the `t` function references **keys** inside your generated JSON. For an Intlayer content entry named `heading`, you’ll use `t("heading")`.
+```jsx fileName="src/components/MyComponent/MyComponent.jsx" codeFormat="esm"
+import { useTranslation } from "react-i18next";
+
+const MyComponent = () => {
+  const { t } = useTranslation("my-component");
+
+  return (
+    <div>
+      <h1>{t("heading")}</h1>
+      <p>{t("description")}</p>
+      <button>{t("buttonText")}</button>
+    </div>
+  );
+};
 
-## Optional: Integrate with Create React App Scripts (CRACO)
+export default MyComponent;
+```
 
-**react-intlayer** provides a CRACO-based approach for custom builds and dev server configuration. If you want Intlayer’s build step integrated seamlessly, you can:
+```jsx fileName="src/components/MyComponent/MyComponent.csx" codeFormat="commonjs"
+const { useTranslation } = require("react-i18next");
+
+const MyComponent = () => {
+  const { t } = useTranslation("my-component");
+
+  return (
+    <div>
+      <h1>{t("heading")}</h1>
+      <p>{t("description")}</p>
+      <button>{t("buttonText")}</button>
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```
+
+> **Key Point**: The `t` function references keys inside your generated JSON. For an Intlayer content entry named `heading`, you'll use `t("heading")`.
+
+---
+
+### (Optional) Step 7: Change the Language of Your Content
+
+To allow users to switch languages dynamically, use the `changeLanguage` function provided by i18next. Here's an example of a simple locale switcher:
+
+```tsx fileName="src/components/LocaleSwitcher/LocaleSwitcher.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useTranslation } from "react-i18next";
+
+const LocaleSwitcher: FC = () => {
+  const { i18n } = useTranslation();
+
+  const changeLanguage = (locale: string) => {
+    i18n.changeLanguage(locale);
+  };
+
+  return (
+    <div>
+      <button
+        onClick={() => changeLanguage("en")}
+        disabled={i18n.language === "en"}
+      >
+        English
+      </button>
+      <button
+        onClick={() => changeLanguage("fr")}
+        disabled={i18n.language === "fr"}
+      >
+        Français
+      </button>
+      <button
+        onClick={() => changeLanguage("es")}
+        disabled={i18n.language === "es"}
+      >
+        Español
+      </button>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher/LocaleSwitcher.jsx" codeFormat="esm"
+import { useTranslation } from "react-i18next";
 
-1. **Install react-intlayer** (if you haven’t):
-   ```bash
+const LocaleSwitcher = () => {
+  const { i18n } = useTranslation();
+
+  const changeLanguage = (locale) => {
+    i18n.changeLanguage(locale);
+  };
+
+  return (
+    <div>
+      <button
+        onClick={() => changeLanguage("en")}
+        disabled={i18n.language === "en"}
+      >
+        English
+      </button>
+      <button
+        onClick={() => changeLanguage("fr")}
+        disabled={i18n.language === "fr"}
+      >
+        Français
+      </button>
+      <button
+        onClick={() => changeLanguage("es")}
+        disabled={i18n.language === "es"}
+      >
+        Español
+      </button>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useTranslation } = require("react-i18next");
+
+const LocaleSwitcher = () => {
+  const { i18n } = useTranslation();
+
+  const changeLanguage = (locale) => {
+    i18n.changeLanguage(locale);
+  };
+
+  return (
+    <div>
+      <button
+        onClick={() => changeLanguage("en")}
+        disabled={i18n.language === "en"}
+      >
+        English
+      </button>
+      <button
+        onClick={() => changeLanguage("fr")}
+        disabled={i18n.language === "fr"}
+      >
+        Français
+      </button>
+      <button
+        onClick={() => changeLanguage("es")}
+        disabled={i18n.language === "es"}
+      >
+        Español
+      </button>
+    </div>
+  );
+};
+
+module.exports = LocaleSwitcher;
+```
+
+---
+
+### (Optional) Step 8: Integrate with Create React App Scripts (CRACO)
+
+**react-intlayer** provides a CRACO-based approach for custom builds and dev server configuration. If you want Intlayer's build step integrated seamlessly into your Create React App workflow, follow these steps:
+
+1. **Install react-intlayer** (if you haven't):
+
+   ```bash packageManager="npm"
    npm install react-intlayer --save-dev
    ```
+
+   ```bash packageManager="pnpm"
+   pnpm add react-intlayer --save-dev
+   ```
+
+   ```bash packageManager="yarn"
+   yarn add react-intlayer --save-dev
+   ```
+
 2. **Adjust your `package.json` scripts** to use `react-intlayer` scripts:
 
-   ```jsonc
-   "scripts": {
-     "start": "react-intlayer start",
-     "build": "react-intlayer build",
-     "transpile": "intlayer build"
+   ```json fileName="package.json"
+   {
+     "scripts": {
+       "start": "react-intlayer start",
+       "build": "react-intlayer build",
+       "transpile": "intlayer build"
+     }
    }
    ```
 
-   > `react-intlayer` scripts are based on [CRACO](https://craco.js.org/). You can also implement your own setup based on the intlayer craco plugin. [See example here](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
+   > The `react-intlayer` scripts are based on [CRACO](https://craco.js.org/). You can also implement your own setup based on the intlayer craco plugin. [See example here](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
 
 Now, running `npm run build`, `yarn build`, or `pnpm build` triggers both Intlayer and CRA builds.
 
-## TypeScript Configuration
+---
+
+### (Optional) Step 9: Optimize Your Bundle Size
+
+As your application scales, you may want to optimize the bundle size by ensuring only the required translations are loaded. While i18next with `i18next-resources-to-backend` already provides lazy-loading capabilities, you can further optimize by:
+
+- **Code-Splitting**: Use dynamic imports to load components and their translations on demand.
+- **Tree-Shaking**: Ensure your build tool (e.g., Webpack, Vite) is configured to remove unused code.
+- **Namespace Splitting**: Split translations into multiple namespaces and load them as needed.
+
+For more optimization techniques, refer to the [i18next documentation](https://www.i18next.com/principles/performance) and your build tool's documentation.
+
+---
+
+### Configure TypeScript
+
+**Intlayer** provides **autogenerated type definitions** for your content, enabling TypeScript autocompletion and error detection.
 
-**Intlayer** provides **autogenerated type definitions** for your content. To ensure TypeScript picks them up, add **`types`** (or `types` if you configured differently) to your `tsconfig.json` **include** array:
+To ensure TypeScript picks them up, add the autogenerated types directory to your `tsconfig.json` **include** array:
 
-```json5 title="tsconfig.json"
+```json5 fileName="tsconfig.json"
 {
   "compilerOptions": {
-    // ...
+    // Your existing TypeScript configurations
   },
-  "include": ["src", "types"],
+  "include": [
+    "src",
+    "types", // Include the auto-generated types
+  ],
 }
 ```
 
-> This will let TypeScript infer the shape of your translations for better autocompletion and error detection.
+> This enables TypeScript to infer the shape of your translations, providing better autocompletion and compile-time error detection.
+
+---
+
+### Git Configuration
 
-## Git Configuration
+It is recommended to **ignore** auto-generated files and folders from Intlayer. This avoids committing them to your Git repository.
 
-It is recommended to **ignore** auto-generated files and folders from Intlayer. Add this line to your `.gitignore`:
+Add the following lines to your `.gitignore` file:
 
-```plaintext
+```plaintext fileName=".gitignore"
 # Ignore the files generated by Intlayer
 .intlayer
-i18next
+intl
 ```
 
 You typically do **not** commit these resources or `.intlayer` internal build artifacts, as they can be regenerated on each build.
+
+---
+
+### VS Code Extension
+
+To improve your development experience with Intlayer, consider installing 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, refer to the [Intlayer VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+---
+
+### Go Further
+
+To explore more advanced use cases and integrations:
+
+- **[Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)**: Use the visual editor to manage translations directly from your application UI.
+- **[Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**: Externalize your content management using the Intlayer CMS for seamless collaboration with non-technical team members.
+- **[Intlayer with Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_16.md)**: Learn how to integrate Intlayer with Next.js for server-side rendering and static site generation.
+
+---
+
+## Conclusion
+
+By integrating **Intlayer** with **react-i18next**, you combine the best of both worlds:
+
+- **Component-level content management** with Intlayer's flexible, developer-friendly approach.
+- **Robust runtime translation** with the proven capabilities of react-i18next.
+- **TypeScript support** for type-safe translations and autocompletion.
+- **Scalable architecture** that grows with your application.
+
+This integration streamlines your internationalization workflow, reduces maintenance overhead, and provides a superior developer experience. Start building your multilingual React application today with Intlayer and react-i18next!