@intlayer/docs 7.0.4-canary.0 → 7.0.4

package/blog/en/intlayer_with_react-intl.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-01-02
 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.
+title: How to automate your react-intl JSON translations using Intlayer
+description: Automate your JSON translations with Intlayer and react-intl for enhanced internationalization in React applications.
 keywords:
   - react-intl
   - Intlayer
@@ -21,98 +21,70 @@ history:
     changes: Change to syncJSON plugin
 ---
 
-# React Internationalization (i18n) with **react-intl** and Intlayer
-
-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.
-
-## Table of Contents
-
-<TOC/>
+# How to automate your react-intl JSON translations using Intlayer
 
 ## 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.
-
----
+**Intlayer** is an innovative, open-source internationalization library designed to address the shortcomings of traditional i18n solutions. It offers a modern approach to content management in React applications.
 
-## Intlayer vs. react-intl: Key Differences
+See a concrete comparison with react-intl in our [react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/react-i18next_vs_react-intl_vs_intlayer.md) blog post.
 
-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).
+## Why Combine Intlayer with react-intl?
 
-**Key advantages of using Intlayer with react-intl:**
+While Intlayer provides an excellent standalone i18n solution (see our [React integration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react.md)), you might want to combine it with react-intl for several reasons:
 
-1. **Component-Level Dictionaries**  
-   Intlayer content declaration files can live alongside your React components, preventing "orphaned" translations if components are moved or removed.
+1. **Existing codebase**: You have an established react-intl implementation and want to gradually migrate to Intlayer's improved developer experience.
+2. **Legacy requirements**: Your project requires compatibility with existing react-intl plugins or workflows.
+3. **Team familiarity**: Your team is comfortable with react-intl but wants better content management.
 
-2. **Centralized Translations**  
-   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.
+**For that, Intlayer can be implemented as an adapter for react-intl to help automating your JSON translations in CLI or CI/CD pipelines, testing your translations, and more.**
 
-3. **Automatic Build and Regeneration**  
-   Whenever you add or update translations, Intlayer regenerates message JSON files automatically.
+This guide shows you how to leverage Intlayer's superior content declaration system while maintaining compatibility with react-intl.
 
-4. **Type Safety**  
-   TypeScript integration ensures that missing or incorrect translation keys are caught during development.
+## Table of Contents
 
----
+<TOC/>
 
-## Step-by-Step Guide to Set Up Intlayer in a React Application with react-intl
+## Step-by-Step Guide to Set Up Intlayer with react-intl
 
 ### Step 1: Install Dependencies
 
-Install the necessary packages using your preferred package manager:
+Install the necessary packages:
 
 ```bash packageManager="npm"
-npm install intlayer react-intl @intlayer/sync-json-plugin
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer react-intl @intlayer/sync-json-plugin
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
 ```bash packageManager="yarn"
-yarn add intlayer react-intl @intlayer/sync-json-plugin
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-#### Why These Packages?
+**Package descriptions:**
 
-- **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.
-- **@intlayer/sync-json-plugin**: Plugin to automatically sync Intlayer dictionaries to react-intl compatible JSON files.
+- **intlayer**: Core library for internationalization management, content declaration, and building
+- **@intlayer/sync-json-plugin**: Plugin to export Intlayer content declarations to react-intl compatible JSON format
 
-> If you don't already have React installed, you'll also need `react` and `react-dom`.
+### Step 2: Implement the Intlayer plugin to wrap the JSON
 
-### Step 2: Configure Your Project
+Create an Intlayer configuration file to define your supported locales:
 
-Create a configuration file to define the languages and output settings for your application:
+**If you want to also export JSON dictionaries for react-intl**, add the `syncJSON` plugin:
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 import { syncJSON } from "@intlayer/sync-json-plugin";
 
 const config: IntlayerConfig = {
   internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Add your other locales here
-    ],
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
   plugins: [
     syncJSON({
-      // Define the output directory for react-intl message files
       source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
     }),
   ],
