@intlayer/docs 9.4.2 → 9.4.3

package/blog/zh/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "使用 Intl 针对不同语言环境格式化日期和数字"
+description: 你很可能不需要单独引入格式化库。深入解析 Intl 如何处理各语言环境下的日期、数字、货币和列表，实例缓存的开销，以及只在生产环境爆发的时区 Bug。
+keywords:
+  - 按语言环境格式化日期
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - 语言环境货币格式
+  - 相对时间格式化
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# 使用 Intl 针对不同语言环境格式化日期和数字
+
+翻译文本只是国际化（i18n）肉眼可见的一半。产生大量缺陷工单的另一半往往是格式化：德国用户看到的数字是 `1,234.56` 而不是标准的 `1.234,56`；日本用户把 `08/02/2026` 误以为是 8 月；或者同一个日期在服务端与客户端渲染结果不一致，导致 React 发生注水错误（Hydration mismatch）而白屏。
+
+这些场景统统不需要引入第三方库。现代 JavaScript 运行时已经原生内置了 `Intl` API。
+
+## 目录
+
+<TOC/>
+
+## 第一步：删掉你手写的手工日期辅助函数
+
+几乎每个老项目的代码库里，都藏着在考虑国际化之前写的 `formatDate` 函数。它硬编码了字段顺序、分隔符，甚至把英文月份名写死在代码中。
+
+```ts
+// 应该彻底删掉的代码：
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` 可以完美取而代之，且在所有语言环境下都能正确解析：
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+数字处理也是同样道理。调用 `toFixed(2)` 在任何环境下都会生成 `1234.56`，这在欧洲大部分地区都是不符合书写习惯的。
+
+## `Intl` 涵盖的功能全貌
+
+| API                       | 适用场景                                                 |
+| :------------------------ | :------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | 日期与时间，支持 `dateStyle` / `timeStyle` 预设风格      |
+| `Intl.NumberFormat`       | 小数、货币、百分比、物理单位、紧凑记数法                 |
+| `Intl.RelativeTimeFormat` | "3 天前"、"2 小时后" 等相对时间表达                      |
+| `Intl.ListFormat`         | 语言学列表拼接（如中文的“A、B 和 C”，法文的“a, b et c”） |
+| `Intl.PluralRules`        | 确定数字对应的复数分类规则                               |
+| `Intl.Collator`           | 遵循特定语言规则的正确字符串排序                         |
+
+`Intl.Collator` 是常常被开发者遗漏的工具。对字符串直接调用 `array.sort()` 依据的是 Unicode 码点顺序，这会导致带声调或重音的字符排到 `z` 之后，瑞典语的 `ö` 也会排在错误的位置。只要是给用户看的可视化列表，都应当使用 collator 排序。
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("zh").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## 优先选用预设模式，而非手工拼接选项
+
+`dateStyle` 与 `timeStyle` 允许各语言环境根据其文化规范自动决定展示顺序与分隔符。逐个指定 `year`、`month` 和 `day` 会赋予你多余的控制权，但这往往是有害的，因为不同地区的习惯顺序大相径庭，这样做无异于用开发者的个人猜测去覆盖 CLDR 的权威数据。
+
+```ts
+// 由语言环境决定排版布局：
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// 手工强制指定结构，在其他地区很可能出现格式错误：
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+仅在视觉设计上有极其严苛的固定宽度要求（例如紧凑的数据表格列）时，才考虑显式指定各个字段分量。
+
+## 构造格式化实例的开销不可忽视
+
+这是一个直接影响性能的关键细节。初始化一个 `Intl.NumberFormat` 需要加载庞大的语言环境数据，其耗时远远高于后续调用 `.format()` 的耗时。若在长列表渲染循环中针对每一行数据都新建一次格式化实例，会导致非常明显的性能卡顿。
+
+```ts
+// 每一行都重新创建实例（低效）：
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// 创建一次并重复复用（高效）：
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` 和 `toLocaleString()` 内部暗藏完全相同的性能陷阱：每次调用都在底层构造新的格式化实例。对于单个独立数值无伤大雅，但绝不适用于数组或列表遍历。
+
+应基于语言环境和选项组合对其进行缓存：
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## 只在生产环境现身的时区 Bug
+
+这个陷阱曾经耗费无数开发者一整个下午的时间。服务端通过 SSR 生成了日期字符串，浏览器端接管并进行注水（hydration），此时 React 抛出注水不匹配错误并崩溃，原因是两端生成的日期文字并不一致。
+
+其根源在于：如果没有显式声明时区，`Intl.DateTimeFormat` 会默认抓取宿主操作系统的当前时区。生产环境的容器通常运行在 UTC 时区下，而开发者的本地开发机则处于本地时区（如 UTC+8）。这使得 Bug 在本地开发时毫无踪迹，却在上线后必定爆发。
+
+```ts
+// 服务端（UTC）与客户端浏览器（UTC+8）输出不同，注水崩溃：
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// 显式锁定时区，双端输出绝对一致：
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+三种可行的工程化方案：
+
+- **服务端强锁固定时区**并显式透传。确定性高且稳定，但所有用户看到的都是 UTC 时间。
+- **纯客户端渲染日期**，在服务端直出时展示统一的骨架占位符。能精准对应用户本地时间，但存在轻微视觉闪烁。
+- **采集并记录用户所在时区**，在服务端与客户端同步注入。体验最佳，但需要额外的数据流维护成本。
+
+无论选择哪种方式，只要日期同时由服务端与客户端渲染，就必须显式传入 `timeZone`。未明确指定时区的日期，本质上就是一个包含两个不同输出值的隐形炸弹。
+
+## 货币需要的是货币代码，而不是语言环境
+
+语言环境与货币是两个正交的概念。`fr-FR` 并不代表计价单位一定是欧元：法国用户完全可能正在查阅一份以美元结算的账单。
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+语言环境决定的是千分位分隔符、数字分节以及货币符号的摆放位置。货币本身应来源于业务数据。从语言环境直接臆断货币，属于会直接引发财务核算错误的严重缺陷。
+
+此外，建议关注 `currencyDisplay` 属性。在存在多种使用美元符号（$）的币种共存的场景下，将其设为 `"code"` 可以彻底消除美元、加元与澳元之间的歧义。
+
+## 相对时间比绝对时间更具可读性
+
+对于近期发生的操作，“2 小时前”远比冗长的时间戳直观得多，而 `Intl.RelativeTimeFormat` 原生支持精准的本地化转换。
+
+```ts
+new Intl.RelativeTimeFormat("zh", { numeric: "auto" }).format(-1, "day");
+// "昨天"
+```
+
+指定 `numeric: "auto"` 可以得到“昨天”而不是生硬的“1 天前”。
+
+## Intlayer 提供的增强能力
+
+Intlayer 将上述底层 API 封装成了内置缓存的轻量工具函数，省去了手动维护 Map 缓存的繁琐操作，并且会自动将当前激活的语言环境作为默认值注入，无需在每个调用点重复传递。
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1,234.5"
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 小时前"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 公里"
+compact(1200); // "1.2千"
+list(["苹果", "香蕉", "橙子"]); // "苹果、香蕉和橙子"
+```
+
+`date()` 函数同样支持常用预设（`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`），常规场景无需编写繁琐的配置对象。对于 React 和 Vue，Intlayer 还提供了对应的 hooks 与 composables，自动从上下文解析当前语言。
+
+其底层完全基于标准的 `Intl` 实现，属于优雅的缓存与上下文解析封装。详细的方法签名可查阅 [格式化工具文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)。
+
+## 常见错误
+
+- **调用 `toLocaleDateString()` 时未传语言环境。** 默认采用宿主环境设定，在服务端易受容器环境漂移影响。
+- **在遍历循环中反复构造实例。** 实例初始化的开销远高于格式化本身，务必复用。
+- **同构渲染日期遗漏 `timeZone` 声明。** 导致本地无法复现的注水匹配失败。
+- **通过语言环境推测货币。** `fr-FR` 不等同于必须展示为欧元。
+- **对用户可见文字直接使用普通 `sort()`。** 请始终采用 `Intl.Collator`。
+- **在源码中硬编码月份或星期。** CLDR 已完整内置各语言的权威名称。
+- **相对时间保留 `numeric: "always"`。** 会导致本该说“昨天”的地方机械地输出“1 天前”。
+
+## 深入阅读
+
+- [格式化工具与语言环境实用函数：`number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md)
+- [配置参考指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [跨框架性能基准报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)
+- [react-intl 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/react-intl.md)
+- [ICU 消息格式：复数、分支选择与数字骨架](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/icu_message_format.md)
+- [国际化测试策略：覆盖格式化与复数分支](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/i18n_testing_strategies.md)
+- [国际化真正涵盖的核心范畴](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/what_is_internationalization.md)

package/blog/zh/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "如何在用户发现之前检测缺失的翻译"
+description: 缺失的翻译通常会静默失败。为什么回退机制会掩盖问题，真正有效的四层检测机制，以及如何在遇到未翻译键时阻断构建。
+keywords:
+  - 查找缺失翻译
+  - 缺失翻译键
+  - i18n 审计
+  - 未翻译字符串
+  - 翻译覆盖率
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# 如何在用户发现之前检测缺失的翻译
+
+缺失的翻译几乎从不抛出异常。根据你的配置，它要么向日本用户展示英文文本，要么在生产环境页面上直接打印 `checkout.summary.total`。这两种情况都能顺利发布，都能通过代码审查，并且最终都是由客户而不是你发现的。
+
+## 目录
+
+<TOC/>
+
+## 无论你使用什么库，这套方案都适用
+
+本文介绍的内容不局限于某一个特定技术栈。下面介绍的检测层在 i18next、react-i18next、next-intl、react-intl、vue-i18n、next-translate 或 Lingui 中均可同样工作，因为它们都以相同的方式解析键，并以相同的方式产生缺陷。
+
+工具链同样具备很强的可移植性。如果你的翻译消息当前保存在 JSON 字典目录中，[Sync JSON 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 可以直接将 Intlayer 接入这些文件，从而让你无需移动内容或修改导入路径即可使用审计、填充和测试命令：
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // 或针对 next-intl / react-intl 的 "icu"
+    }),
+  ],
+};
+
+export default config;
+```
+
+如果你希望同时保留运行时的 API，[兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 可以在打包工具层对 `useTranslation`、`$t` 等进行别名替换。无论采用哪种方式，都可以将下文的命令视作这一思想的具体实践，而非强制要求。
+
+## 为什么缺失的翻译往往隐蔽无形
+
+所有 i18n 库都通过同一条链条解析键：查找当前激活的语言环境，回退到默认语言，如果依然找不到，就直接返回键名字符串。最后这一步正是问题的根源。系统中没有抛出错误，生产环境中没有警告，也没有任何测试失败，因为整个流水线中没有任何环节将缺失的键视为异常状态。
+
+回退机制让情况变得更糟而不是更好。一个静默以英文渲染的页面，对于讲英语的开发者以及所有自动化检查来说都显得毫无破绽。这个 Bug 只有那些无法阅读最终结果的用户才能看到。
+
+因此，核心问题不在于“如何在运行时处理缺失的翻译”。而在于“如何让包含缺失翻译的代码根本无法被合并”。
+
+## 捕捉缺失翻译的四个层级
+
+每个层级都能捕获其他层级无法发现的漏洞。你需要结合多个层级来构建防护。
+
+| 层级            | 能够捕获                           | 会遗漏                             |
+| :-------------- | :--------------------------------- | :--------------------------------- |
+| 类型系统        | 根本不存在的键名                   | 键名存在但 `ja` 语言环境下的值为空 |
+| 语法检查 (Lint) | 从未被提取供翻译的硬编码字符串     | 字典中遗漏的键                     |
+| 覆盖率审计      | 每个已声明键在各语言环境中的覆盖率 | 从未被标记为可翻译的原始文本       |
+| 渲染测试        | 能够解析但渲染结果不正确的键       | 未被测试用例覆盖的界面内容         |
+
+绝大多数团队存在的盲区在第三行：他们知道自己的键名是有效的，但没有任何工具检查十八种语言是否真的都已填入内容。
+
+## 层级 1：将键转化为类型，而非普通字符串
+
+`t("checkout.summry.total")` 是一个可以正常通过编译的拼写错误。如果你的键是纯文本字符串，每次重命名都是生产风险，每次删除都会留下孤立的废弃键。
+
+类型化的键将这种隐患转化为构建阶段的错误。`react-i18next` 通过声明合并（declaration merging）提供支持，`next-intl` 从消息结构推断类型，Lingui 从源码文本派生 ID，而 Intlayer 则直接从声明文件中生成严谨的类型。它们都行之有效；不同之处仅在于需要编写多少配置代码。
+
+这一层是必要的，但并非万全之策。类型仅能约束默认字典的骨架，它无法证明韩语是否真的为该键配置了对应的翻译。
+
+## 层级 2：通过 Lint 捕获从未变成键的原始字符串
+
+最难找到的翻译往往是从未被外部化的文案。组件内部硬编码的文本对任何基于字典目录的审计工具都是不可见的，因为在工具看来，该字符串根本不存在。
+
+Intlayer 的 ESLint 插件通过 `no-raw-text` 规则覆盖了这一问题，并搭配 `no-unused-content` 检查反向问题：已经声明但没有任何代码引用的死内容。
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` 可以防止字典目录无限膨胀。无用键虽然不会破坏代码执行，但会增加翻译供应商的账单。完整规则清单请见 [ESLint 插件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)。
+
+## 层级 3：审计各语言环境的覆盖率
+
+这是直接回答核心问题的一层。Intlayer 将其作为一条 CLI 命令提供：
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+它会读取配置的语言环境及声明的字典，详细报告哪些文件的哪些键缺少了哪些语言环境。
+
+在将其接入自动化流程前需注意：**该 CLI 会输出检查报告，但退出状态码始终为 0。** 如果直接将其放入流水线中寄希望于它阻断构建，你只会得到一个正常通过的构建以及一段没人会看的大段文本输出。要真正进行拦截，请使用下文介绍的编程式 API。
+
+## 层级 4：在测试套件中通过断言进行验证
+
+`listMissingTranslations()` 会以结构化数据的形式返回相同的审计结果，非常适合用作构建拦截门禁。
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("没有缺失必需的语言环境", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+接口会返回三个关键字段：
+
+- `missingTranslations`：按键名细分，指明缺少哪些语言环境及所在的文件。这是测试失败时应当打印的内容。
+- `missingLocales`：跨所有键汇总后缺失的所有语言集合。
+- `missingRequiredLocales`：仅限制在配置中的 `requiredLocales` 范围内（若未配置则等同于全部语言）。
+
+## `requiredLocales` 是让门禁可持续运行的关键
+
+支持十八种语言并不意味着上线前所有十八种语言都必须 100% 完成。大多数团队都会划分核心阻塞语言与渐进补充语言。
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+如果没有设置 `requiredLocales`，所有声明的语言都会成为强制要求，只要最后一种语言尚未完成，构建就会一直处于红灯状态。这通常会导致团队最终彻底禁用该检查。
+
+## 发现已经流入生产环境的缺失
+
+上述层级能够防止新问题的产生。对于已经发布的线上应用，有两种非常有效的排查策略。
+
+**伪本地化（Pseudolocalization）。** 启用一个将每个字符都进行特殊转换的伪语言环境，例如将 `Checkout` 变成 `[!!! Ĉĥéçķöũţ !!!]`。页面渲染后，任何依然显示为正常英语的内容都毫无疑问是硬编码文案。因为它测试的是最终渲染结果，能在十分钟内发现字典审计永远无法看到的问题。
+
+**爬取自己的网站。** 如果你提供按语言划分的 URL，可以抓取每个语言环境的典型页面，并在 HTML 中检索默认语言的文本。如果在 `/ja/` 页面中检索到了 "Add to cart"，这要么是翻译遗漏，要么是未预期的语言回退。
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## 填补空白
+
+确定缺失的内容后，可以使用 `intlayer fill` 自动补全空条目，而 `autoFill` 选项可以在声明内容时直接生成各语言环境的文件。详见 [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/autoFill.md)。
+
+我们必须清醒地认识到：机器自动填充只是把一个**看得见的漏洞**变成了**看不见的漏洞**。键名填上了内容，审计变绿通过了，但文案还没有任何人审阅过。可以用它来解救紧急上线，但对于任何涉及付费、法律条款或转化决策的核心文案，必须安排人工复核。
+
+## 常见错误
+
+- **将回退机制视作安全保护。** 它只是兜底渲染手段，不是保险锁。静默显示的英文页面本身就是一个 Bug。
+- **依赖 CLI 输出来拦截 CI。** `intlayer content test` 退出码为 0，务必在单元测试中进行断言。
+- **强制要求所有语言都齐全。** 只要发生一次阻塞紧急发布，该检查就会被团队彻底移除。
+- **只查字典目录从不检查渲染画面。** 硬编码字符串在字典中是绝对不可见的。
+- **测试中仅验证默认语言。** 唯一绝不可能缺失的语言就是默认语言。
+- **以机器自动填充作为流程终点。** 审计变绿但文案质量毫无保障。
+
+## 深入阅读
+
+- [测试你的内容：CLI 审计、编程式 API 与 UI 断言](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/testing.md)
+- [ESLint 插件规则（包括 `no-raw-text` 与 `no-unused-content`）](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)
+- [autoFill：自动生成各语言环境的声明文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/autoFill.md)
+- [配置参考：`locales`、`requiredLocales`、`defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [跨框架性能基准报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)
+- [i18next 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/i18next.md)
+- [国际化到底涵盖哪些内容](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/what_is_internationalization.md)
+- [组件级 i18n 与集中式 i18n 的架构对比](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/per-component_vs_centralized_i18n.md)

package/blog/zh/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "在 CI/CD 中自动化翻译而不发布糟糕文案"
+description: 在三个阶段自动化 i18n，pre-push、pull request 与运行时。如何基于覆盖率拦截构建、安全自动补全并避免无限提交循环。
+keywords:
+  - 自动化翻译 ci
+  - i18n ci cd
+  - github actions 翻译
+  - husky pre-push
+  - 持续本地化
+  - 翻译流水线
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# 在 CI/CD 中自动化翻译而不发布糟糕文案
+
+手动翻译根本无法跟上现代软件的发布节奏。周五有人新增了一个文案字符串，导出操作要等到下一个迭代，而此时又有另外三种语言落后了。实现自动化并不复杂。如何在不悄悄向用户发布未经验证的机器输出的前提下实现自动化，才是真正值得深入思考的问题。
+
+## 目录
+
+<TOC/>
+
+## 无需迁移现有代码即可实现自动化
+
+下面介绍的流水线架构与具体的库无关，工具本身也是如此。如果你的文案采用 i18next、next-intl、react-intl、vue-i18n 或 next-translate 的 JSON 字典格式，[Sync JSON 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 可以就地读写这些文件：
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // 或针对 next-intl / react-intl 的 "icu"
+    }),
+  ],
+};
+
+export default config;
+```
+
+你的应用可以继续保持原有的导入方式。后续的 CI 任务将直接填充并校验你现有的字典，审查者在 PR 中看到的 diff 只是 `locales/fr/checkout.json` 的更新，而不是大规模的代码迁移。还有用于 gettext 工作流的 [Sync PO 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md)，以及保持运行时 API 不变的 [兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md)。
+
+## 将拦截门禁（Gate）与内容填充（Fill）分离
+
+两项完全不同的任务经常被混淆。
+
+**门禁（Gate）** 是一项会失败的检查。它的作用是声明当前构建不可发布，因为缺少必需的语言环境。它不写入任何文件。
+
+**填充（Fill）** 是一项变更操作。它生成缺失的翻译并提交代码。它绝不会导致构建失败。
+
+仅运行填充意味着没有任何机制进行拦截，未经验证的机器文案会直接流向生产环境。仅运行门禁意味着构建频繁变红，每次都需要人工介入修复。大多数团队希望同时拥有两者，但绑定到不同的触发器上：在 Pull Request 上触发填充，在合并到发布分支时触发门禁。
+
+## 自动化的落脚点对比
+
+| 阶段          | 触发器   | 适用场景                     | 成本                                   |
+| :------------ | :------- | :--------------------------- | :------------------------------------- |
+| Pre-push 钩子 | 本地 Git | 快速反馈，不消耗 CI 分钟数   | 在开发者的机器上运行并消耗个人 API Key |
+| Pull request  | CI 任务  | 合并前审查，安全统一管理密钥 | 消耗 CI 分钟数及每个 PR 的模型调用费用 |
+| 发布分支      | CI 任务  | 基于覆盖率的严格拦截门禁     | 廉价，无模型调用                       |
+| 运行时        | CMS      | 无需重新构建即可更新内容     | 依赖托管服务                           |
+
+## Pre-push：最快速的反馈循环
+
+Husky 可以在代码离开本地机器之前完成填充，因此新生成的翻译会与引入新字符串的代码处于同一个推送中。
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` 将工作范围限制为尚未推送的内容，从而避免每次推送都耗费大量时间。`--mode complete` 只填充缺失的内容，不会重写已经有值的条目，确保人工审查过的翻译绝不会被静默覆盖。
+
+在 Monorepo 中，可以针对各个应用单独限定范围：
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+缺点也是显而易见的：每个开发者都需要一个 API Key，而且费用由执行推送的人承担。这就是为什么团队扩大后大多数会将其迁移到 CI 的原因。
+
+## Pull request：在审查发生的地方进行填充
+
+在 GitHub Actions 中处理相同的逻辑，并将范围限制在 diff 中：
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+其中有四个关键配置：
+
+- **`fetch-depth: 0`** 是 `--git-diff` 正常运行所必需的。浅克隆（Shallow clone）没有基准分支来进行 diff，填充过程会静默处理空内容。
+- **提交信息中的 `[skip ci]`** 可以防止工作流无限次互相触发。如果没有它，该任务会触发新的运行并再次提交，一夜之间就会耗尽 CI 配额。
+- **带有 `cancel-in-progress` 的 `concurrency`** 可以防止并发推送相互竞争写入相同的文件。
+- **`--git-diff`** 将填充范围限定在 PR 中变更的内容。如果省略它，每次运行都会重新翻译整个字典。
+
+翻译内容会作为 commit 提交到 PR 分支，这意味着代码审查者可以在 diff 中进行审核。这正是选择在此阶段执行而不是合并后再执行的根本原因。
+
+## 发布分支：门禁检查
+
+门禁不需要访问 AI 模型，执行速度应当非常快。
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+通过断言覆盖率的测试来提供保障，而不是依赖终端输出：
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("没有缺失必需的语言环境", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` 虽然会输出检查报告，但退出状态码始终为 0，仅供参考而不会阻断流水线。可以在本地使用该命令；而在 CI 中使用测试断言。更多区别参见 [如何检测缺失的翻译](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/detecting_missing_translations.md)。
+
+## `requiredLocales` 让门禁在实际开发中可持续运行
+
+如果门禁要求所有十八种语言全部完整，就会因为最慢的一种语言未就绪而阻塞所有发布，最终在一个月内被团队彻底禁用。
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+声明你支持的所有语言，并且仅将那些必须阻断发布的语言设为必需项。其余语言可以异步补充，绝不会拖延代码上线。
+
+## 将翻译完全移出代码仓库
+
+另一种模式是在代码中仅保留一种基准语言，其余语言通过带有 Live Sync 功能的 CMS 进行远程管理。这样内容变动完全不需要重新构建应用，使文案修改周期与技术部署周期解耦。
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+这非常适合非技术人员负责文案的团队。这是一种权衡：你获得了内容编辑的自主权，但放弃了仅通过 git checkout 即可完全确定应用渲染状态的确定性。详情见 [CMS 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)。
+
+请注意，`clientSecret` 属于服务端凭证。它应当保存在 CI Secrets 和服务器环境变量中，绝不能暴露给客户端 bundle。
+
+## 坦诚面对局限性
+
+以上所有方案自动化的都是**覆盖率**，而不是**翻译质量**。机器自动填充把一个原本显眼的缺失变成了看不见的缺失：由于 key 已经有了值，审计顺利通过，但没有任何人阅读过这段文案。
+
+对于内部后台、更新日志或处于 Beta 阶段的语言，这完全可以接受。但对于定价页面、法律条款、支付失败提示或任何用户做决策前阅读的内容，这是不可接受的。这些内容必须经过人工审核，并全程使用 `--mode complete`，确保审核过的文案不会在后续构建中被自动覆盖。
+
+同时为模型提供上下文以保证文案风格统一：
+
+```ts
+ai: {
+  applicationContext: "B2B 发票管理应用。正式专业语调。绝不要翻译产品名称。",
+}
+```
+
+## 常见错误
+
+- **自动提交中缺少 `[skip ci]`。** 导致任务陷入死循环耗尽配额。
+- **使用 `--git-diff` 时进行了浅克隆（Shallow clone）。** 没有比较基准，什么都没填充且没有任何警告。
+- **每次运行都填充整个字典目录。** 务必使用 `--git-diff` 或 `--unpushed` 控制成本。
+- **将 CLI 报告用作门禁检查。** 退出状态码为 0，无法阻断流程。
+- **将每种语言都设为必需（required）。** 首次阻塞发布时就会导致检查被永久移除。
+- **只配置了填充任务却没有设置任何门禁。** 没有任何步骤会报错，未经审查的机翻直接上线。
+- **将模型 API Key 存放在代码库中。** 必须和 `clientSecret` 一样保存在 CI Secrets 中。
+
+## 深入阅读
+
+- [CI/CD：通过 Husky、GitHub Actions 与 CMS 自动生成翻译](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/CI_CD.md)
+- [测试你的内容并在覆盖率不足时阻断构建](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/testing.md)
+- [autoFill：自动生成各语言环境的声明文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/autoFill.md)
+- [配置参考：`locales`、`requiredLocales`、`editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [跨框架性能基准报告](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/index.md)
+- [i18next 兼容适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/i18next.md)
+- [如何检测缺失的翻译](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/detecting_missing_translations.md)
+- [如何测试翻译而不写出脆弱的测试](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/i18n_testing_strategies.md)