如何使用 Intlayer 自动化您的 next-intl JSON 翻译

www.youtube.com

Open embedded page in fullscreen

目录

什么是 Intlayer？

Intlayer 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 Next.js 应用提供了一种现代化的内容管理方法。

请参阅我们博客文章中的具体比较：next-i18next vs. next-intl vs. Intlayer。

为什么要将 Intlayer 与 next-intl 结合使用？

虽然 Intlayer 提供了一个出色的独立 i18n 解决方案（请参阅我们的Next.js 集成指南），但您可能出于以下几个原因想将其与 next-intl 结合使用：

1. 现有代码库：您已经有一个成熟的 next-intl 实现，并希望逐步迁移到 Intlayer 以获得更好的开发者体验。
2. 遗留需求：您的项目需要兼容现有的 next-intl 插件或工作流程。
3. 团队熟悉度：您的团队对 next-intl 感到熟悉，但希望获得更好的内容管理。

为此，Intlayer 可以作为 next-intl 的适配器来实现，帮助您在 CLI 或 CI/CD 流水线中自动化 JSON 翻译、测试翻译等功能。

本指南将向您展示如何利用 Intlayer 优越的内容声明系统，同时保持与 next-intl 的兼容性。

目录

使用 next-intl 设置 Intlayer 的分步指南

1. 1

   安装依赖

   安装必要的包：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer init --interactive
   

   --interactive 标志是可选的。如果你是 AI agent，请使用 intlayer-cli init。

   此命令将检测你的环境并安装所需的包。例如：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npm install intlayer @intlayer/sync-json-plugin --save-dev
   

   包描述：

   • intlayer：国际化管理、内容声明和构建的核心库
   • @intlayer/sync-json-plugin：将 Intlayer 内容声明导出为 next-intl 兼容 JSON 格式的插件
2. 2

   实现 Intlayer 插件以包装 JSON

   创建一个 Intlayer 配置文件来定义你支持的语言：

   如果你还想为 next-intl 导出 JSON 字典，添加 syncJSON 插件：

   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({
         format: "icu",
         source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
       }),
     ],
   };
   
   export default config;
   

   syncJSON 插件将自动包装 JSON。它将读取和写入 JSON 文件，而不改变内容架构。

   如果你想让 JSON 与 intlayer 内容声明文件（.content 文件）并存，Intlayer 将按以下方式处理：

   1. 加载 JSON 和内容声明文件，并将其转换为 intlayer 字典。
   2. 如果 JSON 和内容声明文件之间存在冲突，Intlayer 将合并所有字典。这取决于插件的优先级和内容声明文件的优先级（都是可配置的）。

   如果使用 CLI 或 CMS 更改了 JSON 的翻译，Intlayer 将使用新翻译更新 JSON 文件。

   有关 syncJSON 插件的更多详细信息，请参阅 syncJSON 插件文档。

3. 3

   设置 AI 提供商

   Intlayer 为你的 i18next 工作流解锁了一系列高级自动化和开发者友好的功能。

   • 自动检测和填充缺失的翻译：Intlayer 扫描你的 JSON 字典，查找未翻译或缺失的键，仅翻译那些，所以你的 JSON 的 99% 保持不变。
   • 大 JSON 文件的分块翻译：当你的翻译文件非常大时，Intlayer 自动将处理分成可管理的块，独立地翻译它们以避免 API 限制和内存问题。
   • 命名空间并行化：如果你有数百个命名空间（或文件），Intlayer 并行化翻译任务，有效加快你的 CI/CD 或批量翻译操作。
   • 灵活的 AI 提供商支持：选择你首选的 AI 提供商（例如 OpenAI、Claude、Gemini），只需配置凭证。使用你自己的 API 密钥，并根据需要切换提供商。
   • 弹性的 AI 响应处理：Intlayer 可以处理你的 AI 提供商将文本作为字符串或对象返回的边界情况，甚至在格式不一致时自动重试。
   • CLI 和 CI/CD 就绪：直接在你的测试或管道中运行 Intlayer 的检查和自动填充，使你的本地化流程强大和自动化。
   • 集成在你现有的设置之上：你无需更改你的 i18next 或 Next.js 基础。Intlayer 作为你当前设置的插件，为你提供所有这些好处，同时需要最小的迁移。

   以下是如何设置 AI 提供商的示例：

   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,
     },
     ai: {
       provider: "openai",
       model: "gpt-5-mini",
       apiKey: process.env.OPENAI_API_KEY,
     },
     plugins: [
       syncJSON({
         format: "icu",
         source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
       }),
     ],
   };
   
   export default config;
   

   然后你可以执行以下命令来填充你的翻译：

   bash

   复制内容

   复制代码

   复制代码到剪贴板

   npx intlayer fill
   

   这将用你配置的 AI 提供商填充你的翻译。

   在 Intlayer AI 配置文档 中查看所有可用的 AI 提供商。 在 Intlayer CLI 文档 中查看所有可用的命令。

   ---

Git 配置

建议忽略自动生成的 Intlayer 文件：

# 忽略 Intlayer 生成的文件
.intlayer

这些文件可以在构建过程中重新生成，无需提交到版本控制。

VS Code 扩展

为了提升开发者体验，请安装官方的 Intlayer VS Code 扩展：

从 VS Code 市场安装