localize

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

本地化流水线

本地化不仅仅是翻译，而是让游戏在每种语言和地区都显得原汁原味的完整过程。本地化质量差会破坏沉浸感、令玩家困惑，还会阻碍平台认证。本技能涵盖完整流程，从字符串提取到文化审查、配音录制、RTL 布局测试，以及本地化 QA 签核。

模式：

• scan — 查找硬编码字符串和本地化反模式（只读）
• extract — 提取字符串并生成可供翻译的表格
• validate — 检查翻译是否完整、占位符是否正确以及长度是否合适
• status — 查看所有语言区域的覆盖情况矩阵
• brief — 为外部团队生成译者背景说明文档
• cultural-review — 标记在文化上敏感的内容、符号、颜色和习语
• vo-pipeline — 管理配音本地化：脚本、录制规格和集成
• rtl-check — 验证 RTL 语言布局、镜像和字体支持
• freeze — 执行字符串冻结；在开始翻译前锁定源字符串
• qa — 在发布前运行完整的本地化 QA 流程

如果未提供子命令，则输出用法并停止。判定：FAIL — 缺少必需的子命令。

---

每次 AskUserQuestion 调用都遵循 .claude/docs/automation-modes.md （始终协作式询问 · 引导式仅限重大事项 · 自主模式记录并继续； automation_always_ask 类别始终提示）。

阶段 2A：扫描模式

在代码根目录（根据 .claude/docs/code-root-resolution.md 解析）中搜索硬编码的面向用户的字符串。如果代码根目录尚未解析，则报告 NOT ASSESSED — code root unresolved，而不是报告零条命中。 未解析根目录却报告零条命中，会让人以为“没有需要本地化的内容”，这正是本检查要避免的问题：

• UI 代码中未使用本地化函数（tr()、Tr()、NSLocalizedString、GetText 等）封装的字符串字面量
• 应使用参数化处理的拼接字符串
• 使用位置占位符（%s、%d）而非命名占位符（{playerName}）的字符串
• 混用受区域设置影响的数据（数字、日期、货币），却未采用适配区域设置的格式化方式的格式字符串

搜索本地化反模式：

• 日期／时间格式化未使用适配区域设置的函数
• 数字格式化未考虑区域设置（1,000 与 1.000）
• 嵌入在图像或纹理中的文本（标记 assets/ 中的资源文件）
• 假定文本从左到右排列的字符串（位置布局、字符串拼接顺序）
• 在字符串逻辑中硬编码的性别／复数假设（必须使用复数形式或性别标记）
• 硬编码的标点符号（例如 "You won!" —— 不同地区的感叹号样式有所不同）

报告所有发现，并附上文件路径和行号。此模式为只读模式，不会写入任何文件。

---

阶段 2B：提取模式

• 扫描所有源文件，查找本地化字符串引用
• 与 assets/data/strings/ 中现有的字符串表进行比对
• 为尚未设置键的字符串生成新条目
• 根据以下约定建议键名：[category].[subcategory].[description]
  • 示例：ui.hud.health_label、dialogue.npc.merchant.greeting、menu.main.play_button
• 每个新条目都必须包含一个 context 字段，即译者注释，用于说明：
  • 字符串出现的位置（所在屏幕、场景）
  • 最大字符长度
  • 占位符的含义（{playerName} = 玩家选择的显示名称）
  • 适用的性别／复数语境

输出要添加到字符串表的新字符串差异。

向用户展示差异。询问：“可以将这些新条目写入 assets/data/strings/strings-en.json 吗？”

如果用户同意，只写入差异（新条目），不要完整替换文件。判定：COMPLETE — 字符串已提取并写入。

---

阶段 2C：验证模式

读取 assets/data/strings/ 中的所有字符串表文件。对于每种语言，检查：

