@intlayer/docs 7.0.3 → 7.0.4

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 automate your react-i18next JSON translations using Intlayer
+description: Automate your JSON translations with Intlayer and react-i18next for enhanced internationalization in React applications.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - Internationalization
+  - i18n
   - Blog
-  - Next.js
-  - JavaScript
   - React
+  - JavaScript
+  - TypeScript
+  - Content Management
 slugs:
   - blog
   - intlayer-with-react-i18next
@@ -21,110 +23,71 @@ history:
     changes: Change to syncJSON plugin
 ---
 
-# React Internationalization (i18n) with react-i18next and Intlayer
+# How to automate your react-i18next JSON translations using Intlayer
+
+## What is Intlayer?
+
+**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.
 
-## Overview
+See a concrete comparison with react-i18next 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.
 
-- **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.
+## Why Combine Intlayer with react-i18next?
 
-When combined, Intlayer can **export** dictionaries in **i18next-compatible JSON** so that react-i18next can **consume** them at runtime.
+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-i18next for several reasons:
+
+1. **Existing codebase**: You have an established react-i18next implementation and want to gradually migrate to Intlayer's improved developer experience.
+2. **Legacy requirements**: Your project requires compatibility with existing react-i18next plugins or workflows.
+3. **Team familiarity**: Your team is comfortable with react-i18next but wants better content management.
+
+**For that, Intlayer can be implemented as an adapter for react-i18next to help automating your JSON translations in CLI or CI/CD pipelines, testing your translations, and more.**
+
+This guide shows you how to leverage Intlayer's superior content declaration system while maintaining compatibility with react-i18next.
 
 ## Table of Contents
 
-<TOC>
-
-## Why Use Intlayer with react-i18next?
-
-**Intlayer** content declaration files offer a better developer experience because they are:
-
-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.
-
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Content declaration file
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Content declaration file
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Content declaration file
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Content declaration file
-               └── index.jsx
-   ```
-
-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.
-
-## Installation
-
-In a Create React App project, install these dependencies:
-
-```bash
-# With npm
-npm install intlayer react-i18next i18next i18next-resources-to-backend @intlayer/sync-json-plugin
+<TOC/>
+
+## Step-by-Step Guide to Set Up Intlayer with react-i18next
+
+### Step 1: Install Dependencies
+
+Install the necessary packages:
+
+```bash packageManager="npm"
+npm install intlayer @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 @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 @intlayer/sync-json-plugin
 ```
 
-### What Are These Packages?
+**Package descriptions:**
+
+- **intlayer**: Core library for internationalization management, content declaration, and building
+- **@intlayer/sync-json-plugin**: Plugin to export Intlayer content declarations to react-i18next compatible JSON format
 
-- **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.
+### Step 2: Implement the Intlayer plugin to wrap the JSON
 
-## Configuring Intlayer to Export i18next Dictionaries
+Create an Intlayer configuration file to define your supported locales:
 
-Create (or update) your `intlayer.config.ts` in the root of your project:
+**If you want to also export JSON dictionaries for react-i18next**, add the `syncJSON` plugin:
 
