@intlayer/docs 9.4.1 → 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)