• 完整性 — 源语言（en）中存在该键，但此语言没有对应译文
• 占位符不匹配 — 源文本中有 {name}，但译文中遗漏了它或添加了额外占位符
• 字符串长度违规 — 译文超过源 context 字段中记录的字符数限制
• 复数形式数量 — 此语言要求 N 种复数形式，但译文提供的形式更少
• 孤立键 — 存在译文，但代码根目录中没有任何地方引用该键
• 过时译文 — 源字符串在译文写入后发生了变化（标记为需要重新翻译）
• 编码 — 存在非 ASCII 字符，且字体图集支持这些字符（不确定时标记）

按语言和严重程度分组报告验证结果。此模式为只读模式——不会写入任何文件。

---

阶段 2D：状态模式

• 统计源表中可本地化字符串的总数
• 按语言统计：已翻译、未翻译、过时（源文本在翻译后发生变化）的字符串数量
• 生成覆盖率矩阵：

## Localization Status
Generated: [Date]
String freeze: [Active / Not yet called / Lifted]

| Locale | Total | Translated | Missing | Stale | Coverage |
|--------|-------|-----------|---------|-------|----------|
| en (source) | [N] | [N] | [N] | [N] | [N]% |
| [locale] | [N] | [N] | [N] | [N] | [X]% |

> **Every cell above is a count you must take from the string table — including
> the source row.** Do not pre-fill the source locale as `100%`: that asserts a
> result before counting, and on a project with no `assets/data/strings/` it
> produces a coverage report for a table that does not exist. If the string table
> is absent, the whole status output is
> **`NOT ASSESSED — no string table found`**, not a matrix of zeros with a
> confident source row.

### Issues
- [N] hardcoded strings found in source code (run /localize scan)
- [N] strings exceeding character limits
- [N] placeholder mismatches
- [N] orphaned keys
- [N] strings added after freeze was called (freeze violations)

此模式为只读模式——不会写入任何文件。

---

阶段 2E：简报模式

生成一份译者背景简报文档。此文档会与字符串表导出文件一同发送给外部翻译团队或本地化供应商。

读取：

• design/gdd/ — 提取游戏类型、基调、背景设定和角色名称。按章节阅读 GDD：使用 Grep 工具（内容模式，匹配 ^#）查找所需标题，再使用 offset 和 limit 参数读取相应范围。
• assets/data/strings/strings-en.json — 源字符串表
• design/narrative/ 中现有的任何设定或叙事文档

生成 production/localization/translator-brief-[locale]-[date].md：

# Translator Brief — [Game Name] — [Locale]

## Game Overview
[2-3 paragraph summary of the game, genre, tone, and audience]

## Tone and Voice
- **Overall tone**: [e.g., "Darkly comic, not slapstick — think Terry Pratchett, not Looney Tunes"]
- **Player address**: [e.g., "Second person, informal. Never formal 'vous' — always 'tu' for French"]
- **Profanity policy**: [e.g., "Mild — PG-13 equivalent. Match intensity to source, do not soften or escalate"]
- **Humour**: [e.g., "Wordplay exists — if a pun cannot translate, invent an equivalent local joke; do not translate literally"]

## Character Glossary
| Name | Role | Personality | Notes |
|------|------|-------------|-------|
| [Name] | [Role] | [Personality] | [Do not translate / transliterate as X] |

## World Glossary
| Term | Meaning | Notes |
|------|---------|-------|
| [Term] | [What it means] | [Keep in English / translate as X] |

## Do Not Translate List
The following must appear verbatim in all locales:
- [Game name]
- [UI terms that match in-engine labels]
- [Brand or trademark names]

## Placeholder Reference
| Placeholder | What it represents | Example |
|-------------|-------------------|---------|
| `{playerName}` | Player's chosen display name | "Shadowblade" |
| `{count}` | Integer quantity | "3" |

## Character Limits
Tight UI fields with hard limits are marked in the string table `context` field.
Where no limit is stated, target ±30% of the English length as a guideline.

## Contact
Direct questions to: [placeholder for user/team contact]
Delivery format: JSON, same schema as strings-en.json

询问：“我可以将这份译者简报写入 production/localization/translator-brief-[locale]-[date].md 吗？”

---

阶段 2F：文化审查模式

通过 Agent 启动 localization-lead。请其根据目标语言（从 assets/data/strings/ 和 assets/ 读取），审核以下内容的文化敏感性：

