@intlayer/docs 7.0.3 → 7.0.4

package/blog/en/intlayer_with_next-intl.md

@@ -1,16 +1,8 @@
 ---
 createdAt: 2025-01-02
 updatedAt: 2025-10-29
-title: Intlayer and next-intl
-description: Integrate Intlayer with next-intl for the internationalization (i18n) of a React app
-keywords:
-  - next-intl
-  - Intlayer
-  - Internationalization
-  - Blog
-  - Next.js
-  - JavaScript
-  - React
+title: How to automate your next-intl JSON translations using Intlayer
+description: Automate your JSON translations with Intlayer and next-intl for enhanced internationalization in Next.js applications.
 slugs:
   - blog
   - intlayer-with-next-intl
@@ -20,100 +12,62 @@ history:
     changes: Change to syncJSON plugin
 ---
 
-# Next.js Internationalization (i18n) with next-intl and Intlayer
+# How to automate your next-intl JSON translations using Intlayer
 
-Both next-intl and Intlayer are open-source internationalization (i18n) frameworks designed for Next.js applications. They are widely used for managing translations, localization, and language switching in software projects.
+## What is Intlayer?
 
-They share three principal notions:
+**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 Next.js applications.
 
-1. **Dictionary**: The method for defining the translatable content of your application.
-   - Named `content declaration file` in Intlayer, which can be a JSON, JS, or TS file exporting the structured data. See [Intlayer documentation](https://intlayer.org/fr/doc/concept/content) for more information.
-   - Named `messages` or `locale messages` in next-intl, usually in JSON files. See [next-intl documentation](https://github.com/amannn/next-intl) for more information.
+See a concrete comparison with next-intl in our [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/next-i18next_vs_next-intl_vs_intlayer.md) blog post.
 
-2. **Utilities**: Tools to build and interpret content declarations in the application, such as `useIntlayer()` or `useLocale()` for Intlayer, and `useTranslations()` for next-intl.
+## Why Combine Intlayer with next-intl?
 
-3. **Plugins and Middlewares**: Features for managing URL redirection, bundling optimization, and more e.g., `intlayerMiddleware` for Intlayer or [`createMiddleware`](https://github.com/amannn/next-intl) for next-intl.
+While Intlayer provides an excellent standalone i18n solution (see our [Next.js integration guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_16.md)), you might want to combine it with next-intl for several reasons:
 
-## Table of Contents
-
-<TOC>
-
-## Intlayer vs. next-intl: Key Differences
-
-For a deeper analysis of how Intlayer compares to other i18n libraries for Next.js (such as next-intl), check out the [next-i18next vs. next-intl vs. Intlayer blog post](https://github.com/aymericzip/intlayer/blob/main/docs/blog/en/i18next_vs_next-intl_vs_intlayer.md).
-
-## How to Generate next-intl Messages with Intlayer
-
-### Why Use Intlayer with next-intl?
+1. **Existing codebase**: You have an established next-intl implementation and want to gradually migrate to Intlayer's improved developer experience.
+2. **Legacy requirements**: Your project requires compatibility with existing next-intl plugins or workflows.
+3. **Team familiarity**: Your team is comfortable with next-intl but wants better content management.
 
-Intlayer content declaration files generally offer a better developer experience. They are more flexible and maintainable due to two main advantages:
+**For that, Intlayer can be implemented as an adapter for next-intl to help automating your JSON translations in CLI or CI/CD pipelines, testing your translations, and more.**
 
-1. **Flexible Placement**: You can place an Intlayer content declaration file anywhere in your application’s file tree. This makes it easy to rename or delete components without leaving unused or dangling message files.
+This guide shows you how to leverage Intlayer's superior content declaration system while maintaining compatibility with next-intl.
 
-   Example file structures:
-
-   ```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
-   ```
+## Table of Contents
 
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Content declaration file
-               └── index.jsx
-   ```
+<TOC/>
 
-2. **Centralized Translations**: Intlayer stores all translations in a single content declaration, ensuring no translation is missing. In TypeScript projects, missing translations are flagged automatically as type errors, providing immediate feedback to developers.
+## Step-by-Step Guide to Set Up Intlayer with next-intl
 
-### Installation
+### Step 1: Install Dependencies
 
-To use Intlayer and next-intl together, install both libraries:
+Install the necessary packages:
 
 ```bash packageManager="npm"
-npm install intlayer next-intl @intlayer/sync-json-plugin
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="yarn"
-yarn add intlayer next-intl @intlayer/sync-json-plugin
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer next-intl @intlayer/sync-json-plugin
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-### Configuring Intlayer to Export next-intl Messages
+**Package descriptions:**
+
+- **intlayer**: Core library for internationalization management, content declaration, and building
+- **@intlayer/sync-json-plugin**: Plugin to export Intlayer content declarations to next-intl compatible JSON format
 
-> **Note:** Exporting messages from Intlayer for next-intl can introduce slight differences in structure. If possible, keep an Intlayer-only or next-intl-only flow to simplify the integration. If you do need to generate next-intl messages from Intlayer, follow the steps below.
+### Step 2: Implement the Intlayer plugin to wrap the JSON
 
-Create or update an `intlayer.config.ts` file (or `.mjs` / `.cjs`) in the root of your project:
+Create an Intlayer configuration file to define your supported locales:
+
+**If you want to also export JSON dictionaries for next-intl**, add the `syncJSON` plugin:
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
 const config: IntlayerConfig = {
   internationalization: {
@@ -122,7 +76,7 @@ const config: IntlayerConfig = {
   },
   plugins: [
     syncJSON({
-      source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
   ],
 };
@@ -130,236 +84,30 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Dictionary
-
-Below are examples of content declaration files in multiple formats. Intlayer will compile these into message files that next-intl can consume.
+The `syncJSON` plugin will automatically wrap the JSON. It will read and write the JSON files without changing the content architecture.
 
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
+If you want to make coexist that JSON with intlayer content declaration files (`.content` files), Intlayer will proceed this way:
 
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
+    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).
 
-export default content;
-```
+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.
 
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+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).
 
-export default content;
-```
+## Git Configuration
 
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
+It's recommended to ignore auto-generated Intlayer files:
 
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
+```plaintext fileName=".gitignore"
+# Ignore files generated by Intlayer
+.intlayer
 ```
 
-```json fileName="**/*.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"
-      }
-    }
-  }
-}
-```
-
-### Build the next-intl Messages
-
-To build the message files for next-intl, run:
+These files can be regenerated during your build process and don't need to be committed to version control.
 
-```bash packageManager="npm"
-npx intlayer build
-```
-
-```bash packageManager="yarn"
-yarn intlayer build
-```
+### VS Code Extension
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
-
-This will generate resources in the `./intl/messages` directory (as configured in `intlayer.config.*`). The expected output:
-
-```bash
-.
-└── intl
-    └── messages
-       └── en
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
-```
-
-Each file includes compiled messages from all Intlayer content declarations. The top-level keys typically match your `content.key` fields.
-
-### Using next-intl in Your Next.js App
-
-> For more details, see the official [next-intl usage docs](https://github.com/amannn/next-intl#readme).
-
-1. **Create a Middleware (optional):**  
-   If you want to manage automatic locale detection or redirection, use next-intl’s [createMiddleware](https://github.com/amannn/next-intl#createMiddleware).
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["en", "fr", "es"],
-     defaultLocale: "en",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **Create a `layout.tsx` or `_app.tsx` to Load Messages:**  
-   If you’re using the App Router (Next.js 13+), create a layout:
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
-
-
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
-
-     return (
-       <html lang={params.locale}>
-         <body>
-           <NextIntlClientProvider locale={params.locale} messages={messages}>
-             {children}
-           </NextIntlClientProvider>
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   If you’re using the Pages Router (Next.js 12 or below), load messages in `_app.tsx`:
-
-   ```typescript fileName="pages/_app.tsx"
-   import type { AppProps } from 'next/app';
-   import { NextIntlProvider } from 'next-intl';
-
-   function MyApp({ Component, pageProps }: AppProps) {
-     return (
-       <NextIntlProvider locale={pageProps.locale} messages={pageProps.messages}>
-         <Component {...pageProps} />
-       </NextIntlProvider>
-     );
-   }
-
-   export default MyApp;
-   ```
-
-3. **Fetch Messages Server-Side (Pages Router example):**
-
-   ```typescript fileName="pages/index.tsx"
-   import { GetServerSideProps } from "next";
-   import HomePage from "../components/HomePage";
-
-   export default HomePage;
-
-   export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
-     const messages = (await import(`../intl/messages/${locale}.json`)).default;
-
-     return {
-       props: {
-         locale,
-         messages,
-       },
-     };
-   };
-   ```
-
-### Using Content in Next.js Components
-
-Once the messages are loaded into next-intl, you can use them in your components via the `useTranslations()` hook:
-
-```typescript fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslations } from 'next-intl';
-
-const MyComponent: FC = () => {
-  const t = useTranslations('my-component');
-  // 'my-component' corresponds to the content key in Intlayer
-
-  return (
-    <div>
-      <h1>{t('helloWorld')}</h1>
-    </div>
-  );
-};
-
-export default MyComponent;
-```
-
-```jsx fileName="src/components/MyComponent/index.jsx" codeFormat="esm"
-import { useTranslations } from "next-intl";
-
-export default function MyComponent() {
-  const t = useTranslations("my-component");
-
-  return (
-    <div>
-      <h1>{t("helloWorld")}</h1>
-    </div>
-  );
-}
-```
+For improved developer experience, install the official **Intlayer VS Code Extension**:
 
-**That’s it!** Whenever you update or add new Intlayer content declaration files, re-run the `intlayer build` command to regenerate your next-intl JSON messages. next-intl will pick up the updated content automatically.
+[Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)