readme-i18n

name: readme-i18n
description: 用于以下情况：用户想要翻译仓库README、使仓库支持多语言、本地化文档、添加语言切换器、国际化README或更新GitHub风格仓库中的本地化README变体。

将仓库 README.md 本地化，同时不破坏其周围的仓库机制。

默认任务为翻译 + 链接整合：

• 读取作为事实来源的 README
• 创建本地化的姊妹文件，例如 README.zh.md
• 保留 GitHub 风格的 Markdown 结构和仓库特定的标记
• 在每个变体的顶部附近添加或更新共享的语言选择器

此技能适用于多语言 README 工作流，不适用于通用网站/应用的国际化（i18n）。

输入

在可用时应接受以下输入：

• 来源 README 路径，默认 README.md
• 源语言，默认推断或英语
• 一个或多个目标语言
• 可选的术语表或禁止翻译列表
• 可选的文件名覆盖，如果仓库已使用不同的多语言命名模式

如果未指定目标语言，则检查现有的翻译文件、选择器、文件名、问题或之前的仓库惯例。如果仍然无法明确目标语言，则询问一次。不要凭空发明目标语言。

默认值和决策规则

• 除非用户明确说明，否则将根目录 README.md 视为事实来源。
• 如果源语言不明确，询问一次。否则默认为英语。
• 保持与来源 README 相同的章节顺序。仅在需要生成有效的本地化锚点时，对标题措辞进行小幅调整。
• 使用 README.<bcp47-tag>.md 命名方式输出本地化姊妹文件，除非仓库已有不同的既定模式需要保留。
• 更新已有的语言选择器，不要重复添加。
• 仅翻译人类语言内容。
• 保留项目名称、包名、命令、CLI 标志、选项名、环境变量、URL、文件路径、内联代码、代码围栏、HTML 属性以及徽章/图片 URL。
• 徽章替代文本或可见标签仅在不需要更改徽章 URL、查询参数或图片来源的情况下才可翻译。
• 如果提供了术语表或禁止翻译列表，则应对每种目标语言一致地应用。

工作流

1. 确定来源 README 和语言

• 确认来源 README 路径。默认使用 README.md。
• 根据文件内容和仓库上下文确定源语言。
• 根据请求或现有仓库模式确定目标语言。
• 记录必须保持未翻译的术语表项、产品名称或短语。

2. 翻译前审计 Markdown 结构

将来源 README 视为结构而非散文阅读。打开 references/preservation-checklist.md 并清点最可能被破坏的元素：

• 标题及标题级别
• 徽章行、Shields URL 和图片链接
• 表格及对齐行
• 原始 HTML 块和内联 HTML
• GitHub 警告或提示块，例如 > [!NOTE]
• 代码围栏、内联代码、命令和配置片段
• 文档内锚点，例如 (#installation)
• 指向文件、文档、截图或其他 README 变体的相对链接

如果 README 已有本地化姊妹文件，在选择文件名或选择器样式前也要检查它们。

3. 仅翻译散文层

翻译：

• 段落文本
• 列表项散文
• 表格单元格散文
• HTML 块内的可见文本
• 安全的图片替代文本
• 选择器标签及其他面向人类的标签

不翻译：

• 围栏代码块
• 内联代码跨度
• shell 命令
• 标志，例如 --help
• 环境变量，例如 OPENAI_API_KEY
• URL
• 文件路径
• 仓库/包/项目标识符
• 徽章和图片 URL

如有疑问，保留文字标记，转而翻译周围的句子。

4. 编写本地化 README 时保持结构

• 保持与来源 README 相同的标题层级和章节顺序。
• 保持相同数量的代码围栏，除非用户明确要求重写示例。
• 保留表格形状、列表嵌套、HTML 包装器和 Markdown 注释。
• 保留相对链接，除非链接有意指向本地化的姊妹 README。

5. 重写本地化锚点和依赖锚点的链接

当翻译后的标题发生变化时，GitHub 会生成不同的标题 ID。翻译标题后：

• 重写每个同文件内的 (#...) 链接，使其匹配该文件中本地化的标题片段
• 保留自定义显式锚点，例如 <a id="...">，除非文件已使用本地化的显式 ID
• 确保每个文档内锚点目标都指向现有的标题或显式锚点

优先对标题措辞进行小幅调整，而不是破坏锚点。章节顺序仍应与来源 README 一致。

6. 使用仓库的命名模式编写姊妹文件

默认使用如下姊妹文件名：

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

如果仓库已使用不同的多语言命名模式，则保持一致地使用该模式，而不是强制使用默认模式。

7. 插入或更新语言选择器

在编辑选择器之前，打开 references/language-selector-reference.md。

放置位置：

• 将选择器放在文件顶部附近
• 如果 README 以标题、徽章、英雄图片或简短介绍块开头，则将选择器紧接在该开头簇之后

行为：

• 如果已有选择器块，则原地更新
• 如果添加新选择器，则使用参考文件中的规范标记注释，以便后续运行可以确定性地更新
• 强调当前语言并链接其他变体
• 保持每个 README 变体中选择器的顺序和标签一致

8. 最终验证

完成前验证：

• 本地化文件名遵循所选模式
• 每个 README 变体包含且仅包含一个选择器块
• 代码围栏数量保持不变
• 徽章/图片 URL 和相对文件链接仍指向原始目标，除非有意本地化
• 每个 (#...) 链接在其自身文件内可解析
• 本地化的 README 在结构上与来源 README 仍感觉一致

输出

生成：

• 每个目标语言一个本地化姊妹 README
• 每个 README 变体中的一个更新后的选择器块
• 向用户简要说明创建或更新的文件、任何假设以及有意保持未翻译的术语

维护说明

除非用户另有说明，否则保持 README.md 作为规范来源。当来源 README 后续更改时，通过比较更改的散文来更新每个本地化姊妹文件，然后重新检查选择器、文件名和锚点链接，而不是从头重新格式化整个文件。

示例提示

示例 1

将此 README 翻译成中文并添加语言切换器。保持徽章 URL、代码围栏和所有命令完全不变。

示例 2

使仓库多语言化。添加西班牙语和中文 README 变体，保持内部锚点链接有效，并将选择器接入每个文件。

示例 3

我们已经有 README.zh.md。添加 README.es.md 并原地更新现有选择器，而不是添加第二个。

常见错误

• 翻译围栏代码块或内联代码，而不是只翻译周围的散文
• 重复添加语言选择器，而不是更新现有块
• 翻译标题但忘记重写同文件内的 (#...) 链接
• 尝试翻译可见标签时更改徽章 URL 或图片来源
• 在本地化 README 中重新排序章节，即使来源 README 是权威