| name | frontend-i18n-essentials |
| description | 前端国际化（i18n）的综合规划与执行指南——做国际性网站、多语言架构、补多语言、翻译质量验证、字体跨语言统一、路由 / SEO / 字符串提取 / 动态切换等 i18n 相关任务时用。本 skill 按"运行时 / 翻译内容 / 视觉"三层正交模型路由：先定位用户的 i18n 痛点在哪一层，再走对应决策流；翻译内容层默认走三段流水线（机翻 → AI 本地人审 → 人工兜底）+ subagent 并行化（locale × persona × domain）。触发：用户说"做国际性网站""加多语言""补英文版""做 i18n""多语言网站的 SEO""路由用子路径还是子域名""本地化翻译""文化陷阱""AI 扮演当地人审翻译""字体跨语言不统一""语言切换器怎么做""字符串提取"。不用于纯单语言产品（没有国际化意图的就别套）、不用于纯翻译任务不涉及前端（那是纯文案）、不用于 RTL 排版深度实现（附录里有清单但不是本 skill 主场，目标市场不含中东时直接跳过）。 |
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 干两件事：
- 按三层正交模型诊断用户的痛点在哪一层（运行时 / 翻译内容 / 视觉），避免把不同层的问题混着解
- 按三场景分流（新搭 / 补多语言 / 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 必兜底的三件事
- glossary 前置：主 agent 先和用户定核心术语表
glossary.json 下发每个 subagent 作为硬约束。例：
{
"Login": {
"zh": "登录",
"ja": "ログイン",
"ar": "تسجيل الدخول"
},
"Dashboard": {
"zh": "控制台",
"ja": "ダッシュボード",
"ar": "لوحة القيادة"
}
}
禁止 subagent 自由译 glossary 内的术语。
-
key 完整性校验：subagent 返回后，主 agent schema diff 对照源语言 json 的 key 树，漏 key / 错嵌套回发补。
-
文化 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 审完仍要人工过一遍：
- 法律 / 合规：
legal.* / privacy.* / terms.*
- 错误提示：
error.* / warning.*
- 品牌 slogan / 首页主标题：
marketing.hero.* / brand.*
- 支付 / 结账链路：
checkout.* / payment.*
- 客服话术：
support.* / help.*
步骤 4：输出结构化结论 + handoff
最终输出给用户的三件事：
- 诊断小结（一句话）：本次任务落在哪一层 × 哪个场景
- 决策清单（分层表格）：每条决策 + 理由 + 认知笔记的对应段落锚
- 执行 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 新搭项目
关键动作：
- 第一天就用框架原生 i18n（Next.js / Nuxt / Astro 内置）
- URL 策略定好（子路径 + 默认语言不带前缀）
- ESLint i18n 插件接好（防硬编码回归）
- 字体调性前置决策（含目标语言配套字体栈）
- hreflang 中间件自动生成
- 翻译流水线搭起来（glossary + subagent 编排模板）
场景 B 补多语言
关键动作：
- 绝不改老 URL（原路径 = 默认语言，新加
/xx/ 前缀）
- 字符串提取：AI + subagent 并行 + 人审 + 批量改 + ESLint 兜底
- 每加一种语言，所有页面 hreflang 批量更新（subagent 并行改模板）
- 语言切换器首次接入（右上角 + cookie 持久化）
- 调性字体栈若已存在，评估是否覆盖目标语言
场景 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（认知笔记——是否同步删除视是否还有其他引用）
