frontend-i18n-essentials

Packaged Knowledge Snapshot

This packaged copy includes local note snapshots for portability. When the original Obsidian absolute path is unavailable, use the packaged snapshot instead:

• /Users/kunkun/note/11-前端工程/前端国际化（i18n）认知对齐.md -> references/packaged-knowledge/前端国际化（i18n）认知对齐.md

Frontend i18n Essentials

这个 skill 在做什么

做国际性网站时的 i18n 规划与执行路由器。用户要做多语言、补多语言、或 i18n debug 时，本 skill 干两件事：

1. 按三层正交模型诊断用户的痛点在哪一层（运行时 / 翻译内容 / 视觉），避免把不同层的问题混着解
2. 按三场景分流（新搭 / 补多语言 / debug）输出对应决策 + 执行资产（prompt 模板 / subagent 编排 / checklist / glossary 骨架）

本 skill 不替用户做具体库选型（next-intel vs i18next vs react-intl 让 AI 按项目栈判断），不跑完整开发流程（执行交给开发实现剧本）——它只管"i18n 相关决策的判断方向"和"翻译质量流水线的编排"。

核心赌局

i18n 最常见的失败是把三件正交的事混成一件：

• 用户抱怨"网站不地道"——问题在翻译内容层（机翻味）、视觉层（字体塌）、还是运行时层（切语言把表单清空了）？
• 模型默认倾向把这些症状堆在一起开一个大药方，结果哪一层都没治好

本 skill 的硬约束：先定位层，再开方。三层各自独立评审、独立优化。

何时进入本 skill

要进：

• 用户说"做国际性网站 / 做国际化 / 做多语言 / 加英文版 / 加日文版 / i18n / 本地化 / localization"
• 老项目要补多语言，问"怎么开始 / 架构怎么搭 / 翻译怎么搞"
• 讨论 i18n 相关具体决策：路由用子路径还是子域名 / SEO hreflang 怎么配 / 语言切换器放哪 / 切语言要不要刷新 / 复数怎么处理 / 字符串提取 / 字体跨语言
• 翻译质量问题：机翻味重、当地人读着古怪、文化陷阱
• i18n 相关 debug：SEO 流量异常、语言切换后状态错乱、缺翻译页面 404

不要进：

• 项目是纯单语言（无国际化意图，用户没说要扩展）→ 跳过本 skill
• 纯翻译任务不涉及前端（纯文案翻译）→ 不是本 skill 范畴
• RTL 排版深度实现（目标市场不含中东 / 希伯来 / 波斯 / 乌尔都时直接跳过，附录里有清单但不是主场）
• UI 设计 / 视觉规划 / 动效 / 组件库（那是 frontend-suite 其他 skill 的活）

知识库依赖

本 skill 的认知底座住在 Obsidian，本文件只放执行层的路由 + 模板。决策前必读底座：

文件	用途	何时读
/Users/kunkun/note/11-前端工程/前端国际化（i18n）认知对齐.md	三层正交模型 + 四条元原则 + 8 题原则 + 三场景速查	启动必读

重要分工：

• 认知层（Obsidian 笔记）：原则 + 判断标准 + 禁区——回答"为什么这么做"
• skill 层（本文件）：执行流程 + prompt 模板 + 决策树——回答"怎么做"

两者互补不重复。认知笔记更新优先，skill 同步引用。

执行顺序

步骤 0 读认知层 + 场景路由
  ↓
步骤 1 三层诊断（运行时 / 翻译内容 / 视觉）
  ↓
步骤 2 按层 × 场景输出决策 + 落地方案
  ↓
步骤 3 翻译内容层：subagent 并行化编排（按需）
  ↓
步骤 4 输出结构化结论 + handoff 给执行者

---

步骤 0：读认知层 + 场景路由

先 Read 认知底座（一次即可，后续按章节回读）： /Users/kunkun/note/11-前端工程/前端国际化（i18n）认知对齐.md

场景路由（一次问答定档）：

问用户（或从上下文推断）：

你的项目是 A）全新国际化项目从零搭 / B）已有项目补多语言 / C）i18n 相关 debug？