审查内容

符号和手势

• 竖起大拇指、OK 手势、胜利手势——含义因地区而异
• 艺术、UI 或音频中的宗教或精神象征
• 国旗、地图呈现方式、争议领土

颜色

• 白色（在一些亚洲文化中代表哀悼）、绿色（在一些地区具有政治关联）、红色（象征好运或危险）
• 与文化联想相冲突的警示颜色

数字

• 4（在日语和中文文化中与死亡相关）、13、666——标记 UI 中的使用情况（房间号、物品数量、价格）

幽默和习语

• 翻译到其他语言后会显得冒犯的习语
• 在某些市场不恰当的厕所或身体幽默（尤其是日本、德国和中东地区）
• 涉及特定地区文化敏感话题的黑色幽默

暴力和内容分级

• 可能需要调整 DE（德国）、AU（澳大利亚）、CN（中国）或 AE（阿联酋）分级的内容
• 血液颜色、血腥程度、毒品相关内容——如有需要，为不同地区的素材版本全部标记

名称和形象呈现

• 在目标语言中具有冒犯性、亵渎性或负面含义的角色名称
• 对民族、宗教或族群的刻板呈现

以表格形式列出调查结果：

发现	受影响的语言	严重程度	建议措施
[描述]	[语言]	[阻断 / 建议 / 备注]	[修改 / 标记以供审查 / 接受]

阻断 = 发布该语言版本前必须修复。建议 = 建议修改。备注 = 仅供参考。

询问：“我可以将这份文化审查报告写入 production/localization/cultural-review-[date].md 吗？”

---

阶段 2G：VO 流程模式

管理配音本地化流程。根据参数确定子任务：

• vo-pipeline scan — 找出所有需要录制配音的对白
• vo-pipeline script — 生成带导演注释的录音脚本
• vo-pipeline validate — 检查所有已录制的配音文件是否存在且命名正确
• vo-pipeline integrate — 验证代码／资源中是否正确引用了配音文件

VO 流程：扫描

读取 assets/data/strings/ 和 design/narrative/。找出：

• 所有带源文本的对白行（键名匹配 dialogue.*）
• 已录制的对白行（assets/audio/vo/ 中存在音频文件）
• 尚未录制的对白行

输出录音清单：

## VO Recording Manifest — [Date]

| Key | Character | Source Line | Status |
|-----|-----------|-------------|--------|
| dialogue.npc.merchant.greeting | Merchant | "Welcome, traveller." | Recorded |
| dialogue.npc.merchant.haggle | Merchant | "That's my final offer." | Needs recording |

VO 流程：脚本

为每个角色生成录音脚本文档，并按场景分组。包括：

• 角色姓名和简短的性格说明
• 完整对白，以及不常见专有名词的发音指南
• 每句台词的情绪／指导说明（[温暖、热情]、[恼怒、简短]）
• 对话中的应答台词（提供上下文：“玩家刚刚说了 X”）

询问：“我可以将 VO 录音脚本写入 production/localization/vo-scripts-[locale]-[date].md 吗？”

VO 流程：验证

遍历 assets/audio/vo/[locale]/ 中所有 .wav／.ogg 文件。与 VO 清单交叉核对。报告：

• 缺失文件（脚本中有台词，但没有对应音频文件）
• 多余文件（存在音频文件，但没有匹配的字符串键）
• 命名规范违规

VO 流程：集成

在代码根目录中搜索 VO 音频引用。验证每个引用的路径是否存在于 assets/audio/vo/[locale]/ 中。报告失效引用。

---

阶段 2H：RTL 检查模式

从右向左书写的语言（阿拉伯语、希伯来语、波斯语、乌尔都语）除了翻译文本外，还需要镜像布局。此模式用于验证实现。

确定引擎：从 project.yaml 中读取 engine.name；如果该键缺失或为空（包括 project.yaml 中没有 engine: 块的情况），则回退到 .claude/docs/technical-preferences.md。然后检查：

布局镜像

