readme-i18n

readme-i18n 技能概览

readme-i18n 是做什么的

readme-i18n 是一个专注于 README 国际化的技能，用来把单个 GitHub 风格的 README.md 变成一组可维护的多语言 README。它不是通用的应用本地化方案。它的核心职责是：翻译源 README、创建像 README.zh.md 这样的同级文件、保留 Markdown 结构和仓库里的各种机制，并在所有语言版本中新增或规范统一的语言切换器。

谁适合使用 readme-i18n

这个技能特别适合仓库维护者、开源贡献者，以及处理仓库文档的 AI 代理。因为实际需求往往不只是“把文字翻译出来”，而是“产出在 GitHub 上依然能正常工作的多语言 README 文件”。如果你在意 badges、链接、代码块、文件命名和语言切换器的一致性，那么 readme-i18n 会比普通翻译提示词更适合作为起点。

这个技能真正解决的问题

大多数 README 翻译失败，问题不在词汇，而在结构。用户真正需要的是一套工作流，能够：

• 把一个文件当作 source-of-truth
• 保持章节顺序一致
• 原样保留命令、路径、代码和链接机制
• 一致地更新所有语言版本
• 避免重复或失效的语言切换器

这正是 readme-i18n skill 的实际价值所在。

为什么这个技能和普通提示词不一样

readme-i18n 最大的差异在于它内置了决策逻辑。它会告诉代理哪些内容必须严格保留、什么时候应该只提一次澄清问题、如何从现有文件中推断仓库约定，以及如何就地更新现有 selector，而不是再新建一个。随附的参考文件也很利于落地使用，因为它们减少了语言切换器放置位置、以及哪些 Markdown 内容可以安全翻译这类常见猜测成本。

如何使用 readme-i18n 技能

readme-i18n 的安装方式

在你当前使用的任意 Skills 兼容环境中，从 xixu-me/skills 仓库安装这个技能即可。如果你的环境支持直接从 GitHub 安装，常见方式是：

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

如果你的环境使用其他技能管理方式，可以把仓库 URL https://github.com/xixu-me/skills/tree/main/skills/readme-i18n 作为来源参考，并从 skills/readme-i18n 加载该技能。

第一次使用前建议先看哪些文件

对于 readme-i18n，信噪比最高、最省时间的阅读顺序是：

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

这个顺序很重要。SKILL.md 说明整体工作流，selector 参考文件展示预期的区块形式和放置位置，而 preservation checklist 则明确哪些内容必须保持不变。

readme-i18n 需要什么输入

当你提供以下信息时，readme-i18n 的效果最好：

• 源 README 路径，通常是 README.md
• 源语言
• 目标语言或多个目标语言
• 术语表，或明确标注哪些词不能翻译
• 如果仓库已经做过 README 多语言，则提供现有文件命名约定

如果你没有写明目标语言，这个技能会优先检查已有的翻译文件、selector、文件名、issues 或仓库约定来推断。如果仍然无法确定语言，它应当只询问一次，而不是自行臆造目标语言。

需要先知道的默认假设

在运行 readme-i18n 之前，以下文档化默认值很实用，也值得先了解：

• 除非你另行说明，根目录的 README.md 会被视为 source-of-truth
• 如果不存在歧义，默认源语言是 English
• 章节顺序应与源文件保持一致
• 如果仓库已经有多语言命名方案，应沿用现有方案，而不是强行改成新的

这些默认值让 readme-i18n 在已有仓库里比空白翻译请求更安全。

如何写出更好的 readme-i18n 提示

一个较弱的请求是：“把我的 README 翻译成中文。”

一个更强的 readme-i18n usage 提示可以写成：

• 将 README.md 从 English 翻译为 Simplified Chinese
• 创建 README.zh.md
• 保留 commands、paths、badge URLs、code fences 和 relative links
• 在两个文件顶部添加 language selector
• 保持 heading 顺序完全一致
• 不要翻译产品名 AcmeCLI 和 env vars
• 如果发现现有命名规则，沿用该规则

这种更具体的说明会直接提升输出质量，因为它和 readme-i18n 的保留规则与 selector 规则是对齐的。

readme-i18n 的翻译工作流示例

一个实用的 readme-i18n for Translation 工作流通常是：

1. 确定 source-of-truth README。
2. 检查是否已经存在翻译版本。
3. 识别仓库的文件命名模式和当前 selector 风格。
4. 只翻译自然语言内容。
5. 原样保留代码、命令、URLs 和文件路径。
6. 在每个语言版本顶部附近新增或规范一个 selector 区块。
7. 验证所有文件中的链接、格式和一致性。

正确的思路不是“翻译文本”，而是“维护一整个 README 家族”。

语言切换器应该如何工作

这个技能里最有价值的支持文件之一，就是 selector reference。它建议在每个 README 变体顶部附近放置一个 selector 区块，通常位于标题和 badge 区域之后，并使用稳定标记：

<!-- README-I18N:START -->
<!-- README-I18N:END -->

这些标记很关键，因为后续再次运行时可以原地更新 selector。当前语言应被强调显示且不加链接；其他语言则应加上对应链接。不同语言版本里的语言顺序也应保持一致。

哪些内容必须严格保留

在这份 readme-i18n guide 里，preservation checklist 是决定是否值得采用的关键部分。实际操作中，以下内容不要翻译：

• inline code
• fenced code blocks
• commands、flags、env vars、paths
• badge URLs 和 query params
• 图片源路径
• 表格结构
• raw HTML 机制

可见的说明文字可以翻译，但支撑 README 正常工作的机制必须保留。