@@ -121,978 +93,30 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-```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 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;
-```
-
-```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).
-
-### 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"
-  }
-}
-```
-
-> The `intlayer build` command scans your content declaration files, compiles them, and generates the JSON message files that react-intl will consume.
-
-### 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 namespace in your react-intl JSON files
-  key: "my-component",
-
-  content: {
-    // Each call to t() declares a translatable field
-    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",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```javascript fileName="src/components/MyComponent/index.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-
-  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",
-    }),
-  },
-};
-
-export default content;
-```
-
-```javascript fileName="src/components/MyComponent/index.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-
-  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
-```
-
-```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
-.
-└── intl
-    └── messages
-        ├── en
-        │   └── my-component.json
-        ├── fr
-        │   └── my-component.json
-        └── es
-            └── my-component.json
-```
-
-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="intl/messages/en/my-component.json"
-{
-  "helloWorld": "Hello World",
-  "description": "This is a description",
-  "welcomeMessage": "Welcome to our application"
-}
-```
-
-### Step 6: Initialize react-intl in Your React App
-
-#### 6.1. Load the Generated Messages
-
-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`.
-
-Here's an example using **Vite's** `import.meta.glob`:
-
-```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";
-
-// 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>
-);
-```
-
-```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,
-});
-
-// Structure messages by locale
-const messagesRecord = {};
-
-Object.entries(messages).forEach(([path, module]) => {
-  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);
-  }
-});
-
-// Detect user locale
-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>
-);
-```
-
-```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:
->
-> - 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";
-
-interface LocaleContextType {
-  locale: string;
-  setLocale: (locale: string) => void;
-  availableLocales: string[];
-}
-
-const LocaleContext = createContext<LocaleContextType | undefined>(undefined);
-
-// 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);
-  }
-});
-
-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);
-    }
-  };
-
-  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 fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
-import React from "react";
-import { FormattedMessage } from "react-intl";
-
-const MyComponent: React.FC = () => {
-  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;
-```
-
-```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;
-```
-
-```jsx fileName="src/components/MyComponent/index.csx" codeFormat="commonjs"
-const React = require("react");
-const { FormattedMessage } = require("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>
-  );
-};
-
-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>
-  );
-};
-
-export default MyComponent;
-```
-
-```jsx fileName="src/components/MyComponent/MyComponent.mjx" codeFormat="esm"
-import React from "react";
-import { useIntl } from "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>
-  );
-};
-
-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");
+The `syncJSON` plugin will automatically wrap the JSON. It will read and write the JSON files without changing the content architecture.
 
-const localeNames = {
-  en: "English",
-  fr: "Français",
-  es: "Español",
-};
+If you want to make coexist that JSON with intlayer content declaration files (`.content` files), Intlayer will proceed this way:
 
-const LocaleSwitcher = () => {
-  const { locale, setLocale, availableLocales } = useLocale();
+    1. load both JSON and content declaration files and transform them into a intlayer dictionary.
+    2. if there is conflicts between the JSON and the content declaration files, Intlayer will process to the merge of that all dictionaries. Depending of the priority of the plugins, and the one of the content declaration file (all are configurable).
 
-  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
-        )
-      )
-    )
-  );
-};
+If changes are made using the CLI to translate the JSON, or using the CMS, Intlayer will update the JSON file with the new translations.
 
-module.exports = LocaleSwitcher;
-```
-
-Then use the `LocaleSwitcher` component in your app:
+To see more details about the `syncJSON` plugin, please refer to the [syncJSON plugin documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/plugins/sync-json.md).
 
-```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;
-```
+## Git Configuration
 
-#### Date and Number Formatting
+It's recommended to ignore auto-generated Intlayer files:
 
-```tsx fileName="src/components/FormattedData.tsx" codeFormat="typescript"
-import React from "react";
-import { FormattedDate, FormattedNumber, FormattedTime } from "react-intl";
-
-const FormattedData: React.FC = () => {
-  const today = new Date();
-  const price = 1234.56;
-
-  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;
-```
-
-### (Optional) Step 10: Handle Missing Translations
-
-By default, react-intl will render the message ID if a translation is missing. You can customize this behavior:
-
-```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";
-
-// 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",
-    ".intlayer/**/*.ts", // Include Intlayer generated types
-  ],
-}
-```
-
-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)
-
-![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
-
-Ensure your TypeScript configuration includes the autogenerated types.
-
-```json5 fileName="tsconfig.json"
-{
-  // ... Your existing TypeScript configurations
-  "include": [
-    // ... Your existing TypeScript configurations
-    ".intlayer/**/*.ts", // Include the auto-generated types
-  ],
-}
+```plaintext fileName=".gitignore"
+# Ignore files generated by Intlayer
+.intlayer
 ```
 
-### Git Configuration
-
-It's recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+These files can be regenerated during your build process and don't need to be committed to version control.
 
-Add the following to your `.gitignore` file:
+### VS Code Extension
 
-```plaintext fileName=".gitignore"
-# Ignore the files generated by Intlayer
-.intlayer
-
-# Optionally ignore generated message files if they're rebuilt in CI/CD
-intl
-```
+For improved developer experience, install the official **Intlayer VS Code Extension**:
 
-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.
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)