• 引擎是否启用了 RTL 布局？（Godot：Control.layout_direction，Unity：RTL Support package，Unreal：文本方向标志）
• 所有 UI 容器是否都设置为自动镜像，还是位置采用了硬编码？
• 进度条、生命值条和方向指示器是否正确镜像？

文本渲染

• 是否加载了支持阿拉伯语／希伯来语字符集的字体？
• 阿拉伯语文本是否正确呈现连字（字母相连的书写形式）？
• 是否按要求以东阿拉伯数字显示数字？

字符串拼接

• 是否存在假设文本阅读顺序为从左到右的字符串拼接？
• 句子结构反转时，句中的 {placeholder} 位置是否正确？

资源审查

• 是否存在带方向箭头或非对称设计、需要制作镜像版本的 UI 图标？
• 是否存在需要制作 RTL 版本的图像内文字资源？

要检查的 Grep 模式：

• 场景／预制件文件中的引擎专用 RTL 标志
• 所有 HBoxContainer、LinearLayout、HorizontalBox 节点——验证其 layout_direction 设置
• 对话或 UI 代码附近使用 + 的字符串拼接

报告检查结果。将问题分为 BLOCKING（不修复则内容无法阅读）和 ADVISORY（外观改进建议）。

询问：“我可以将此 RTL 检查报告写入 production/localization/rtl-check-[date].md 吗？”

---

阶段 2I：冻结模式

字符串冻结会锁定源（英语）字符串表，使翻译人员能够在源文本不发生变化的情况下开展翻译工作。

freeze call

检查 production/localization/freeze-status.md 中当前的 freeze 状态（如果该文件存在）。

如果已冻结：

“字符串冻结当前为 ACTIVE（调用日期：[date]）。自冻结以来，新增或修改了 [N] 条字符串。这些属于违反冻结的情况，必须重新翻译，或获得批准后解除冻结。”

如果未冻结，请展示冻结前检查清单：

Pre-Freeze Checklist
[ ] All planned UI screens are implemented
[ ] All dialogue lines are final (no further narrative revisions planned)
[ ] All system strings (error messages, tutorial text) are complete
[ ] /localize scan shows zero hardcoded strings
[ ] /localize validate shows no placeholder mismatches in source (en)
[ ] Marketing strings (store description, achievements) are final

使用 AskUserQuestion：

• 提示：“现在调用字符串冻结吗？这会写入 production/localization/freeze-status.md（Status: ACTIVE）并锁定源表。”
• 选项：[A] 是 — 现在调用字符串冻结 / [B] 否 — 我还有字符串要添加

如果选择 [A]：写入 production/localization/freeze-status.md：

# String Freeze Status

**Status**: ACTIVE
**Called**: [date]
**Called by**: [user]
**Total strings at freeze**: [N]

## Post-Freeze Changes
[Any strings added or modified after freeze are listed here automatically by /localize extract]

freeze lift

如果参数包含 lift：询问“我可以将 freeze-status.md 更新为 LIFTED 吗？”，然后将其 Status 设置为 LIFTED，并记录原因和日期。警告：“解除冻结后，所有已修改的字符串都必须重新翻译。请通知翻译团队。”

freeze check（自动集成到 extract）

当 extract 模式发现新增或修改的字符串，且 freeze-status.md 显示 Status: ACTIVE 时——在 extract 自己的“May I write”问题中提及 freeze-status.md，获批后将新键追加到其中的 ## Post-Freeze Changes，并警告：

“⚠️ 字符串冻结已生效。已新增或修改 [N] 条字符串。这些属于违反冻结的情况。继续之前，请通知本地化供应商。”

---

Phase 2J：QA 模式

本地化 QA 是一项专门的检查，应在交付翻译后、任何语言版本发布前进行。这不同于 /localize validate（用于检查完整性），而是一项基于流程实测的结构化质量检查。

通过 Agent 启动 localization-lead，并提供：

• 要进行 QA 的目标语言
• 游戏中所有屏幕/流程的列表（来自 design/gdd/ 或 /content-audit 输出）
• 当前的 /localize validate 报告
• 文化审查报告（如果存在）