readme-i18n 会遵循哪些常见仓库约定

如果仓库已经使用了不同于默认值的命名方案，例如：

• README.md
• README.zh.md
• README.es.md

那么 readme-i18n 应该保留这套方案。这一点对已经做过部分本地化、在 CI 中引用过文件名，或团队贡献者已经形成命名预期的仓库尤其重要。

readme-i18n 最省时间的场景

当你遇到以下落地障碍时，readme-i18n 的价值最大：

• 你需要维护多个保持同步的本地化 README 文件
• 仓库里已经有混乱或重复的语言切换器
• 过去的翻译破坏过 Markdown 或链接
• 你希望后续更新可以重复执行，而不是一次性的手工修改

如果你只是想私下快速看懂某个 README，大致翻译一下即可，那这个技能可能比你实际需要的流程更重。

readme-i18n 技能 FAQ

readme-i18n 适合新手吗？

适合，前提是你的目标明确是 README 本地化。readme-i18n 把任务收束成了清晰的输入要求和保留规则，这比自己从零设计一套翻译工作流更容易上手。不过新手仍然需要检查输出结果，尤其是链接目标、标题层级，以及 selector 是否在所有文件中保持一致。

什么情况下应该用 readme-i18n，而不是普通翻译提示词？

当翻译后的 README 会被提交到仓库时，就应该优先考虑 readme-i18n。普通提示词很可能翻译过头、改动代码示例、弄坏 badge 链接，或者忘了维护跨文件导航。相比速度，这个技能更重视输出的正确性，因此在需要可提交结果时更合适。

readme-i18n 只能用于 GitHub 仓库吗？

它主要针对 GitHub 风格的仓库 README 和 Markdown 约定做了优化。对于其他 Git 托管平台，它依然可能有帮助，但它的假设前提更适合基于 README.md 的开源仓库，而不是完整文档站点或产品级本地化系统。

readme-i18n 能处理整套文档吗？

不能。它是一个以 README 为中心的工作流。如果你的需求是网站、应用，或整套文档的 i18n，那么 readme-i18n skill 就太窄了。它的优势在于维护一个仓库落地页文档及其各语言副本的一致性。

支持哪些语言？

这个技能对语言本身没有限制，只要你明确指定目标语言，或者仓库本身已经给出足够线索即可。它会明确避免在证据不足时自行猜测目标语言。

readme-i18n 能更新已经存在的多语言 README 吗？

可以，而且这正是它最适合的场景之一。它的设计目标就是检查已有的翻译文件和 selector，保留命名约定，并对现有切换器做规范化处理，而不是再额外加出第二套。

什么情况下 readme-i18n 不适合？

以下情况可以跳过它：

• 你只想要一个非正式的阅读译文
• 你的文档主要不在 README 中
• 你需要在大规模文档语料中做术语管理
• 你的仓库不希望在 README 文件里放语言切换链接

在这些场景里，更轻量的提示词，或更完整的文档本地化工作流，往往会更合适。

如何改进 readme-i18n 技能的使用效果

给 readme-i18n 更强的源约束

输入越明确，产出的 README 变体通常越可靠。建议提供：

• 精确的源文件路径
• 精确的目标 locale
• 明确哪些词绝不能翻译
• 语言名称优先使用的 autonyms
• 已有翻译文件应被覆盖，还是只做更新

这样可以减少最常见的失败模式：翻译本身没问题，但仓库行为不对。

为名称和技术术语提供术语表

如果你的 README 里有产品名称、CLI commands、package names 或领域术语，最好显式列出来。readme-i18n 本身已经会尽量保留字面量，但一份简短术语表仍然能显著提升标题、功能描述和示例中的一致性。

明确告诉技能哪些内容不要动

提升 readme-i18n usage 效果的一个最好方法，就是给出硬边界：

• 所有代码块保持 byte-for-byte 完全一致
• 保留 relative links
• 未经要求不要重命名文件
• 不要修改 badge targets
• 不要调整章节顺序

这些要求和 preservation checklist 高度一致，能有效防止那些“看似帮忙、实际有害”的改动。

提交前先检查 selector 的位置

一个常见输出问题是语言切换器位置别扭，或者重复出现。可以将生成结果对照 references/language-selector-reference.md，重点检查：

• 每个文件里只存在一个 selector
• 各语言版本中的位置一致
• 当前语言使用加粗而不是链接
• 链接指向真实存在的同级文件名

这是一个很小的复核步骤，但收益很高。

检查本地化标题和锚点

翻译后的标题可能改变平台根据 heading 文本自动生成 fragment ID 的行为。readme-i18n 会尽量保持标题层级不变，但你仍应在翻译后测试文内标题链接，尤其是在较长 README 中更要注意这一点。

从源文件变更出发迭代，而不是零散手改

如果你希望长期维护，最好始终把 README.md 作为 source-of-truth，并在源文件更新后重新运行 readme-i18n，而不是分别手动编辑每个本地化文件。这样更容易长期保持章节顺序、selector 内容和术语使用的一致性。

首次运行后做一次并排核对

第一次生成后，建议并排比较源文件和目标文件，重点核对：

• 章节数量是否一致
• 代码块数量是否一致
• 表格和列表结构是否一致
• 图片和 badges 是否一致
• selector 链接是否可用

相比逐句重读，这种检查更快发现结构性回归问题。

用明确的仓库约定提升后续运行稳定性

如果你的仓库使用了非标准的多语言模式，下次调用 readme-i18n 时最好直接写明。比如：

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

当仓库约定是被明确说出来，而不是靠推断时，这个技能的稳定性会高很多。