-```typescript title="intlayer.config.ts"
+```typescript fileName="intlayer.config.ts"
 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],
     defaultLocale: Locales.ENGLISH,
   },
   plugins: [
     syncJSON({
-      source: ({ key, locale }) => `./i18next/resources/${locale}/${key}.json`,
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
   ],
 };
@@ -132,221 +95,30 @@ 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).
-
-## Building the i18next Resources
-
-Once your content declarations are in place (next section), run the **Intlayer build command**:
-
-```bash
-# With npm
-npx run intlayer build
-```
-
-```bash
-# With yarn
-yarn intlayer build
-```
-
-```bash
-# With pnpm
-pnpm intlayer build
-```
-
-> This will generate your i18next resources inside the `./i18next/resources` directory by default.
-
-A typical output might look like this:
-
-```bash
-.
-└── i18next
-    └── resources
-       ├── en
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
-```
-
-Where each **Intlayer** declaration key is used as an **i18next namespace** (e.g., `my-content.json`).
-
-## 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:
-
-```typescript title="i18n.ts"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  // react-i18next plugin
-  .use(initReactI18next)
-  // dynamically load resources
-  .use(
-    resourcesToBackend((language: string, namespace: string) => {
-      // Adjust the import path to your resources directory
-      return import(`../i18next/resources/${language}/${namespace}.json`);
-    })
-  )
-  // Initialize i18next
-  .init({
-    // Fallback locale
-    fallbackLng: "en",
-
-    // You can add other i18next config options here, see:
-    // https://www.i18next.com/overview/configuration-options
-  });
-
-export default i18next;
-```
-
-```javascript title="i18n.js"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  .use(initReactI18next)
-  .use(
-    resourcesToBackend(
-      (language, namespace) =>
-        import(`../i18next/resources/${language}/${namespace}.json`)
-    )
-  )
-  .init({
-    fallbackLng: "en",
-  });
-
-export default i18next;
-```
-
-Then, in your **root** or **index** file (e.g., `src/index.tsx`), import this `i18n` setup **before** rendering the `App`:
-
-```typescript
-import React from "react";
-import ReactDOM from "react-dom/client";
-// Initialize i18n before anything else
-import "./i18n";
-import App from "./App";
-
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
-
-## Creating and Managing Your Dictionarys
-
-Intlayer extracts translations from “content declaration files” located anywhere under `./src` (by default).  
-Here’s a minimal example in TypeScript:
-
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  // The "key" will be your i18next namespace (e.g., "my-component")
-  key: "my-component",
-  content: {
-    // Each "t" call is a separate translation node
-    heading: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-    description: t({
-      en: "My i18n description text...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-If you prefer JSON, `.cjs`, or `.mjs`, refer to the [Intlayer docs](https://intlayer.org/en/doc/concept/content).
-
-> By default, valid content declarations match the file extension pattern:
+The `syncJSON` plugin will automatically wrap the JSON. It will read and write the JSON files without changing the content architecture.
 
-> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
+If you want to make coexist that JSON with intlayer content declaration files (`.content` files), Intlayer will proceed this way:
 
-## Using the Translations in React Components
+    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).
 
-After you’ve **built** your Intlayer resources and configured react-i18next, you can directly use the `useTranslation` hook from **react-i18next**.  
-For instance:
+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.
 
-```tsx title="src/components/MyComponent/MyComponent.tsx"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
+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).
 
-/**
- * The i18next "namespace" is the Intlayer `key` from "MyComponent.content.ts"
- * so we'll pass "my-component" to useTranslation().
- */
-const MyComponent: FC = () => {
-  const { t } = useTranslation("my-component");
-
-  return (
-    <div>
-      <h1>{t("heading")}</h1>
-      <p>{t("description")}</p>
-    </div>
-  );
-};
-
-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")`.
-
-## Optional: 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, you can:
-
-1. **Install react-intlayer** (if you haven’t):
-   ```bash
-   npm install 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"
-   }
-   ```
-
-   > `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
+## Git Configuration
 
-**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:
+It's recommended to ignore auto-generated Intlayer files:
 
-```json5 title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-  },
-  "include": ["src", "types"],
-}
+```plaintext fileName=".gitignore"
+# Ignore files generated by Intlayer
+.intlayer
 ```
 
-> This will let TypeScript infer the shape of your translations for better autocompletion and error detection.
+These files can be regenerated during your build process and don't need to be committed to version control.
 
-## Git Configuration
+### VS Code Extension
 
-It is recommended to **ignore** auto-generated files and folders from Intlayer. Add this line to your `.gitignore`:
-
-```plaintext
-# Ignore the files generated by Intlayer
-.intlayer
-i18next
-```
+For improved developer experience, install the official **Intlayer VS Code Extension**:
 
-You typically do **not** commit these resources or `.intlayer` internal build artifacts, as they can be regenerated on each build.
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)