@intlayer/docs 7.0.3 → 7.0.4-canary.0

package/blog/en/intlayer_with_react-intl.md

@@ -1,345 +1,1098 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer and react-intl
-description: Integrate Intlayer with react-intl for a React app
+updatedAt: 2025-10-29
+title: How to Integrate Intlayer with react-intl – Complete i18n Guide
+description: Learn how to integrate Intlayer with react-intl for a React app. Comprehensive guide with code examples for managing translations efficiently.
 keywords:
   - react-intl
   - Intlayer
   - Internationalization
   - Blog
-  - Next.js
+  - i18n
   - JavaScript
   - React
+  - FormatJS
 slugs:
   - blog
   - intlayer-with-react-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Change to syncJSON plugin
 ---
 
 # React Internationalization (i18n) with **react-intl** and Intlayer
 
-This guide shows how to integrate **Intlayer** with **react-intl** to manage translations in a React application. You’ll declare your translatable content with Intlayer and then consume those messages with **react-intl**, a popular library from the [FormatJS](https://formatjs.io/docs/react-intl) ecosystem.
+This comprehensive guide demonstrates how to integrate **Intlayer** with **react-intl** to manage translations in a React application efficiently. You'll learn to declare your translatable content with Intlayer and consume those messages with **react-intl**, a popular library from the [FormatJS](https://formatjs.io/docs/react-intl) ecosystem.
 
-## Overview
+## Table of Contents
 
-- **Intlayer** allows you to store translations in **component-level** content declaration files (JSON, JS, TS, etc.) within your project.
-- **react-intl** provides React components and hooks (like `<FormattedMessage>` and `useIntl()`) to display localized strings.
+<TOC/>
 
-By configuring Intlayer to **export** translations in a **react-intl–compatible** format, you can automatically **generate** and **update** the message files that `<IntlProvider>` (from react-intl) requires.
+## What is Intlayer?
+
+**Intlayer** is an innovative, open-source internationalization (i18n) library designed to simplify multilingual support in modern web applications. Intlayer seamlessly integrates with popular React frameworks, including **react-intl**.
+
+With Intlayer, you can:
+
+- **Easily manage translations** using declarative dictionaries at the component level.
+- **Dynamically localize content** throughout your application.
+- **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.
+- **Maintain component-level translations** to prevent orphaned translations when components are moved or deleted.
+
+> Intlayer also integrates with Next.js, Express, React, and other popular frameworks. Check out our documentation for framework-specific guides.
 
 ---
 
-## Why Use Intlayer with react-intl?
+## Intlayer vs. react-intl: Key Differences
+
+For a deeper analysis of how Intlayer compares to other i18n libraries for React (such as 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).
 
-1. **Per-Component Dictionarys**  
-   Intlayer content declaration files can live alongside your React components, preventing “orphaned” translations if components are moved or removed. For example:
+**Key advantages of using Intlayer with react-intl:**
 
-   ```bash
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts   # Intlayer content declaration
-               └── index.tsx          # React component
-   ```
+1. **Component-Level Dictionaries**  
+   Intlayer content declaration files can live alongside your React components, preventing "orphaned" translations if components are moved or removed.
 
 2. **Centralized Translations**  
-   Each content declaration file collects all translations needed by a component. This is particularly helpful in TypeScript projects: missing translations can be caught at **compile time**.
+   Each content declaration file collects all translations needed by a component. This is particularly helpful in TypeScript projects where missing translations can be caught at compile time.
 
 3. **Automatic Build and Regeneration**  
-   Whenever you add or update translations, Intlayer regenerates message JSON files. You can then pass these into react-intl’s `<IntlProvider>`.
+   Whenever you add or update translations, Intlayer regenerates message JSON files automatically.
+
+4. **Type Safety**  
+   TypeScript integration ensures that missing or incorrect translation keys are caught during development.
 
 ---
 
-## Installation
+## Step-by-Step Guide to Set Up Intlayer in a React Application with react-intl
 
-In a typical React project, install the following:
+### Step 1: Install Dependencies
 
-```bash
-# with npm
-npm install intlayer react-intl
+Install the necessary packages using your preferred package manager:
+
+```bash packageManager="npm"
+npm install intlayer react-intl @intlayer/sync-json-plugin
+```
 
-# with yarn
-yarn add intlayer react-intl
+```bash packageManager="pnpm"
+pnpm add intlayer react-intl @intlayer/sync-json-plugin
+```
 
-# with pnpm
-pnpm add intlayer react-intl
+```bash packageManager="yarn"
+yarn add intlayer react-intl @intlayer/sync-json-plugin
 ```
 
-### Why These Packages?
+#### Why These Packages?
 
 - **intlayer**: Core CLI and library that scans for content declarations, merges them, and builds dictionary outputs.
-- **react-intl**: The main library from FormatJS that provides `<IntlProvider>`, `<FormattedMessage>`, `useIntl()` and other internationalization primitives.
+- **react-intl**: The main library from FormatJS that provides `<IntlProvider>`, `<FormattedMessage>`, `useIntl()`, and other internationalization primitives.
+- **@intlayer/sync-json-plugin**: Plugin to automatically sync Intlayer dictionaries to react-intl compatible JSON files.
 
-> If you don’t already have React itself installed, you’ll need it, too (`react` and `react-dom`).
+> If you don't already have React installed, you'll also need `react` and `react-dom`.
 
-## Configuring Intlayer to Export react-intl Messages
+### Step 2: Configure Your Project
 
-In your project’s root, create **`intlayer.config.ts`** (or `.js`, `.mjs`, `.cjs`) like so:
+Create a configuration file to define the languages and output 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 here
+    ],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    // Tells Intlayer to generate message files for react-intl
-    dictionaryOutput: ["react-intl"],
+  plugins: [
+    syncJSON({
+      // Define the output directory for react-intl message files
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-    // The directory where Intlayer will write your message JSON files
-    reactIntlMessagesDir: "./react-intl/messages",
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Add your other locales here
+    ],
+    defaultLocale: Locales.ENGLISH,
   },
+  plugins: [
+    syncJSON({
+      // Define the output directory for react-intl message files
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
 export default config;
 ```
 
-> **Note**: For other file extensions (`.mjs`, `.cjs`, `.js`), see the [Intlayer docs](https://intlayer.org/en/doc/concept/configuration) for usage details.
+```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 here
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      // Define the output directory for react-intl message files
+      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+    }),
+  ],
+};
+
+module.exports = config;
+```
+
+> Through this configuration file, you can set up locales, output directories, content file patterns, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).
 
-## Creating Your Intlayer Dictionarys
+### Step 3: Integrate Intlayer in Your Build Process
+
+Configure your build scripts to run Intlayer when building your application. Add the Intlayer build command to your `package.json`:
+
+```json fileName="package.json"
+{
+  "scripts": {
+    "build": "intlayer build && vite build",
+    "dev": "intlayer build && vite dev"
+  }
+}
+```
 
-Intlayer scans your codebase (by default, under `./src`) for files matching `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`.  
-Here’s a **TypeScript** example:
+> The `intlayer build` command scans your content declaration files, compiles them, and generates the JSON message files that react-intl will consume.
 
-```typescript title="src/components/MyComponent/index.content.ts"
+### Step 4: Declare Your Content
+
+Create and manage your content declarations to store translations. Intlayer scans your codebase (by default, under `./src`) for files matching `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`.
+
+Here's a **TypeScript** example:
+
+```typescript fileName="src/components/MyComponent/index.content.ts" contentDeclarationFormat="typescript"
 import { t, type Dictionary } from "intlayer";
 
 const content = {
-  // "key" becomes the top-level message key in your react-intl JSON file
+  // "key" becomes the namespace in your react-intl JSON files
   key: "my-component",
 
   content: {
     // Each call to t() declares a translatable field
     helloWorld: t({
       en: "Hello World",
-      es: "Hola Mundo",
       fr: "Bonjour le monde",
+      es: "Hola Mundo",
     }),
     description: t({
       en: "This is a description",
       fr: "Ceci est une description",
       es: "Esta es una descripción",
     }),
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
   },
 } satisfies Dictionary;
 
 export default content;
 ```
 
-If you prefer JSON or different JS flavors (`.cjs`, `.mjs`), the structure is largely the same see [Intlayer docs on content declaration](https://intlayer.org/en/doc/concept/content).
+```javascript fileName="src/components/MyComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
 
----
+/** @type {import('intlayer').Dictionary} */
+const content = {
+  key: "my-component",
 
-## Building the react-intl Messages
+  content: {
+    helloWorld: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "This is a description",
+      fr: "Ceci est une description",
+      es: "Esta es una descripción",
+    }),
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
+  },
+};
 
