Skill

frontend-i18n-essentials

Diagnoses and resolves frontend internationalization (i18n) issues using a three-layer model (runtime, translation content, visuals). Guides architecture decisions, translation pipeline setup, and SEO for multi-language sites.

JavaScript

Popularity

Stars

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/ai-frontend-design-kit:frontend-i18n-essentials

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Supporting Files

references/packaged-knowledge/manifest.jsonreferences/packaged-knowledge/前端国际化（i18n）认知对齐.md

SKILL.md

387 lines · ~2.3k tokens

Stats

Stars7

MaintenanceGood

Last CommitMay 16, 2026

Actions

View Source View Plugin View on GitHub View README

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（认知笔记——是否同步删除视是否还有其他引用）

frontend-i18n-essentials

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

frontend-i18n-essentials

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Packaged Knowledge Snapshot

Frontend i18n Essentials

这个 skill 在做什么

核心赌局

何时进入本 skill

知识库依赖

执行顺序

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

步骤 1：三层诊断

运行时层

翻译内容层

视觉层

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

运行时层决策清单

翻译内容层决策清单

视觉层决策清单

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

三段流水线总览

Subagent 切分策略

主 agent 必兜底的三件事

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

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

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

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

三场景详细速查

场景 A 新搭项目

场景 B 补多语言

场景 C Debug 常见症状

成熟度与演化计划

Deletion-spec

Similar Skills

Packaged Knowledge Snapshot

Frontend i18n Essentials

这个 skill 在做什么

核心赌局

何时进入本 skill

知识库依赖

执行顺序

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

步骤 1：三层诊断

运行时层

翻译内容层

视觉层

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

运行时层决策清单

翻译内容层决策清单

视觉层决策清单

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

三段流水线总览

Subagent 切分策略

主 agent 必兜底的三件事

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

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

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

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

三场景详细速查

场景 A 新搭项目

场景 B 补多语言

场景 C Debug 常见症状

成熟度与演化计划

Deletion-spec

Similar Skills