场景	核心诊断点	跳过什么
A 新搭	架构决策前置（路由 / 库 / 字体栈 / ESLint 防御）	字符串提取（新项目第一天包裹不需要这步）
B 补多语言	老项目适配 + 一次性大工程	可能跳 RTL、简化路由策略（保持老 URL）
C Debug	精确定位现象 → 三层哪一层 → 具体诊断清单	架构决策、翻译流水线设计

场景确定后进入步骤 1。

---

步骤 1：三层诊断

不管三种场景哪个，都要先定位在哪一层：

运行时层

涉及：库选型、复数/插值语法、路由、字符串提取、动态切换、fallback、SEO、语言包管理

诊断问题：

• 架构要不要做、做什么形态？
• 哪些老代码要改？
• 有没有"刷新状态错乱 / SEO 异常 / 缺翻译 404"这类症状？

翻译内容层

涉及：翻译质量、当地人视角、文化适配

诊断问题：

• 翻译由谁出？（AI / 机翻 / 人工 / 混合）
• 审校流水线要不要搭？
• 有没有"机翻味重 / 当地人看着别扭 / 踩文化禁忌"这类反馈？

视觉层

涉及：字体跨语言一致、布局（含 RTL）、视觉量感

诊断问题：

• 品牌调性有没有要求字体一致？
• 中英日韩并排视觉会不会塌？
• 目标市场含不含 RTL 语言？

多层交叠时：按"严重度 × 易解度"优先级排，一次解一层，不要同时开三张药方。

---

步骤 2：按层 × 场景输出决策

运行时层决策清单

按认知笔记的相关章节回读 + 组合输出。常见决策：

决策点	推荐方案
URL 结构	子路径 site.com/zh/，默认语言不带前缀
首次访问	默认语言 + Accept-Language 浮条提示，禁止静默自动跳转
切换刷新	SPA 软切换（router.push + 懒加载 + re-render），保留路径
语言持久化	cookie 优先（SSR 首屏需要），1 年过期
复数 / 插值	用库原生 ICU MessageFormat，不自拼不绕开
fallback 分层	生产回退默认语言 + 开发显示 key + CI 核心语言 block
hreflang	双向 + self-reference + x-default，locale 严格 ISO 码
字符串提取	AI + subagent 扫 + 人审 + ESLint 永久兜底
切换器位置	右上角 + 目标语言本土文字显示 + 国旗图标可选
key 命名	业务语义（user.profile.saveSuccess），禁止 hash

每条背后的"为什么"回查认知笔记对应章节。

翻译内容层决策清单

默认走三段流水线（跳到步骤 3 详细展开）。

视觉层决策清单

决策点	推荐方案
调性优先级	调性 > 一致量感 > 性能
字体栈	Noto Sans / Serif 家族或 Apple 系统栈，禁止手工拼 fallback
CJK / Latin 混排	font-family: "Noto Sans", "Noto Sans SC"（Latin 优先，CJK fallback）
调性字体	像素风 / 复古 / 手写等必须所有语言贯彻同调性，禁止某语言找不到就降级
webfont	要用就必须子集化（Google &text= 或 fonttools subset），禁止整包加载 CJK
系统字体	仅"调性不强 + 性能要求极高"时可默认 system-ui
CSS 逻辑属性	无论是否做 RTL 都用 margin-inline-start 取代 margin-left

---

步骤 3：翻译内容层 Subagent 并行化编排

本步骤专门处理翻译 / 审校任务。架构 / 路由 / 字体场景跳过。

三段流水线总览

第一段：机翻 / AI 直译
  ↓
第二段：AI 本地人审（核心，subagent 并行）
  ↓
第三段：人工兜底（只审敏感文案清单）

Subagent 切分策略

模式	切分	何时用
A. 翻译初稿	按目标语言（1 subagent × 1 locale）	从源语言批量产出 N 份目标语 json
B. 本地化审校	按 locale × persona（3-5 persona × 每种语言）	质量验证阶段
C. 业务域并行	按 locale × domain	大项目（多业务 json × 多语言）

实战中 ABC 可叠加：5 语言 × 8 业务域 × 3 persona = 120 subagent 任务。