-To generate the actual message JSON files for **react-intl**, run:
+export default content;
+```
 
-```bash
-# with npm
-npx intlayer dictionaries build
+```javascript fileName="src/components/MyComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
 
-# with yarn
-yarn intlayer build
+/** @type {import('intlayer').Dictionary} */
+const content = {
+  key: "my-component",
 
-# with pnpm
+  content: {
+    helloWorld: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "This is a description",
+      fr: "Ceci est une description",
+      es: "Esta es una descripción",
+    }),
+    welcomeMessage: t({
+      en: "Welcome to our application",
+      fr: "Bienvenue dans notre application",
+      es: "Bienvenido a nuestra aplicación",
+    }),
+  },
+};
+
+module.exports = content;
+```
+
+```json fileName="src/components/MyComponent/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "my-component",
+  "content": {
+    "helloWorld": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "This is a description",
+        "fr": "Ceci est une description",
+        "es": "Esta es una descripción"
+      }
+    },
+    "welcomeMessage": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Welcome to our application",
+        "fr": "Bienvenue dans notre application",
+        "es": "Bienvenido a nuestra aplicación"
+      }
+    }
+  }
+}
+```
+
+> 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 pattern.
+
+> For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
+
+### Step 5: Build the react-intl Messages
+
+To generate the actual message JSON files for **react-intl**, run:
+
+```bash packageManager="npm"
+npx intlayer build
+```
+
+```bash packageManager="pnpm"
 pnpm intlayer build
 ```
 
