# i18n 修复不是机械替换：颗粒度判断需更慎重

**日期**: 2026-05-10
**触发场景**: logging-system 模块 i18n 修复 PR（#294），6 page ~170 处硬编码替换
**类别**: 工作方式 / PR 拆分判断

---

## 现象

logging-system 模块发现 7/8 page 完全没用 locale 文件已有的 i18n keys，硬编码中文。AI 第一次评估时跟"颜色 token 化"放在同一类，认为都是"机械化替换"，跟用户说"170 处替换 ~30 分钟"。用户拍板"6 page 一个 PR 全做"。

实操结果：实际花了 ~1 小时（含建 9 个 task tracking + 4 次 build 验证 + 中途读完 6 个 page），PR 涉及 9 个文件 +206/-155 LOC，且每处都需要：
1. 找 locale 里对应的 key（若有）
2. 判断 key 语义是否吻合上下文（"应用日志" vs 短列名"应用"）
3. 新增缺失 key（zh + en 双向同步）
4. 处理 template literal 中的中文（不能简单字符串替换）

PR 大、review 分散、决策点多——AI 不该用"机械替换"心智模型对待。

---

## 根因

**i18n 修复 ≠ 颜色 token 替换**：

| 维度 | 颜色 token (PR #291) | i18n 修复 (PR #294) |
|---|---|---|
| 替换关系 | hex → token，1:1 全局映射表 | 文案 → key，每处需上下文判断 |
| 工具 | `sed -i` 批量 | 每处 `Edit` |
| 缺失映射 | 保留原色（标记给设计师） | 必须补 key，且 zh/en 双语同步 |
| Template literal | 不涉及 | 频繁出现（"`${count} 请求, 错误率 ${rate}%`"） |
| 风险 | 视觉微调 | 句法不通 / missing key / 中英混杂 |
| Review 焦点 | 色号映射对不对 | 每个 key 的双语翻译 + 上下文 |

把这两类放在同一个心智模型下评估，必然低估 i18n 工作量 ~3-4×。

---

## 学到的规则

**"机械化"判断的前提条件**：
- ✅ 1:1 映射表能预先定义（hex → token）
- ✅ 替换上下文不影响选择（无歧义）
- ✅ sed/正则一次性可完成（无需逐处 Edit）
- ✅ 验证手段统一（build pass = 验证 pass）

**"逐项判断"任务的特征**：
- ❌ 同一个值在不同上下文需要不同映射（"应用" vs "应用日志"）
- ❌ template literal 内嵌（不能纯字符串替换）
- ❌ 需要新增 / 修改基础设施（补 keys / 升级 Pagination 组件）
- ❌ 验证需要人工（双语切换 / 视觉 review）

**i18n 修复明显属于第二类**。下次遇到 i18n 任务的拆分建议：
- 单个 PR 控制在 **1-2 个 page**（30-50 处替换）
- 升级 Pagination 这种"通用组件 i18n 化"独立成 PR（基础设施不混进 page i18n）
- 补 locale keys（zh + en）放进单独 commit，方便翻译人员分别 review

---

## 适用范围

- 任何"批量替换" 类任务的 PR 拆分判断（i18n / 注释翻译 / API 字段重命名 / 类型精简等）
- 评估"做完要多久"时，先识别上面的"机械 vs 逐项"特征
- 遇到 stacked PR 链时，第三层 PR 的范围要严格控制——上游已占用足够 review 注意力

不适用于：纯重构（simplify）、纯视觉（颜色 token）这种已经"机械化"的任务。

---

## 相关 PR

- #294 (本次 i18n PR，stacked on #291 on #290)
- #291 (颜色 token，机械化的对照组)
- #290 (simplify，机械化的对照组)