@intlayer/docs 7.0.3 → 7.0.4

package/blog/zh/intlayer_with_next-intl.md

@@ -1,392 +1,114 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer和next-intl
-description: 与React应用程序的next-intl集成Intlayer
-keywords:
-  - next-intl
-  - Intlayer
-  - 国际化
-  - 文档
-  - Next.js
-  - JavaScript
-  - React
+updatedAt: 2025-10-29
+title: 如何使用 Intlayer 自动化您的 next-intl JSON 翻译
+description: 使用 Intlayer 和 next-intl 自动化您的 JSON 翻译，提升 Next.js 应用的国际化体验。
 slugs:
   - blog
   - intlayer-with-next-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: 更改为 syncJSON 插件
 ---
 
-# Next.js 国际化 (i18n) 与 next-intl 和 Intlayer
+# 如何使用 Intlayer 自动化您的 next-intl JSON 翻译
 
-next-intl 和 Intlayer 是为 Next.js 应用程序设计的开源国际化 (i18n) 框架。它们广泛用于管理软件项目中的翻译、本地化和语言切换。
+## 什么是 Intlayer？
 
-它们共享三个主要概念：
+**Intlayer** 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 Next.js 应用提供了一种现代化的内容管理方法。
 
-1. **内容声明**: 定义应用程序可翻译内容的方法。
-   - 在 Intlayer 中称为 `content declaration file`，可以是导出结构化数据的 JSON、JS 或 TS 文件。有关更多信息，请参见 [Intlayer 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/concept/content.md)。
-   - 在 next-intl 中称为 `messages` 或 `locale messages`，通常在 JSON 文件中。有关更多信息，请参见 [next-intl 文档](https://github.com/amannn/next-intl/blob/main/docs/zh/introduction.md)。
+请参阅我们博客文章中的具体比较：[next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md)。
 
-2. **工具**: 用于构建和解释应用程序中的内容声明的工具，例如 Intlayer 的 `useIntlayer()` 或 `useLocale()`，以及 next-intl 的 `useTranslations()`。
+## 为什么要将 Intlayer 与 next-intl 结合使用？
 
-3. **插件和中间件**: 用于管理 URL 重定向、打包优化等功能, , 例如，Intlayer 的 `intlayerMiddleware` 或 next-intl 的 [`createMiddleware`](https://github.com/amannn/next-intl/blob/main/docs/zh/api/middleware.md)。
+虽然 Intlayer 提供了一个出色的独立 i18n 解决方案（请参阅我们的[Next.js 集成指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_16.md)），但您可能出于以下几个原因想将其与 next-intl 结合使用：
 
-## Intlayer 与 next-intl: 关键区别
+1. **现有代码库**：您已经有了成熟的 next-intl 实现，并希望逐步迁移到 Intlayer 以获得更好的开发者体验。
+2. **遗留需求**：您的项目需要兼容现有的 next-intl 插件或工作流程。
+3. **团队熟悉度**：您的团队对 next-intl 很熟悉，但希望获得更好的内容管理。
 
-要深入分析 Intlayer 如何与其他 i18n 库（如 next-intl）进行比较，请查看 [next-i18next vs. next-intl vs. Intlayer 博客文章](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/i18next_vs_next-intl_vs_intlayer.md)。
+**为此，Intlayer 可以作为 next-intl 的适配器来实现，帮助您在 CLI 或 CI/CD 流水线中自动化 JSON 翻译，测试翻译内容等。**
 
-## 如何生成 next-intl 消息与 Intlayer
+本指南将向您展示如何利用 Intlayer 优越的内容声明系统，同时保持与 next-intl 的兼容性。
 
-### 为什么使用 Intlayer 与 next-intl？
+## 目录
 
-Intlayer 内容声明文件通常提供更好的开发者体验。由于两个主要优点，它们更加灵活和易于维护：
+<TOC/>
 
-1. **灵活的位置**: 你可以将 Intlayer 内容声明文件放置在应用程序文件树的任何位置。这使得重命名或删除组件变得简单，而不会留下未使用或悬挂的消息文件。
+## 使用 next-intl 设置 Intlayer 的逐步指南
 
-   示例文件结构：
+### 第一步：安装依赖
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # 内容声明文件
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # 内容声明文件
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # 内容声明文件
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # 内容声明文件
-               └── index.jsx
-   ```
-
-2. **集中翻译**: Intlayer 将所有翻译存储在一个内容声明中，确保没有翻译被遗漏。在 TypeScript 项目中，缺失翻译会自动被标记为类型错误，为开发者提供即时反馈。
-
-### 安装
-
-要一起使用 Intlayer 和 next-intl，请安装这两个库：
+安装必要的包：
 
 ```bash packageManager="npm"
-npm install intlayer next-intl
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="yarn"
-yarn add intlayer next-intl
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer next-intl
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-### 配置 Intlayer 导出 next-intl 消息
+**软件包说明：**
 
-> **注意:** 从 Intlayer 导出消息到 next-intl 可能会引入结构上的细微差异。如果可能，保持 Intlayer 或 next-intl 单独的流程以简化集成。如果确实需要从 Intlayer 生成 next-intl 消息，请遵循以下步骤。
+- **intlayer**：国际化管理、内容声明和构建的核心库
+- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为 next-intl 兼容的 JSON 格式的插件
 
-在项目根目录中创建或更新一个 `intlayer.config.ts` 文件（或 `.mjs` / `.cjs`）：
+### 第2步：实现 Intlayer 插件以包装 JSON
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
+创建一个 Intlayer 配置文件以定义支持的语言环境：
 
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"], // 使用 next-intl 输出
-    nextIntlMessagesDir: "./intl/messages", // 保存 next-intl 消息的位置
-  },
-};
-
-export default config;
-```
-
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["react-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
+**如果您还想导出适用于 next-intl 的 JSON 字典**，请添加 `syncJSON` 插件：
 
-export default config;
-```
-
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    dictionaryOutput: ["next-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-module.exports = config;
-```
-
-### 内容声明
-
-以下是多个格式的内容声明文件示例。Intlayer 将把这些编译成 next-intl 可以使用的消息文件。
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```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",
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
-  },
+  ],
 };
 