-This scans all `*.content.*` files, compiles them, and writes the results to the directory specified in your **`intlayer.config.ts`** in this example, `./react-intl/messages`.  
-A typical output might look like:
+```bash packageManager="yarn"
+yarn intlayer build
+```
+
+This command scans all `*.content.*` files, compiles them, and writes the results to the directory specified in your **`intlayer.config.ts`**—in this example, `./intl/messages`.
+
+A typical output structure might look like:
 
 ```bash
 .
-└── react-intl
+└── intl
     └── messages
-        ├── en.json
-        ├── fr.json
-        └── es.json
+        ├── en
+        │   └── my-component.json
+        ├── fr
+        │   └── my-component.json
+        └── es
+            └── my-component.json
 ```
 
-Each file is a JSON object whose **top-level keys** correspond to each **`content.key`** from your declarations. The **sub-keys** (like `helloWorld`) reflect the translations declared within that content item.
-
-For example, the **en.json** might look like:
+Each file is a JSON object with keys corresponding to the `content` properties defined in your Intlayer dictionaries. For example, **en/my-component.json** might look like:
 
-```json fileName="react-intl/messages/en/my-component.json"
+```json fileName="intl/messages/en/my-component.json"
 {
   "helloWorld": "Hello World",
-  "description": "This is a description"
+  "description": "This is a description",
+  "welcomeMessage": "Welcome to our application"
 }
 ```
 
----
-
-## Initializing react-intl in Your React App
+### Step 6: Initialize react-intl in Your React App
 
-### 1. Load the Generated Messages
+#### 6.1. Load the Generated Messages
 
-Where you configure your app’s root component (e.g., `src/main.tsx` or `src/index.tsx`), you’ll need to:
+In your application's entry point (e.g., `src/main.tsx` or `src/index.tsx`), you need to:
 
 1. **Import** the generated message files (either statically or dynamically).
 2. **Provide** them to `<IntlProvider>` from `react-intl`.
 
-A simple approach is to import them **statically**:
+Here's an example using **Vite's** `import.meta.glob`:
 
-```typescript title="src/index.tsx"
+```typescript fileName="src/main.tsx" codeFormat="typescript"
 import React from "react";
 import ReactDOM from "react-dom/client";
 import { IntlProvider } from "react-intl";
 import App from "./App";
 
-// Import the JSON files from the build output.
-// Alternatively, you can import dynamically based on the user's chosen locale.
-import en from "../react-intl/messages/en.json";
-import fr from "../react-intl/messages/fr.json";
-import es from "../react-intl/messages/es.json";
+// Dynamically import all JSON message files
+const messages = import.meta.glob<Record<string, string>>(
+  "../intl/messages/**/*.json",
+  {
+    eager: true,
+  }
+);
 
+// Structure messages by locale
+const messagesRecord: Record<string, Record<string, string>> = {};
 
+Object.entries(messages).forEach(([path, module]) => {
+  // Extract locale and namespace from file path
+  // Example path: "../intl/messages/en/my-component.json"
+  const match = path.match(/messages\/(\w+)\/(.+?)\.json$/);
+  if (match) {
+    const [, locale, namespace] = match;
+    if (!messagesRecord[locale]) {
+      messagesRecord[locale] = {};
+    }
+    // Flatten all messages for the locale
+    Object.assign(messagesRecord[locale], module.default || module);
+  }
+});
+
+// Detect user locale (you can implement more sophisticated logic)
+const userLocale = navigator.language.split("-")[0] || "en";
+const locale = messagesRecord[userLocale] ? userLocale : "en";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
 
-// Dynamically import all JSON files using Vite's import.meta.glob
-const messages = import.meta.glob("../react-intl/messages/**/*.json", {
+```javascript fileName="src/main.mjs" codeFormat="esm"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { IntlProvider } from "react-intl";
+import App from "./App";
+
+// Dynamically import all JSON message files
+const messages = import.meta.glob("../intl/messages/**/*.json", {
   eager: true,
 });
 
