@intlayer/docs 5.5.9 → 5.5.11

package/blog/en-GB/intlayer_with_react-i18next.md

@@ -0,0 +1,346 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer and react-i18next
+description: Compare Intlayer with react-i18next for a React app
+keywords:
+  - react-i18next
+  - i18next
+  - Intlayer
+  - Internationalisation
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-i18next
+---
+
+# React Internationalization (i18n) with react-i18next and Intlayer
+
+## Overview
+
+- **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.
+
+When combined, Intlayer can **export** dictionaries in **i18next-compatible JSON** so that react-i18next can **consume** them at runtime.
+
+## 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
+```
+
+```bash
+# With yarn
+yarn add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+```bash
+# With pnpm
+pnpm add intlayer react-i18next i18next i18next-resources-to-backend
+```
+
+### What Are These Packages?
+
+- **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.
+
+## Configuring Intlayer to Export i18next Dictionaries
+
+Create (or update) your `intlayer.config.ts` in the root of your project:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Add as many locales as you wish
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Tell Intlayer to create i18next-compatible JSON
+    dictionaryOutput: ["i18next"],
+
+    // Choose an output directory for the generated resources
+    // This folder will be created if it doesn't exist yet.
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+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://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/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",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    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://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/doc/concept/content).
+
+> By default, valid content declarations match the file extension pattern:
+
+> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
+
+## Using the Translations in React Components
+
+After you’ve **built** your Intlayer resources and configured react-i18next, you can directly use the `useTranslation` hook from **react-i18next**.  
+For instance:
+
+```tsx title="src/components/MyComponent/MyComponent.tsx"
+import type { FC } from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * 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
+
+**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:
+
+```json5 title="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+> This will let TypeScript infer the shape of your translations for better autocompletion and error detection.
+
+## Git Configuration
+
+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
+```
+
+You typically do **not** commit these resources or `.intlayer` internal build artifacts, as they can be regenerated on each build.

package/blog/en-GB/intlayer_with_react-intl.md

@@ -0,0 +1,325 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer and react-intl
+description: Integrate Intlayer with react-intl for a React app
+keywords:
+  - react-intl
+  - Intlayer
+  - Internationalisation
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-intl
+---
+
+# 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.
+
+## Overview
+
+- **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.
+
+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.
+
+---
+
+## Why Use Intlayer with react-intl?
+
+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:
+
+   ```bash
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts   # Intlayer content declaration
+               └── index.tsx          # React component
+   ```
+
+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**.
+
+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>`.
+
+---
+
+## Installation
+
+In a typical React project, install the following:
+
+```bash
+# with npm
+npm install intlayer react-intl
+
+# with yarn
+yarn add intlayer react-intl
+
+# with pnpm
+pnpm add intlayer react-intl
+```
+
+### 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.
+
+> If you don’t already have React itself installed, you’ll need it, too (`react` and `react-dom`).
+
+## Configuring Intlayer to Export react-intl Messages
+
+In your project’s root, create **`intlayer.config.ts`** (or `.js`, `.mjs`, `.cjs`) like so:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Add as many locales as you wish
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Tells Intlayer to generate message files for react-intl
+    dictionaryOutput: ["react-intl"],
+
+    // The directory where Intlayer will write your message JSON files
+    reactIntlMessagesDir: "./react-intl/messages",
+  },
+};
+
+export default config;
+```
+
+> **Note**: For other file extensions (`.mjs`, `.cjs`, `.js`), see the [Intlayer docs](https://intlayer.org/en-GB/doc/concept/configuration) for usage details.
+
+---
+
+## Creating Your Intlayer Dictionarys
+
+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 title="src/components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // "key" becomes the top-level message key in your react-intl JSON file
+  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",
+    }),
+  },
+} 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-GB/doc/concept/content).
+
+---
+
+## Building the react-intl Messages
+
+To generate the actual message JSON files for **react-intl**, run:
+
+```bash
+# with npm
+npx intlayer dictionaries build
+
+# with yarn
+yarn intlayer build
+
+# with 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
+.
+└── react-intl
+    └── messages
+        ├── en-GB.json
+        ├── fr.json
+        └── es.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-GB.json** might look like:
+
+```json fileName="react-intl/messages/en/my-component.json"
+{
+  "helloWorld": "Hello World",
+  "description": "This is a description"
+}
+```
+
+---
+
+## Initializing react-intl in Your React App
+
+### 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:
+
+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**:
+
+```typescript title="src/index.tsx"
+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-GB.json";
+import fr from "../react-intl/messages/fr.json";
+import es from "../react-intl/messages/es.json";
+
+// If you have a mechanism to detect the user's language, set it here.
+// For simplicity, let's pick English.
+const locale = "en-GB";
+
+// Collate messages in an object (or pick them dynamically)
+const messagesRecord: Record<string, Record<string, any>> = {
+  en: en,
+  fr: fr,
+  es: es,
+};
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
+
+> **Tip**: For real projects, you might:
+>
+> - Dynamically load the JSON messages at runtime.
+> - Use environment-based, browser-based, or user account–based locale detection.
+
+### 2. Use `<FormattedMessage>` or `useIntl()`
+
+Once your messages are loaded into `<IntlProvider>`, any child component can use react-intl to access localized strings. There are two main approaches:
+
+- **`<FormattedMessage>`** component
+- **`useIntl()`** hook
+
+---
+
+## Using Translations in React Components
+
+### Approach A: `<FormattedMessage>`
+
+For quick inline usage:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+export default function MyComponent() {
+  return (
+    <div>
+      <h1>
+        {/* “my-component.helloWorld” references the key from en-GB.json, fr.json, etc. */}
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
+
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+    </div>
+  );
+}
+```
+
+> The **`id`** prop in `<FormattedMessage>` must match the **top-level key** (`my-component`) plus any sub-keys (`helloWorld`).
+
+### Approach B: `useIntl()`
+
+For more dynamic usage:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { useIntl } from "react-intl";
+
+export default function MyComponent() {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+    </div>
+  );
+}
+```
+
+Either approach is valid , choose whichever style suits your app.
+
+---
+
+## Updating or Adding New Translations
+
+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.
+
+---
+
+## TypeScript Integration (Optional)
+
+If you’re using TypeScript, Intlayer can **generate type definitions** for your translations.
+
+- Make sure `tsconfig.json` includes your `types` folder (or whichever output folder Intlayer generates) in the `"include"` array.
+
+```json5
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+The generated types can help detect missing translations or invalid keys in your React components at compile time.
+
+---
+
+## Git Configuration
+
+It’s common to **exclude** Intlayer’s internal build artifacts from version control. In your `.gitignore`, add:
+
+```plaintext
+# Ignore intlayer build artifacts
+.intlayer
+react-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.