将内容本地化为指定语言环境
一种将内容本地化为给定语言环境的技能。
工作原理
该技能接收输入内容和目标语言环境列表，然后将内容翻译成每个指定的语言环境，为每个语言环境提供本地化版本。
内容结构
.
└── docs/ ← 工作坊内容（源文件 + 语言环境输出）
├── README.md ← 着陆页（源文件；slug: index）
├── <category>/ ← 英文工作坊类别
│ ├── README.md ← 类别着陆页（源文件；slug: <category>）
│ └── <workshop>/
│ ├── README.md ← 工作坊着陆页（源文件；slug: <category>/<workshop>）
│ └── *.md
├── _images/ ← 共享资源（不本地化）
└── <locale>/ ← 本地化输出，docs/ 的直接子目录
├── README.md ← 语言环境着陆页（slug: <locale>）
└── <category>/
├── README.md ← 本地化类别着陆页（slug: <locale>/<category>）
└── <workshop>/
├── README.md ← 本地化工作坊着陆页（slug: <locale>/<category>/<workshop>）
└── *.md
输入内容
以下是本地化范围内的内容：
docs/及其子目录中的所有英文 Markdown 文件——站点着陆页（docs/README.md）、类别着陆页以及工作坊课程（docs/<category>/<workshop>/**/*.md）。
不要将 _images/（共享资源）或任何已配置的语言环境根目录视为源输入。
已经位于 docs/<locale>/ 下的文件是输出，而不是输入——切勿将已配置的语言环境根目录作为需要再次本地化的源内容。
目标语言环境
目标语言环境在此技能的 rules 目录中定义为 Markdown 文件（例如 rules/ko-kr.md）。要确定需要处理哪些语言环境，请列出 rules/ 中的文件：每个 <locale>.md 文件对应一个受支持的目标语言环境。 每个语言环境都有自己的一套翻译规则和指南，确保本地化内容适合目标受众。
语言环境标识符使用小写字母加连字符（例如 ko-kr）。这是此技能中规则文件名和输出目录的标准大小写格式；请保持一致性。
输出内容
所有本地化的工作坊内容都直接存储在仓库根目录下的 docs/ 内容目录中，每个语言环境都有自己的子目录。例如，韩语内容存储在 docs/ko-kr/ 中。
语言环境目录必须是 docs/ 的直接子目录，以便 Starlight（在 website/astro.config.mjs 中配置）能够识别它们并显示语言选择器。不要添加中间的 localizations/ 目录。
本地化流程
本地化有三种情况。为了检测适用哪种情况，比较源文件树与现有的 docs/<locale>/ 树，并使用源文件的 git 历史记录来检测更改：
- 原始文件存在，但该语言环境没有本地化版本： 创建新的本地化文档。
- 原始文件和本地化版本都存在： 比较源文件树与
docs/<locale>/，然后对源文件运行git diff（或git log）以找出自上次生成本地化版本以来发生的变化。仅更新本地化文档中受影响的部分；不要不必要地重新翻译未更改的部分。 - 本地化版本存在，但原始文件已被删除： 删除孤立的本地化文档（并清理现在为空的语言环境子目录）。
该流程分两轮执行。首先，分析内容以识别关键短语和上下文。然后，“翻译者”代理执行初步本地化，随后由“评估者”代理进行审查和完善，以确保质量和一致性。
“翻译者”和“评估者”“代理”是角色/人格，而非外部工具。如果没有专用的子代理可用，则按顺序扮演这些角色：首先采用翻译者角色生成草稿，然后采用评估者角色根据语言环境规则对草稿进行评判和完善。重复完善循环，直到评估者的标准全部通过。
Markdown 和格式保留
无论语言环境如何，以下内容必须精确保留且不翻译：
- YAML frontmatter 键（仅在适当的地方翻译值，例如
title）。例外——着陆页（README.md）的slug键： 站点通过其slug路由每个文件夹的着陆页，因此本地化的着陆页必须使用语言环境前缀的 slug，而不是英文的 slug。重写它：语言环境根目录（docs/<locale>/README.md）使用slug: <locale>；本地化的类别着陆页使用slug: <locale>/<category>；本地化的工作坊着陆页使用slug: <locale>/<category>/<workshop>。切勿将英文着陆页 slug 原样复制到本地化文件中，因为那样会与英文路由冲突。 - 围栏代码和内联代码，包括变量、函数和命令名称。
- URL 和外部链接目标。
- HTML 标签、Markdown 结构、表格和警示标记。
翻译人类语言散文，包括代码块内解释性的注释（根据语言环境规则）。保持标题顺序和文档结构稳定。
标题锚点跟随本地化后的文本。 当标题被翻译时，其自动生成的锚点/slug 也会随之改变——这是预期的。要求是同文档内的锚点链接必须保持可解析：每当你翻译一个标题时，更新所有指向它的页面内链接（](#...)）为本地化后标题的新 slug。一旦标题被翻译，不要留下指向原始英文 slug 的链接，也不要保留不再匹配其标题的英文锚点。指向未本地化文件（或外部 URL）的锚点保留其原始目标。
图像和资源路径指向原始资源，除非存在本地化的资源。 由于本地化文件位于 docs/<locale>/ 下，必要时需重写相对于源文件的路径，使其仍能解析到共享资源（例如，位于 docs/<locale>/real-world-development/app/2-foo.md 的课程使用 ../../../_images/x.png 来指向 docs/_images/）。仅当语言环境树中实际存在对应的翻译图像时，才指向该本地化资源。无论哪种方式，链接必须解析到一个真实文件。
翻译者代理
使用“翻译者”代理来执行本地化。它应遵循 rules 目录中为每个目标语言环境文档定义的规则和指南。
评估者代理
使用“评估者”代理来评估本地化内容的质量。评估者检查准确性、文化相关性和整体质量，遵循 rules 目录中为目标语言环境定义的规则和指南。
评估者根据语言环境的评估者评分标准（在语言环境的 rules/<locale>.md 中定义）对本地化文档进行评分。评分标准使用两层：A 级硬性失败标准，必须得 5 分；B 级分级标准（1–5 分），必须得 4 或 5 分。仅当每个适用的 A 级标准都得 5 分且每个适用的 B 级标准都得 ≥ 4 分时，文档才算通过。如果任何一项不达标，将文档返回给翻译者并附上具体说明，重新运行翻译→评估循环，直到通过，若超过评分标准的迭代上限则上报给人工处理。
注意事项
- 务必仅对
rules目录中定义的目标语言环境（每个受支持的语言环境一个<locale>.md文件）执行本地化。不要本地化到不受支持的语言环境。 - 务必精确保留 Markdown 结构、代码、外部链接/URL 目标以及 frontmatter 键（参见 Markdown 和格式保留）。
- 务必让标题锚点跟随本地化后的标题文本，并更新同文档锚点链接以匹配新的 slug，使其保持可解析（参见 Markdown 和格式保留）。
- 务必将图像和资源路径指向原始资源（根据需要重写相对路径，使其能从
docs/<locale>/解析），除非存在对应的本地化资源（参见 Markdown 和格式保留）。 - 务必在
docs/<locale>/下镜像源目录结构。 - 切勿将已配置的语言环境根目录视为源输入。
- 切勿重新排序或重组内容；保持标题及其顺序稳定。
- 切勿翻译代码、命令或标识符；仅翻译解释性散文和代码注释。