-// Collate messages into a structured record
-const messagesRecord: Record<string, Record<string, any>> = {};
+// Structure messages by locale
+const messagesRecord = {};
 
 Object.entries(messages).forEach(([path, module]) => {
-  // Extract locale and namespace from the file path
-  const [, locale, namespace] = path.match(/messages\/(\w+)\/(.+?)\.json$/) ?? [];
-  if (locale && namespace) {
-    messagesRecord[locale] = messagesRecord[locale] ?? {};
-    messagesRecord[locale][namespace] = module.default; // Assign JSON content
+  const match = path.match(/messages\/(\w+)\/(.+?)\.json$/);
+  if (match) {
+    const [, locale, namespace] = match;
+    if (!messagesRecord[locale]) {
+      messagesRecord[locale] = {};
+    }
+    Object.assign(messagesRecord[locale], module.default || module);
   }
 });
 
-// Merge namespaces for each locale
-const mergeMessages = (locale: string) =>
-  Object.values(messagesRecord[locale] ?? {}).reduce(
-    (acc, namespaceMessages) => ({ ...acc, ...namespaceMessages }),
-    {}
-  );
+// Detect user locale
+const userLocale = navigator.language.split("-")[0] || "en";
+const locale = messagesRecord[userLocale] ? userLocale : "en";
 
-// If you have a mechanism to detect the user's language, set it here.
-// For simplicity, let's pick English.
-const locale = "en";
-
-
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+ReactDOM.createRoot(document.getElementById("root")).render(
   <React.StrictMode>
-    <IntlProvider locale={locale} messages={mergeMessages(locale)}>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
       <App />
     </IntlProvider>
   </React.StrictMode>
 );
 ```
 
-> **Tip**: For real projects, you might:
+```javascript fileName="src/main.cjs" codeFormat="commonjs"
+const React = require("react");
+const ReactDOM = require("react-dom/client");
+const { IntlProvider } = require("react-intl");
+const App = require("./App");
+
+// For CommonJS, you'll need to load messages differently
+// This example assumes you have a way to import JSON files
+const enMessages = require("../intl/messages/en/my-component.json");
+const frMessages = require("../intl/messages/fr/my-component.json");
+const esMessages = require("../intl/messages/es/my-component.json");
+
+const messagesRecord = {
+  en: enMessages,
+  fr: frMessages,
+  es: esMessages,
+};
+
+// Detect user locale
+const userLocale = navigator.language.split("-")[0] || "en";
+const locale = messagesRecord[userLocale] ? userLocale : "en";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  React.createElement(
+    React.StrictMode,
+    null,
+    React.createElement(
+      IntlProvider,
+      { locale: locale, messages: messagesRecord[locale] },
+      React.createElement(App)
+    )
+  )
+);
+```
+
+> **Tip**: For production applications, consider:
 >
-> - Dynamically load the JSON messages at runtime.
-> - Use environment-based, browser-based, or user account–based locale detection.
+> - Implementing proper locale detection based on user preferences, browser settings, or user accounts
+> - Loading messages dynamically to reduce initial bundle size
+> - Using a locale switcher component to allow users to change languages
+
+#### 6.2. Create a Locale Context (Optional but Recommended)
+
+For better locale management, create a context that allows components to access and change the current locale:
+
+```typescript fileName="src/context/LocaleContext.tsx" codeFormat="typescript"
+import React, {
+  createContext,
+  useContext,
+  useState,
+  ReactNode,
+  useEffect,
+} from "react";
+import { IntlProvider } from "react-intl";
 
