---
createdAt: 2025-01-02
updatedAt: 2025-10-29
title: 如何使用 Intlayer 自动化您的 react-intl JSON 翻译
description: 使用 Intlayer 和 react-intl 自动化您的 JSON 翻译，提升 React 应用的国际化体验。
keywords:
- react-intl
- Intlayer
- 国际化
- 博客
- i18n
- JavaScript
- React
- FormatJS
slugs:
- blog
- intlayer-with-react-intl
history:
- version: 7.0.6
date: 2025-11-01
changes: 添加 loadJSON 插件
- version: 7.0.0
date: 2025-10-29
changes: 更改为 syncJSON 插件
---
# 如何使用 Intlayer 自动化您的 react-intl JSON 翻译
## 目录
<TOC/>
## 什么是 Intlayer？
**Intlayer** 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 React 应用提供了一种现代化的内容管理方法。
请参阅我们博客文章中的具体对比：[react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/react-i18next_vs_react-intl_vs_intlayer.md)。
## 为什么要将 Intlayer 与 react-intl 结合使用？
虽然 Intlayer 提供了一个出色的独立 i18n 解决方案（请参阅我们的[React 集成指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md)），但您可能出于以下几个原因希望将其与 react-intl 结合使用：
1. **现有代码库**：您已经有一个成熟的 react-intl 实现，并希望逐步迁移到 Intlayer 以获得更好的开发者体验。
2. **遗留需求**：您的项目需要兼容现有的 react-intl 插件或工作流程。
3. **团队熟悉度**：您的团队熟悉 react-intl，但希望获得更好的内容管理。
4. **使用 Intlayer 功能**：您想使用 Intlayer 的内容声明、翻译自动化、翻译测试等功能。
**为此，Intlayer 可以作为 react-intl 的适配器实现，帮助您在 CLI 或 CI/CD 流水线中自动化 JSON 翻译、测试翻译等。**
本指南将向您展示如何利用 Intlayer 优越的内容声明系统，同时保持与 react-intl 的兼容性。
## 使用 react-intl 设置 Intlayer 的分步指南
### 第一步：安装依赖
安装所需的包：
```bash packageManager="npm"
npm install intlayer @intlayer/sync-json-plugin
```
```bash packageManager="pnpm"
pnpm add intlayer @intlayer/sync-json-plugin
```
```bash packageManager="yarn"
yarn add intlayer @intlayer/sync-json-plugin
```
```bash packageManager="bun"
bun add intlayer @intlayer/sync-json-plugin
```
**包说明：**
- **intlayer**：用于国际化管理、内容声明和构建的核心库
/// **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为兼容 react-intl 的 JSON 格式的插件
### 第 2 步：实现 Intlayer 插件以包装 JSON
创建一个 Intlayer 配置文件以定义您支持的语言环境：
**如果您还想导出适用于 react-intl 的 JSON 字典**，请添加 `syncJSON` 插件：
```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],
defaultLocale: Locales.ENGLISH,
},
plugins: [
syncJSON({
source: ({ key, locale }) => `./intl/messages/${locale}/${key}.json`,
}),
],
};
export default config;
```
`syncJSON` 插件会自动包装 JSON。它会读取和写入 JSON 文件，而不会改变内容结构。
如果你希望让 JSON 与 intlayer 内容声明文件（`.content` 文件）共存，Intlayer 会按以下方式处理：
1. 加载 JSON 和内容声明文件，并将它们转换为 intlayer 字典。
2. 如果 JSON 和内容声明文件之间存在冲突，Intlayer 会合并所有字典。具体合并方式取决于插件的优先级以及内容声明文件的优先级（所有优先级均可配置）。
如果通过 CLI 翻译 JSON 或使用 CMS 进行更改，Intlayer 会使用新的翻译更新 JSON 文件。
要查看更多关于 `syncJSON` 插件的详细信息，请参阅 [syncJSON 插件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md)。
### （可选）步骤 3：实现按组件的 JSON 翻译
默认情况下，Intlayer 会加载、合并并同步 JSON 和内容声明文件。更多详情请参阅 [内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。但如果你愿意，也可以使用 Intlayer 插件，在代码库中的任意位置实现按组件管理本地化的 JSON。
为此，你可以使用 `loadJSON` 插件。
```ts fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";
import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
const config: IntlayerConfig = {
internationalization: {
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
defaultLocale: Locales.ENGLISH,
},
// 保持您当前的 JSON 文件与 Intlayer 字典同步
plugins: [
/**
* 将加载 src 目录中所有匹配模式 {key}.i18n.json 的 JSON 文件
*/
loadJSON({
source: ({ key }) => `./src/**/${key}.i18n.json`,
locale: Locales.ENGLISH,
priority: 1, // 确保这些 JSON 文件优先于 `./locales/en/${key}.json` 中的文件
}),
/**
* 将加载并将输出和翻译写回 locales 目录中的 JSON 文件
*/
syncJSON({
source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
priority: 0,
}),
],
};
export default config;
```
这将加载 `src` 目录中所有匹配 `{key}.i18n.json` 模式的 JSON 文件，并将它们作为 Intlayer 字典加载。
## Git 配置
建议忽略自动生成的 Intlayer 文件：
```plaintext fileName=".gitignore"
# 忽略 Intlayer 生成的文件
.intlayer
```
这些文件可以在构建过程中重新生成，无需提交到版本控制。
### VS Code 扩展
为了提升开发者体验，请安装官方的 **Intlayer VS Code 扩展**：
[从 VS Code 市场安装](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)