一、翻译与国际化Skill的设计
翻译与国际化Skill是一种专为自动化处理多语言翻译和国际化配置而设计的AI能力模块。它能够自动完成代码注释、技术文档、UI文本的翻译工作，同时支持生成和维护国际化配置文件（如JSON、YAML、PO等），确保多语言项目中的翻译一致性和术语统一性。
该Skill的核心价值在于帮助开发者摆脱繁琐的手工翻译工作，让AI自动识别源代码中的待翻译文本，调用翻译引擎进行处理，并生成符合目标语言习惯和项目规范的翻译结果。无论是个人开源项目还是企业级国际化产品，翻译与国际化Skill都能显著提升本地化效率。
多语言双向翻译
支持中文↔英文、中↔日、中↔韩等多语言方向，覆盖主流编程语言和技术文档场景。
格式感知翻译
智能识别代码块、模板语法、占位符和标记语言，仅翻译文本内容，保留技术格式不变。
术语一致性管理
基于术语表和翻译记忆，确保相同技术概念在全文翻译中保持翻译一致。
i18n文件自动化
自动读取源码提取待翻译键值对，生成多语言国际化文件（JSON/YAML/PO/Properties）。
设计理念：翻译与国际化Skill遵循"一次配置，多语言输出"的原则。开发者只需定义好源语言文本和术语规则，Skill即可自动完成从文本提取、翻译到文件生成的全流程。目标是在保证翻译质量的前提下，将国际化的工作量降低80%以上。
1.1 Skill的核心能力矩阵
| 能力维度 |
具体功能 |
适用场景 |
| 文本翻译 |
代码注释、文档、UI文本、错误消息 |
开源项目本地化、文档国际化 |
| 文件格式转换 |
JSON/YAML/PO/Properties/Markdown |
前端i18n、后端国际化配置 |
| 术语管理 |
术语表建立、一致性检查、偏差识别 |
技术文档翻译、API文档本地化 |
| 质量控制 |
格式校验、占位符完整性、上下文感知 |
生产环境国际化发布前检查 |
使用建议：在项目初期就将翻译与国际化Skill纳入CI/CD流程。每次代码提交后自动触发翻译更新，可以避免积压大量待翻译文本，确保国际化与功能开发同步推进。
二、代码注释和文档翻译
代码注释和文档翻译是翻译与国际化Skill最基础也是最核心的功能之一。它能够自动识别源代码中的注释块（支持单行注释//、多行注释/* */、文档注释///、以及脚本语言中的#注释），在保持代码结构不变的前提下，将注释内容准确翻译为目标语言。
对于README、API文档、CHANGELOG等技术文档，Skill能够解析Markdown、reStructuredText、AsciiDoc等常见文档格式，翻译正文内容的同时完整保留标题层级、列表结构、代码块和超链接等格式标记。
2.1 注释翻译示例
原始代码（Python）：
# Calculate the weighted average of the input array
# Parameters:
# data - list of numerical values
# weights - list of weight coefficients
# Returns:
# float - the weighted average result
def weighted_average(data, weights):
if len(data) != len(weights):
raise ValueError("data and weights must have the same length")
return sum(d * w for d, w in zip(data, weights)) / sum(weights)
翻译后代码（注释变为中文）：
# 计算输入数组的加权平均值
# 参数：
# data - 数值列表
# weights - 权重系数列表
# 返回：
# float - 加权平均值结果
def weighted_average(data, weights):
if len(data) != len(weights):
raise ValueError("data and weights must have the same length")
return sum(d * w for d, w in zip(data, weights)) / sum(weights)
关键原则：代码注释翻译遵循"保留功能说明准确性"为第一优先级的策略。技术术语（如"weighted average"）使用行业标准译名（"加权平均值"），函数签名和类型标注保持原文不变，仅翻译注释中的描述性文本。错误消息字符串在UI场景下可以翻译，但在API场景下建议保留英文以保持与生态一致性。
2.2 多语言注释格式支持
| 语言 |
单行注释 |
多行注释 |
文档注释 |
| JavaScript / TypeScript / Java / C# / C / C++ |
// |
/* */ |
/** */ (JSDoc) |
| Python |
# |
""" """ |
""" (docstring) |
| Ruby |
# |
=begin =end |
# (YARD) |
| Go |
// |
/* */ |
// (go doc) |
| Rust |
// |
/* */ |
///、//! (rustdoc) |
| Shell / Bash / Python (script) |
# |
: ' ' (heredoc) |
# (无标准) |
2.3 文档翻译格式保留策略
# My Project
[](https://example.com)
## Installation
```bash
npm install my-project
```
## Usage
```javascript
import { translate } from 'my-project';
// Translate Chinese to English
const result = await translate('你好，世界', { from: 'zh', to: 'en' });
console.log(result); // Hello, World
```
> **Note:** The API key is required for production use.
在翻译上述文档时，Skill会执行以下操作：
- 保留标题层级：#、##、### 等标题标记和层级关系不变
- 保留代码块：``` 包裹的代码块及其内容完全不翻译
- 保留行内代码：`translate` 这样的行内代码标记不翻译
- 保留链接：[]() 格式的 Markdown 链接文本翻译但URL不翻译
- 保留徽章： 图片徽章文本翻译但URL和样式不翻译
- 保留引用块：> 引用块符号保留，内部文本翻译
注意事项：翻译文档时需特别留意占位符变量（如${name}、%s、{0}等）和模板语法（如{{ variable }}）。这些元素必须原封不动保留在译文中，否则会导致程序运行错误。翻译与国际化Skill应当自动检测并保护这些特殊语法结构。
三、i18n国际化文件生成
i18n国际化文件生成是翻译与国际化Skill的高级功能，专门用于处理前端框架、后端应用和库项目的多语言资源配置。Skill能够读取源代码中待翻译的文本内容，自动提取生成键值对结构，并为每种目标语言生成对应的翻译文件。
该功能支持主流的国际化格式和框架，包括但不限于：Vue I18n（JSON格式）、React Intl / FormatJS（JSON）、GNU gettext（PO/POT格式）、Ruby I18n（YAML格式）、Java ResourceBundle（Properties格式）、 iOS/macOS本地化（Strings格式）等。
3.1 JSON国际化文件生成
源语言文件（zh-CN.json）：
{
"app.title": "项目管理工具",
"app.description": "高效管理您的项目和团队任务",
"nav.dashboard": "仪表盘",
"nav.projects": "项目列表",
"nav.settings": "系统设置",
"common.save": "保存",
"common.cancel": "取消",
"common.delete": "删除",
"common.confirm": "确认",
"message.welcome": "欢迎回来，{username}！",
"message.project_count": "您有 {count} 个项目正在进行中",
"error.required": "此字段为必填项",
"error.invalid_email": "请输入有效的邮箱地址"
}
生成的英文翻译文件（en.json）：
{
"app.title": "Project Management Tool",
"app.description": "Efficiently manage your projects and team tasks",
"nav.dashboard": "Dashboard",
"nav.projects": "Projects",
"nav.settings": "Settings",
"common.save": "Save",
"common.cancel": "Cancel",
"common.delete": "Delete",
"common.confirm": "Confirm",
"message.welcome": "Welcome back, {username}!",
"message.project_count": "You have {count} projects in progress",
"error.required": "This field is required",
"error.invalid_email": "Please enter a valid email address"
}
复数形式处理：Skill支持不同语言的复数规则。中文中"{count} 个项目"既可表示单数也可表示复数；但英文需要区分单复数形式，自动生成 "You have {count} project" 和 "You have {count} projects" 两条翻译，或使用支持复数选择器的 ICU MessageFormat 语法：{count, plural, one {You have # project} other {You have # projects}}。
3.2 PO/POT 格式生成
GNU gettext 格式在 C/C++、PHP、Python 项目中广泛应用。Skill可以读取源码中的 gettext 调用并生成标准的 POT 模板文件和各语言的 PO 翻译文件。
#: src/controllers/user.php:42
#: src/views/profile.php:15
msgid "User registration successful"
msgstr "用户注册成功"
#: src/controllers/order.php:88
#, c-format
msgid "Order total: %s"
msgstr "订单总额：%s"
#: src/views/welcome.php:5
msgid "Welcome, %s!"
msgstr_plural "Welcome, %s!"
msgstr[0] "欢迎，%s！"
msgstr[1] "欢迎，%s们！"
3.3 YAML国际化文件生成
YAML格式在 Ruby on Rails、Python Django 以及部分静态站点生成器中广泛使用。
zh-CN:
site:
title: 我的博客
tagline: 分享技术与生活
posts:
recent: 最新文章
popular: 热门推荐
comments:
zero: 暂无评论
one: 共 1 条评论
other: 共 %{count} 条评论
footer:
copyright: "© 2026 版权所有"
contact: 联系我们
格式互转能力：Skill支持在JSON、YAML、PO三种格式之间进行互转。例如，当项目从 Vue I18n 迁移到 React Intl 时，只需指定源格式和目标格式，Skill即可自动完成配置文件的格式转换，无需手动重写整套国际化文件。
3.4 提取翻译键值的工作流程
Skill的自动化提取流程共分为五个步骤：
- 源码扫描：遍历项目目录，识别所有包含待翻译文本的文件（支持按扩展名过滤）。
- 文本提取：根据框架规则提取键值对。例如在 Vue 中识别 $t('key') 和 {{ $t('key') }}，在 React 中识别 intl.formatMessage({ id: 'key' })。
- 去重合并：将同一键名在多个文件中出现的情况合并为一个条目，确保翻译量最小化。
- 批量翻译：对提取的所有键值进行批量翻译，利用术语表确保翻译一致性。
- 文件生成：根据目标语言数量，生成对应数量的国际化配置文件，保持键结构完整。
上下文感知翻译：Skill在翻译时会收集键名所在文件的路径、相邻代码、注释说明等上下文信息，传递给翻译引擎以获得更准确的翻译结果。例如，"run"在CI配置上下文中应译为"运行"，而在运动类应用上下文中应译为"跑步"。上下文信息是消除这种歧义的关键。
四、翻译一致性管理
翻译一致性是国际化项目中最大的挑战之一。同一个术语在不同文件、不同页面甚至同一页面的不同位置出现时，必须使用完全相同的译名。翻译与国际化Skill通过内置的术语表管理和一致性检查机制，从根本上解决了这个问题。
一致性管理涵盖三个层面：术语级一致性（同一术语始终使用相同译名）、文件级一致性（同一键名在不同文件中翻译一致）、项目级一致性（整个项目遵循统一的翻译风格和规范）。
4.1 术语表管理
术语表是翻译一致性的基石。Skill支持在项目根目录创建术语表文件（terminology.json），定义核心术语的标准翻译。
{
"version": "1.0",
"language_pair": {
"source": "zh-CN",
"target": "en-US"
},
"terms": [
{
"source": "用户",
"target": "User",
"category": "通用",
"note": "系统用户，保持首字母大写",
"status": "confirmed"
},
{
"source": "订单",
"target": "Order",
"category": "电商",
"note": "特指购物订单",
"status": "confirmed"
},
{
"source": "支付",
"target": "Payment",
"category": "金融",
"alternative": ["Checkout", "Settlement"],
"note": "支付流程中的统一术语",
"status": "confirmed"
},
{
"source": "数据源",
"target": "Data Source",
"category": "技术",
"note": "两个单词，中间有空格",
"status": "confirmed"
},
{
"source": "部署",
"target": "Deploy",
"category": "DevOps",
"alternative": ["Deployment"],
"note": "动词时用Deploy，名词时用Deployment",
"status": "confirmed"
}
]
}
术语表生命周期管理：术语表不是一次创建就固定不变的。翻译与国际化Skill支持术语表的版本控制和持续更新。当项目新增功能领域时，可以往术语表中添加新术语；当发现现有译名不符合行业惯例时，可以更新术语表并触发对历史翻译的重新审核。每次术语表变更都应记录变更日志，便于追溯。
4.2 一致性检查流程
Skill在执行翻译一致性检查时，会按照以下步骤自动完成质量审核：
| 检查项 |
说明 |
违规处理 |
| 术语一致性 |
检查译文中术语是否与术语表定义一致 |
自动替换为标准译名，标记原译文 |
| 跨文件一致性 |
同一键名在不同文件中的翻译是否一致 |
统一为出现次数最多的译法，报告冲突 |
| 占位符完整性 |
译文中是否保留了所有占位符变量 |
自动补全缺失占位符，标记为需人工审核 |
| 格式标记保留 |
HTML标签、Markdown标记是否完整 |
自动修复标记缺失，报告格式问题 |
| 情感色彩匹配 |
原文和译文的语气正式程度是否匹配 |
调整词汇选择，确保风格一致 |
4.3 偏差检测与修复
当Skill检测到翻译偏差时，会生成详细的差异报告，帮助开发者快速定位问题。
翻译一致性检查报告
======================
项目：my-i18n-app
检查时间：2026-05-08 09:31:38
源语言：zh-CN
目标语言：en-US
[警告] 术语不一致 (3处)
- "用户" → 当前译为"Customer"，术语表要求"User"
文件：src/locales/en-US/user-profile.json:12
文件：src/locales/en-US/order-history.json:35
- "数据源" → 当前译为"Datasource"，术语表要求"Data Source"
文件：src/locales/en-US/admin-settings.json:78
[错误] 占位符缺失 (1处)
- 键名：message.welcome
原文：欢迎回来，{username}！
当前译文：Welcome back!
问题：缺少 {username} 占位符
建议修复：Welcome back, {username}!
[注意] 跨文件不一致 (2处)
- "common.save"
- 文件 A: "Save"
- 文件 B: "Store"
- 建议统一为："Save"
检查结论：通过 245 / 251 项，6项需处理
建议：自动修复 4 项，2 项需人工审核
最佳实践：建议在项目的CI/CD流水线中加入翻译一致性检查步骤。每次构建时自动运行一致性检查，如果发现严重问题（如占位符缺失、术语冲突）则构建失败，强制开发者在合并代码前修复。这种方式可以将翻译质量问题拦截在开发阶段，避免有问题的翻译部署到生产环境。
4.4 语境感知与翻译风格调整
翻译一致性不仅仅是术语层面的统一，还包括翻译风格的协调。Skill支持根据文档类型和使用场景自动调整翻译的正式程度：
- 技术文档/API文档：使用正式规范的术语，避免口语化表达，保持客观中性的语气。
- UI界面/交互文本：使用简洁明了的表达，按钮和提示文字尽量简短，符合用户界面设计规范。
- 错误消息/日志输出：保持信息完整性和清晰度，避免歧义，辅助开发者快速定位问题。
- 市场营销内容/公告：在保证准确性的前提下，可适当采用更有感染力的表达方式。
- 代码注释/开发文档：技术术语优先，解释性内容可以适当展开，以帮助开发人员理解为目的。
风格冲突处理：当同一术语在不同文档类型中需要不同处理时（例如，"delete"在UI按钮上译为"删除"，在日志文本中译为"已删除"），术语表可以定义多语境翻译条目，Skill根据检测到的文档类型自动选择最合适的翻译版本，而不是强制全项目统一。
4.5 批量更新与历史翻译重译
当术语表发生变更时，Skill支持对项目中的历史翻译进行批量重译。具体流程为：
- 检测到术语表中有术语的翻译发生了变更
- 扫描项目所有国际化文件，定位包含旧译名的条目
- 将这些条目标记为"待更新"，生成变更差异清单
- 按照变更清单逐一替换旧译名为新译名
- 生成翻译更新报告，列出所有修改的文件和条目数量
这一机制确保了在整个项目的生命周期中，翻译的一致性不会因为术语表的进化而遭到破坏。开发者可以放心地优化术语表，而无需担心产生碎片化的不一致翻译。