主 agent 必兜底的三件事

1. glossary 前置：主 agent 先和用户定核心术语表 glossary.json 下发每个 subagent 作为硬约束。例：

{
  "Login": {
    "zh": "登录",
    "ja": "ログイン",
    "ar": "تسجيل الدخول"
  },
  "Dashboard": {
    "zh": "控制台",
    "ja": "ダッシュボード",
    "ar": "لوحة القيادة"
  }
}

禁止 subagent 自由译 glossary 内的术语。

2. key 完整性校验：subagent 返回后，主 agent schema diff 对照源语言 json 的 key 树，漏 key / 错嵌套回发补。

3. 文化 checklist 强制注入：spawn 每个 subagent 时 prompt 里必带：

审校时必须显式 check 以下文化陷阱：
- 颜色（红色在不同文化含义反转）
- 数字（4 / 13 / 666 / 7 的文化含义）
- 手势图标（OK / 大拇指在不同文化含义反转）
- 宗教（食物成分、节日祝福、图像敏感）
- 政治（地图、国名、争议区域）
- 幽默（笑话 / 双关语跨文化失效）

Subagent prompt 模板（翻译初稿 - 模式 A）

你是专业翻译，将下面的 json 语言包从 [源语言] 翻译到 [目标 locale]。

输入：[源 json]
术语表（强制遵循）：[glossary.json 对应 locale 段]

输出要求：
1. 严格保留 json 结构、key 名不变，只译 value
2. 术语表内的词必须按表中目标语译法，不自由发挥
3. ICU MessageFormat 语法保留（如 `{count, plural, ...}` 中的 case 名不译）
4. 直译即可，不追求地道——地道化在下一段审校做
5. 输出纯 json，不加任何解释

源 json:
[...]

Subagent prompt 模板（本地化审校 - 模式 B）

你是一名 [国籍] 用户，[年龄段]、[职业/身份]、[教育程度]、
[对本产品领域的熟悉度]。请以该身份读下面这段译文，按下述四段结构输出审校意见。

审校时必须显式 check 以下文化陷阱：
- 颜色 / 数字 / 手势图标 / 宗教 / 政治 / 幽默（详见上文清单）

输出格式（对每个有问题的条目）：
【别扭处】原文"[片段]"
【严重度】高/中/低（高=误解风险，中=不地道但能懂，低=语气偏好）
【建议】建议改成"[新译]"
【理由】当地人通常这么说因为...

译文：
[...]

源文（参考）：
[...]

每种语言至少跑 3 个 persona（主力用户 + 边缘用户 + 高龄/低教育），取并集。

人工兜底清单（主 agent 标注、人工兜底）

以下类型的 key 由主 agent 在 glossary 或单独 flag 文件中标记 needs-human-review: true，AI 审完仍要人工过一遍：

1. 法律 / 合规：legal.* / privacy.* / terms.*
2. 错误提示：error.* / warning.*
3. 品牌 slogan / 首页主标题：marketing.hero.* / brand.*
4. 支付 / 结账链路：checkout.* / payment.*
5. 客服话术：support.* / help.*

---

步骤 4：输出结构化结论 + handoff

最终输出给用户的三件事：

1. 诊断小结（一句话）：本次任务落在哪一层 × 哪个场景
2. 决策清单（分层表格）：每条决策 + 理由 + 认知笔记的对应段落锚
3. 执行 handoff：
   • 运行时层决策 → 交给开发实现剧本 / 具体框架文档
   • 翻译任务 → subagent 编排已就位，主 agent 直接 spawn
   • 视觉字体决策 → 交给 frontend-visual-reference 或设计资产生成 skill

示例输出：

【诊断】本次任务：场景 B（补多语言）× 三层均涉及

【运行时层决策】
- 路由：子路径 + 默认语言不带前缀（不改老 URL）
- hreflang：HTML head 模式（项目 < 500 页）
- 字符串提取：AI + subagent 并行 + ESLint 兜底
- 切换器：右上角下拉 + 本土文字显示 + cookie 持久化
（每条理由 → 参见 Obsidian 笔记 §运行时层）