-### 2. Use `<FormattedMessage>` or `useIntl()`
+interface LocaleContextType {
+  locale: string;
+  setLocale: (locale: string) => void;
+  availableLocales: string[];
+}
 
-Once your messages are loaded into `<IntlProvider>`, any child component can use react-intl to access localized strings. There are two main approaches:
+const LocaleContext = createContext<LocaleContextType | undefined>(undefined);
 
-- **`<FormattedMessage>`** component
-- **`useIntl()`** hook
+// Load messages
+const messages = import.meta.glob<Record<string, string>>(
+  "../../intl/messages/**/*.json",
+  {
+    eager: true,
+  }
+);
 
----
+const messagesRecord: Record<string, Record<string, string>> = {};
+
+Object.entries(messages).forEach(([path, module]) => {
+  const match = path.match(/messages\/(\w+)\/(.+?)\.json$/);
+  if (match) {
+    const [, locale] = match;
+    if (!messagesRecord[locale]) {
+      messagesRecord[locale] = {};
+    }
+    Object.assign(messagesRecord[locale], module.default || module);
+  }
+});
 
-## Using Translations in React Components
+const availableLocales = Object.keys(messagesRecord);
+
+export const LocaleProvider: React.FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const [locale, setLocaleState] = useState<string>(() => {
+    // Get locale from localStorage or browser
+    const saved = localStorage.getItem("locale");
+    if (saved && availableLocales.includes(saved)) {
+      return saved;
+    }
+    const browserLocale = navigator.language.split("-")[0];
+    return availableLocales.includes(browserLocale) ? browserLocale : "en";
+  });
+
+  const setLocale = (newLocale: string) => {
+    if (availableLocales.includes(newLocale)) {
+      setLocaleState(newLocale);
+      localStorage.setItem("locale", newLocale);
+    }
+  };
 
