名称

i18n-key-audit

描述

当项目需要接入多语言、评审国际化文案键或排查翻译缺失与格式错乱时使用。该技能检查硬编码文案、键命名、复数规则、占位符、日期数字格式、文本膨胀与从右到左布局，输出可执行的修复清单与键值规范。适用于 Web、App、桌面端与多语言 API 的国际化改造。关键词：国际化、i18n、本地化、l10n、文案键、硬编码、翻译缺失、复数、占位符、日期格式、数字格式、RTL、文本膨胀、语言包、多语言、翻译管理。

国际化文案键审计

找出"表面翻译了、实际还是会坏"的国际化问题。

何时使用

新功能上线前需要检查国际化完整性。
接入第二种语言，发现文案缺失或错位。
翻译团队反馈占位符对不上。
需要制定文案键规范与 CI 检查。

不适用：纯文案润色；翻译质量评价（需母语审校）。

输入

源码与语言包（JSON、YAML、properties 等）。
目标语言清单，是否包含 RTL 语言。
现有键命名约定。
设计稿（用于评估文本膨胀）。

工作流

第 1 步：扫描硬编码

模板、组件、脚本中的可见字符串。
提示、错误、校验、空状态、按钮、标题、无障碍标签。
图片中的文字、PDF 模板、邮件模板。
后端返回给前端的文案。

排除：日志、内部错误码、仅开发者可见的调试信息。

第 2 步：键规范检查

按 references/key-conventions.md：

结构：模块.页面.元素，全小写，点分隔。
语义化，不以文案内容命名。
同一含义复用同一键，不复制。
数组与复数使用框架约定格式。

反例：button_text_2、text1、确定 作为键名。

第 3 步：占位符与复数

占位符命名一致：{count} 不能一处 {count} 一处 {0}。
占位符数量与含义在译文一致。
复数规则按语言处理：英语 two forms，阿拉伯语 six forms。
避免字符串拼接表达语序，改用整句模板。

反例："共" + n + "条"，日语与英语语序不同。

第 4 步：格式与布局

按 references/locale-pitfalls.md：

日期：YYYY-MM-DD 不是唯一正确写法，按 locale 格式化。
数字：千分位、小数点符号因地区而异。
货币：符号位置、小数位、ISO 代码。
姓名顺序、地址顺序、电话号码格式。
文本膨胀：德语、俄语通常比英语长 30% 以上。
RTL：镜像布局、图标方向、数字仍为 LTR。

第 5 步：缺失与冗余

缺失键：目标语言缺少源语言中的键。
冗余键：语言包中存在但代码未使用。
空译文与占位译文（复制英文未翻译）。
键顺序不一致导致 diff 噪声。

第 6 步：门禁与流程

CI 检查：键齐全、占位符匹配、无硬编码新增。
伪本地化：用加长字符测试布局。
截图回归：多语言页面截图对比。
翻译平台双向同步，避免手工改语言包。

检查清单

[ ] 用户可见文案无硬编码。
[ ] 键命名遵循统一结构且语义化。
[ ] 所有语言键集合一致，无缺失与多余。
[ ] 占位符名称与数量在各语言一致。
[ ] 复数与性别变体按语言处理。
[ ] 日期、数字、货币使用 locale 格式化。
[ ] RTL 布局与图标方向已适配。
[ ] 长文案在按钮与卡片中不截断。
[ ] 伪本地化与截图回归已通过。
[ ] CI 已配置国际化门禁。

输出模板

## 结论
可发布 / 需修复后发布

## 硬编码清单
| 文件 | 行 | 文案 | 建议键 |
| --- | --- | --- | --- |

## 键问题
| 键 | 问题 | 影响语言 | 修复 |
| --- | --- | --- | --- |

## 格式与布局
- ...

## 门禁建议
- ...

反模式

把中文直接当键名。
用拼接构造句子。
只翻译主流程，漏掉错误与空状态。
默认所有语言文本长度与英文相同。
用 toUpperCase() 处理土耳其语等特殊语言。

参考文件

references/key-conventions.md：键命名与结构规范。
references/locale-pitfalls.md：日期、数字、RTL 与文本膨胀陷阱。