-export default content;
+export default config;
 ```
 
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
+`syncJSON` 插件会自动包装 JSON。它会读取和写入 JSON 文件，而不会改变内容结构。
 
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-```
+如果你想让 JSON 与 intlayer 内容声明文件（`.content` 文件）共存，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"
-      }
-    }
-  }
-}
-```
-
-### 构建 next-intl 消息
+    1. 加载 JSON 和内容声明文件，并将它们转换为 intlayer 字典。
 
-要构建 next-intl 的消息文件，请运行：
+2. 如果 JSON 文件和内容声明文件之间存在冲突，Intlayer 将合并所有字典。合并的优先级取决于插件的优先级以及内容声明文件的优先级（所有均可配置）。
 
-```bash packageManager="npm"
-npx intlayer dictionaries build
-```
+如果使用 CLI 翻译 JSON 或使用 CMS 进行更改，Intlayer 会使用新的翻译更新 JSON 文件。
 
-```bash packageManager="yarn"
-yarn intlayer build
-```
+## Git 配置
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
+建议忽略自动生成的 Intlayer 文件：
 
-这将在 `./intl/messages` 目录中生成资源（如 `intlayer.config.*` 中配置的）。预期输出：
-
-```bash
-.
-└── intl
-    └── messages
-       └── zh
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
+```plaintext fileName=".gitignore"
+# 忽略 Intlayer 生成的文件
+.intlayer
 ```
 
-每个文件包含来自所有 Intlayer 内容声明的编译消息。顶级键通常与 `content.key` 字段匹配。
-
-### 在你的 Next.js 应用中使用 next-intl
-
-> 欲了解更多详细信息，请参阅官方 [next-intl 使用文档](https://github.com/amannn/next-intl/blob/main/docs/zh/getting-started.md)。
-
-1. **创建中间件 (可选):**  
-   如果你想管理自动语言检测或重定向，请使用 next-intl 的 [createMiddleware](https://github.com/amannn/next-intl/blob/main/docs/zh/api/middleware.md)。
-
-   ```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. **创建一个 `layout.tsx` 或 `_app.tsx` 来加载消息:**  
-   如果你正在使用 App Router（Next.js 13+），请创建一个布局：
-
-   ```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>
-     );
-   }
-   ```
-
-   如果你正在使用 Pages Router（Next.js 12 或更早），请在 `_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. **在服务器端获取消息 (Pages Router 示例):**
-
-   ```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,
-       },
-     };
-   };
-   ```
-
-### 在 Next.js 组件中使用内容
-
-一旦消息被加载到 next-intl 中，你可以通过 `useTranslations()` 钩子在组件中使用它们：
-
-```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' 对应于 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";
+### VS Code 扩展
 
-export default function MyComponent() {
-  const t = useTranslations("my-component");
+为了提升开发者体验，请安装官方的 **Intlayer VS Code 扩展**：
 
-  return (
-    <div>
-      <h1>{t("helloWorld")}</h1>
-    </div>
-  );
-}
-```
+[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-**就这些！** 每当你更新或添加新的 Intlayer 内容声明文件时，重新运行 `intlayer build` 命令以重新生成你的 next-intl JSON 消息。next-intl 将自动获取更新的内容。
+[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)