-### Approach A: `<FormattedMessage>`
+  return (
+    <LocaleContext.Provider value={{ locale, setLocale, availableLocales }}>
+      <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+        {children}
+      </IntlProvider>
+    </LocaleContext.Provider>
+  );
+};
+
+export const useLocale = () => {
+  const context = useContext(LocaleContext);
+  if (!context) {
+    throw new Error("useLocale must be used within LocaleProvider");
+  }
+  return context;
+};
+```
+
+```javascript fileName="src/context/LocaleContext.mjs" codeFormat="esm"
+import React, { createContext, useContext, useState } from "react";
+import { IntlProvider } from "react-intl";
+
+const LocaleContext = createContext(undefined);
+
+// Load messages
+const messages = import.meta.glob("../../intl/messages/**/*.json", {
+  eager: true,
+});
+
+const messagesRecord = {};
+
+Object.entries(messages).forEach(([path, module]) => {
+  const match = path.match(/messages\/(\w+)\/(.+?)\.json$/);
+  if (match) {
+    const [, locale] = match;
+    if (!messagesRecord[locale]) {
+      messagesRecord[locale] = {};
+    }
+    Object.assign(messagesRecord[locale], module.default || module);
+  }
+});
+
+const availableLocales = Object.keys(messagesRecord);
+
+export const LocaleProvider = ({ children }) => {
+  const [locale, setLocaleState] = useState(() => {
+    const saved = localStorage.getItem("locale");
+    if (saved && availableLocales.includes(saved)) {
+      return saved;
+    }
+    const browserLocale = navigator.language.split("-")[0];
+    return availableLocales.includes(browserLocale) ? browserLocale : "en";
+  });
+
+  const setLocale = (newLocale) => {
+    if (availableLocales.includes(newLocale)) {
+      setLocaleState(newLocale);
+      localStorage.setItem("locale", newLocale);
+    }
+  };
+
+  return (
+    <LocaleContext.Provider value={{ locale, setLocale, availableLocales }}>
+      <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+        {children}
+      </IntlProvider>
+    </LocaleContext.Provider>
+  );
+};
+
+export const useLocale = () => {
+  const context = useContext(LocaleContext);
+  if (!context) {
+    throw new Error("useLocale must be used within LocaleProvider");
+  }
+  return context;
+};
+```
+
+Now update your main entry file to use the `LocaleProvider`:
+
+```typescript fileName="src/main.tsx" codeFormat="typescript"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { LocaleProvider } from "./context/LocaleContext";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <LocaleProvider>
+      <App />
+    </LocaleProvider>
+  </React.StrictMode>
+);
+```
+
+### Step 7: Utilize Content in Your Code
+
+Access your translations throughout your application using react-intl's components and hooks.
+
+#### Approach A: Using `<FormattedMessage>`
 
 For quick inline usage:
 
-```tsx title="src/components/MyComponent/index.tsx"
+```tsx fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
 import React from "react";
 import { FormattedMessage } from "react-intl";
 
-export default function MyComponent() {
+const MyComponent: React.FC = () => {
   return (
     <div>
       <h1>
-        {/* “my-component.helloWorld” references the key from en.json, fr.json, etc. */}
         <FormattedMessage id="my-component.helloWorld" />
       </h1>
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+      <p>
+        <FormattedMessage id="my-component.welcomeMessage" />
+      </p>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
 
+```jsx fileName="src/components/MyComponent/index.mjx" codeFormat="esm"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+const MyComponent = () => {
+  return (
+    <div>
+      <h1>
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
       <p>
         <FormattedMessage id="my-component.description" />
       </p>
+      <p>
+        <FormattedMessage id="my-component.welcomeMessage" />
+      </p>
     </div>
   );
-}
+};
+
+export default MyComponent;
 ```
 
-> The **`id`** prop in `<FormattedMessage>` must match the **top-level key** (`my-component`) plus any sub-keys (`helloWorld`).
+```jsx fileName="src/components/MyComponent/index.csx" codeFormat="commonjs"
+const React = require("react");
+const { FormattedMessage } = require("react-intl");
 
