readme-i18n

name: readme-i18n
description: 当用户想要翻译仓库README、使仓库多语言化、本地化文档、添加语言切换器、国际化README，或更新基于GitHub风格的仓库的本地化README变体时使用。

在不破坏仓库机制的前提下本地化仓库的 README.md。

默认任务为翻译 + 整合：

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

此技能适用于多语言 README 工作流，而非通用的网站/应用程序国际化。

输入

在可用时预期以下输入：

• 源 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 随后更新时，通过 diff 更改的散文来更新每个本地化兄弟文件，然后重新检查选择器、文件名和锚点链接，而不是从头重新格式化整个文件。

示例提示

示例 1

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

示例 2

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

示例 3

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

常见错误

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