readme-i18n

在不破坏仓库相关机制的前提下，本地化仓库的 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 时保留结构

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

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

翻译标题后，GitHub 会生成不同的标题 ID。翻译标题后：

• 重写所有指向同一文件的 (#...) 链接，使其匹配该文件中的本地化标题 slug
• 保留自定义显式锚点，例如 <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.md 作为规范源文件。源 README 后续发生变更时，通过比较差异更新每个本地化同级文件中的变更文案，然后重新检查选择器、文件名和锚点链接，而不是从头重新排版整个文件。

示例提示

示例 1

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

示例 2

让仓库支持多种语言。添加西班牙语和中文 README 版本，确保内部锚点链接有效，并将选择器添加到每个文件中。

示例 3

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

常见错误

• 翻译围栏代码块或行内代码，而不是只翻译其周围的文案
• 重复添加语言选择器，而不是更新现有选择器
• 翻译标题后忘记重写指向同一文件的 (#...) 链接
• 翻译可见标签时更改了徽章 URL 或图片源
• 本地化 README 时调整了章节顺序，尽管源 README 才是权威版本