请 localization-lead 制定一份 QA 计划，涵盖：

1. 功能性字符串检查 — 每条字符串都能在游戏中显示，且没有截断、占位符错误或编码损坏
2. UI 溢出检查 — 检查超出 UI 边界的译文（即使未超出字符数限制，有些语言的译文也会变长）
3. 上下文准确性 — 在游戏中抽查 10% 的字符串，检查翻译准确性和表达自然度
4. 文化审查事项 — 确认文化审查中所有 BLOCKING 项均已解决
5. VO 同步检查 — 如果存在 VO，确认翻译后口型同步或字幕时序可接受
6. 平台认证要求 — 检查平台特定的本地化要求（年龄分级文本、法律声明、ESRB/PEGI/CERO 文本）

按语言输出 QA 结论：

## Localization QA Verdict — [Locale]

**Status**: PASS / PASS WITH CONDITIONS / NOT ASSESSED / FAIL
**Reviewed by**: localization-lead
**Date**: [date]

### Findings
| ID | Area | Description | Severity | Status |
|----|------|-------------|----------|--------|
| LOC-001 | UI Overflow | "Settings" button text overflows on [Screen] | BLOCKING | Open |
| LOC-002 | Translation | [Key] translation is literal — sounds unnatural | ADVISORY | Open |

### Conditions (if PASS WITH CONDITIONS)
- [Condition 1 — must resolve before ship]

### Sign-Off
[ ] All BLOCKING findings resolved
[ ] Producer approves shipping [Locale]

按以下优先级判断，先匹配者为准：如果有任何 BLOCKING 问题尚未解决，则为 FAIL；否则，如果某项检查无法执行，则为 NOT ASSESSED——这些检查基于流程实测，因此，未有人在游戏中体验过的语言版本（或尚未交付译文的语言版本）不能仅凭字符串表通过；请列出每项未执行的检查；否则，如果仍有待处理条件，则为 PASS WITH CONDITIONS；否则为 PASS。NOT ASSESSED 的优先级高于两种通过结论——未经实测的语言版本尚未通过——但低于 FAIL，因此未解决的 BLOCKING 问题绝不会被其掩盖。

询问：“我可以将此本地化 QA 报告写入 production/localization/loc-qa-[locale]-[date].md 吗？”

关卡集成：在 workflow: full 下，Polish → Release 关卡要求每个即将发布的已翻译语言版本均获得 PASS 或 PASS WITH CONDITIONS 结论（建议在 standard 下执行；在 minimal 下不执行）。某个语言版本的 FAIL 只会阻止该语言版本发布——如果其他语言版本的 QA 通过，它们仍可继续发布。NOT ASSESSED 表示该语言版本尚未通过：其 QA 尚未执行。

---

Phase 3：规则与后续步骤

规则

• 始终使用英语（en）作为源语言区域设置
• 每个字符串表条目都必须包含 context 字段，注明译者说明、字符限制和占位符含义
• 切勿直接修改翻译文件——应生成差异供审核
• 必须按 UI 元素定义字符限制，并在验证模式下强制执行
• 将字符串发送给译者之前，必须调用字符串冻结——切勿翻译仍在变动的内容
• 必须从一开始就设计 RTL 支持——事后改造 RTL 布局的成本很高
• 对于游戏将以商业形式发行的任何语言区域，都必须进行文化审核
• VO 脚本必须包含导演说明——只有原始对白会导致录音效果平淡

推荐工作流

/localize scan            → find hardcoded strings
/localize extract         → build string table
/localize freeze          → lock source before sending to translators
/localize brief           → generate translator briefing document
[Send to translators]
/localize validate        → check returned translations
/localize cultural-review → flag culturally sensitive content
/localize rtl-check       → if shipping Arabic / Hebrew / Persian
/localize vo-pipeline     → if shipping dubbed VO
/localize qa              → full localization QA pass

在 qa 对每个准备发布的已翻译语言区域返回 PASS 或 PASS WITH CONDITIONS 后，运行 /gate-check release 时，请附上 QA 报告路径。