-### Approach B: `useIntl()`
+const MyComponent = () => {
+  return (
+    <div>
+      <h1>
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+      <p>
+        <FormattedMessage id="my-component.welcomeMessage" />
+      </p>
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```
+
+> The **`id`** prop in `<FormattedMessage>` must match the flattened key structure: `namespace.key` (e.g., `my-component.helloWorld`).
+
+#### Approach B: Using `useIntl()`
+
+For more dynamic usage and to access translations in JavaScript logic:
+
+```tsx fileName="src/components/MyComponent/MyComponent.tsx" codeFormat="typescript"
+import React from "react";
+import { useIntl } from "react-intl";
+
+const MyComponent: React.FC = () => {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+      <button
+        aria-label={intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      >
+        {intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      </button>
+    </div>
+  );
+};
 
-For more dynamic usage:
+export default MyComponent;
+```
 
-```tsx title="src/components/MyComponent/index.tsx"
+```jsx fileName="src/components/MyComponent/MyComponent.mjx" codeFormat="esm"
 import React from "react";
 import { useIntl } from "react-intl";
 
-export default function MyComponent() {
+const MyComponent = () => {
   const intl = useIntl();
 
   return (
     <div>
       <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
       <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+      <button
+        aria-label={intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      >
+        {intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      </button>
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+```jsx fileName="src/components/MyComponent/MyComponent.csx" codeFormat="commonjs"
+const React = require("react");
+const { useIntl } = require("react-intl");
+
+const MyComponent = () => {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+      <button
+        aria-label={intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      >
+        {intl.formatMessage({ id: "my-component.welcomeMessage" })}
+      </button>
+    </div>
+  );
+};
+
+module.exports = MyComponent;
+```
+
+### (Optional) Step 8: Change the Language of Your Content
+
+To allow users to switch languages, create a locale switcher component:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import React from "react";
+import { useLocale } from "../context/LocaleContext";
+
+const localeNames: Record<string, string> = {
+  en: "English",
+  fr: "Français",
+  es: "Español",
+};
+
+const LocaleSwitcher: React.FC = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  return (
+    <div>
+      <label htmlFor="locale-select">Choose language: </label>
+      <select
+        id="locale-select"
+        value={locale}
+        onChange={(e) => setLocale(e.target.value)}
+      >
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {localeNames[loc] || loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import React from "react";
+import { useLocale } from "../context/LocaleContext";
+
+const localeNames = {
+  en: "English",
+  fr: "Français",
+  es: "Español",
+};
+
+const LocaleSwitcher = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  return (
+    <div>
+      <label htmlFor="locale-select">Choose language: </label>
+      <select
+        id="locale-select"
+        value={locale}
+        onChange={(e) => setLocale(e.target.value)}
+      >
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {localeNames[loc] || loc}
+          </option>
+        ))}
+      </select>
     </div>
   );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const React = require("react");
+const { useLocale } = require("../context/LocaleContext");
+
+const localeNames = {
+  en: "English",
+  fr: "Français",
+  es: "Español",
+};
+
+const LocaleSwitcher = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  return React.createElement(
+    "div",
+    null,
+    React.createElement(
+      "label",
+      { htmlFor: "locale-select" },
+      "Choose language: "
+    ),
+    React.createElement(
+      "select",
+      {
+        id: "locale-select",
+        value: locale,
+        onChange: (e) => setLocale(e.target.value),
+      },
+      availableLocales.map((loc) =>
+        React.createElement(
+          "option",
+          { key: loc, value: loc },
+          localeNames[loc] || loc
+        )
+      )
+    )
+  );
+};
+
+module.exports = LocaleSwitcher;
+```
+
+Then use the `LocaleSwitcher` component in your app:
+
+```tsx fileName="src/App.tsx" codeFormat="typescript"
+import React from "react";
+import MyComponent from "./components/MyComponent";
+import LocaleSwitcher from "./components/LocaleSwitcher";
+
+const App: React.FC = () => {
+  return (
+    <div>
+      <LocaleSwitcher />
+      <MyComponent />
+    </div>
+  );
+};
+
+export default App;
+```
+
+### (Optional) Step 9: Advanced Message Formatting
+
+react-intl supports advanced formatting features like pluralization, date/time formatting, and number formatting. Here are some examples:
+
+#### Pluralization
+
+```typescript fileName="src/components/ItemCount.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  key: "item-count",
+  content: {
+    items: t({
+      en: "{count, plural, =0 {No items} one {One item} other {# items}}",
+      fr: "{count, plural, =0 {Aucun article} one {Un article} other {# articles}}",
+      es: "{count, plural, =0 {Sin artículos} one {Un artículo} other {# artículos}}",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+```tsx fileName="src/components/ItemCount.tsx" codeFormat="typescript"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+interface ItemCountProps {
+  count: number;
 }
+
+const ItemCount: React.FC<ItemCountProps> = ({ count }) => {
+  return (
+    <p>
+      <FormattedMessage id="item-count.items" values={{ count }} />
+    </p>
+  );
+};
+
+export default ItemCount;
 ```
 
-Either approach is valid choose whichever style suits your app.
+#### Date and Number Formatting
 
----
+```tsx fileName="src/components/FormattedData.tsx" codeFormat="typescript"
+import React from "react";
+import { FormattedDate, FormattedNumber, FormattedTime } from "react-intl";
 
-## Updating or Adding New Translations
+const FormattedData: React.FC = () => {
+  const today = new Date();
+  const price = 1234.56;
 
-1. **Add or modify** content in any `*.content.*` file.
-2. Rerun `intlayer build` to regenerate the JSON files under `./react-intl/messages`.
-3. React (and react-intl) will pick up the updates next time you rebuild or reload your application.
+  return (
+    <div>
+      <p>
+        Date: <FormattedDate value={today} />
+      </p>
+      <p>
+        Time: <FormattedTime value={today} />
+      </p>
+      <p>
+        Price: <FormattedNumber value={price} style="currency" currency="USD" />
+      </p>
+    </div>
+  );
+};
 
----
+export default FormattedData;
+```
 
-## TypeScript Integration (Optional)
+### (Optional) Step 10: Handle Missing Translations
 
-If you’re using TypeScript, Intlayer can **generate type definitions** for your translations.
+By default, react-intl will render the message ID if a translation is missing. You can customize this behavior:
 
-- Make sure `tsconfig.json` includes your `types` folder (or whichever output folder Intlayer generates) in the `"include"` array.
+```typescript fileName="src/main.tsx" codeFormat="typescript"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { IntlProvider } from "react-intl";
+import App from "./App";
 
-```json5
+// Custom handler for missing translations
+const onError = (err: any) => {
+  if (err.code === "MISSING_TRANSLATION") {
+    console.warn("Missing translation", err.message);
+    return;
+  }
+  throw err;
+};
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <IntlProvider locale="en" messages={{}} onError={onError}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
+
+### (Optional) Step 11: TypeScript Integration
+
+Intlayer can generate TypeScript type definitions for your translations, providing compile-time type safety.
+
+Ensure your `tsconfig.json` includes the generated types:
+
+```json5 fileName="tsconfig.json"
 {
   "compilerOptions": {
-    // ...
+    // ... your other compiler options
   },
-  "include": ["src", "types"],
+  "include": [
+    "src",
+    ".intlayer/**/*.ts", // Include Intlayer generated types
+  ],
 }
 ```
 
-The generated types can help detect missing translations or invalid keys in your React components at compile time.
+This enables autocompletion and compile-time checks for translation keys in your IDE.
 
----
+### Configure TypeScript
+
+Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
 
-## Git Configuration
+![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
 
-It’s common to **exclude** Intlayer’s internal build artifacts from version control. In your `.gitignore`, add:
+Ensure your TypeScript configuration includes the autogenerated types.
 
-```plaintext
-# Ignore intlayer build artifacts
+```json5 fileName="tsconfig.json"
+{
+  // ... Your existing TypeScript configurations
+  "include": [
+    // ... Your existing TypeScript configurations
+    ".intlayer/**/*.ts", // Include the auto-generated types
+  ],
+}
+```
+
+### Git Configuration
+
+It's recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+
+Add the following to your `.gitignore` file:
+
+```plaintext fileName=".gitignore"
+# Ignore the files generated by Intlayer
 .intlayer
-react-intl
+
+# Optionally ignore generated message files if they're rebuilt in CI/CD
+intl
 ```
 
-Depending on your workflow, you may also want to ignore or commit the final dictionaries in `./react-intl/messages`. If your CI/CD pipeline regenerates them, you can safely ignore them; otherwise, commit them if you need them for production deployments.
+Depending on your workflow, you may want to commit the `./intl/messages` files if they're needed for production deployments. If your CI/CD pipeline regenerates them, you can safely ignore them.