【翻译内容层决策】
- 走三段流水线
- Glossary 待用户确认 10 个核心术语
- Subagent 切分按 locale × 3 persona 并行
- 人工兜底：legal / error / checkout / brand 四类 key
（prompt 模板已就位见步骤 3）

【视觉层决策】
- 项目调性：[待用户确认]
- 字体栈：先按 Noto 家族方案落地，调性确认后再定制
（参见 Obsidian 笔记 §视觉层）

【Handoff】
- 运行时层 → 开发实现剧本 + 框架文档（next-intl / i18next 选型）
- 翻译任务 → 待 glossary 确认后主 agent spawn subagents
- 视觉层 → 待调性确认后 frontend-visual-reference 出字体方案

---

三场景详细速查

场景 A 新搭项目

关键动作：

1. 第一天就用框架原生 i18n（Next.js / Nuxt / Astro 内置）
2. URL 策略定好（子路径 + 默认语言不带前缀）
3. ESLint i18n 插件接好（防硬编码回归）
4. 字体调性前置决策（含目标语言配套字体栈）
5. hreflang 中间件自动生成
6. 翻译流水线搭起来（glossary + subagent 编排模板）

场景 B 补多语言

关键动作：

1. 绝不改老 URL（原路径 = 默认语言，新加 /xx/ 前缀）
2. 字符串提取：AI + subagent 并行 + 人审 + 批量改 + ESLint 兜底
3. 每加一种语言，所有页面 hreflang 批量更新（subagent 并行改模板）
4. 语言切换器首次接入（右上角 + cookie 持久化）
5. 调性字体栈若已存在，评估是否覆盖目标语言

场景 C Debug 常见症状

症状	诊断入口	常见根因
SEO 流量下降 / 被错误语言索引	Search Console 国际定位报告	hreflang 双向不一致 / canonical 冲突 / 静默自动跳转
切语言后状态错乱	查派生状态	缓存 / 格式化 state 没监听 locale 变化
切语言后跳回首页	查路由实现	没保持路径，router.push('/zh/') 而非 /zh/{currentPath}
缺翻译页面 404	查 fallback 配置	没配回退默认语言
某处文案没翻（残留原语言）	ESLint + 搜硬编码	字符串提取漏抽 / 缺 t() 包裹
切语言表单丢失	查组件是否 unmount	SPA 软切换实现错误导致 re-mount
中英混排字体塌	查 font-family 链	CJK 字体在前导致英文字母质量差

---

成熟度与演化计划

当前成熟度：0.5（基于 2026-04-23 认知采访沉淀，未经实战验证）

演化节奏（参考 git-workflow 的 3-5 次实战再固化原则）：

• 0.5 → 0.7：跑过 3 次真实 i18n 项目后，字段 / prompt 模板 / glossary 骨架按实战反馈微调
• 0.7 → 0.9：跑过 5+ 次后，评估是否拆分为 i18n-setup（架构 / 路由 / 提取）+ i18n-localize（翻译 / 审校 / subagent 编排）两个 skill
• 0.9 → 1.0：拆分后稳定运行、考虑升格为独立 i18n-suite plugin（3-4 skill 语义内聚）

Deletion-spec

• 触发删除条件：当 i18n 相关认知已被模型默认稳定吸收（无需本 skill 做路由就能按三层模型分析任务）、或本 skill 的价值被独立 i18n-suite plugin 完全覆盖后，本 skill 可降级
• 禁用方式：删除本目录 skills/frontend-i18n-essentials/；frontend-suite 的 plugin.json description 同步移除 i18n 段；README 同步
• 卸载清单：
  • ~/.agents/plugins/frontend-suite/.claude-plugin/plugin.json（description 段）
  • ~/.agents/plugins/frontend-suite/.codex-plugin/plugin.json（description 段）
  • ~/.agents/plugins/.claude-plugin/marketplace.json（frontend-suite description）
  • ~/.agents/plugins/frontend-suite/README.md（i18n 段）
  • /Users/kunkun/note/11-前端工程/前端国际化（i18n）认知对齐.md（认知笔记——是否同步删除视是否还有其他引用）