GitHub Copilot 指令文档本地化指南：基于 awesome-copilot 的 Markdown 本地化规范与实践

GitHub Copilot 指令文档本地化指南：基于 awesome-copilot 的 Markdown 本地化规范与实践

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

本篇技术指南围绕 localization.instructions.md 这一社区指令文档展开，系统讲解在 GitHub Copilot 工作区中对 Markdown 技术文档进行本地化（Localization）的标准流程：包括 locale 目录与命名规范、翻译完整性校验、图片与文档链接的处理策略，以及免责声明的强制要求。读完本文，你将掌握一套可直接执行的"查找全部 Markdown → 翻译 → 落盘到localization/{{locale}}→ 行数比对 → 追加免责声明"的完整本地化工作流，并能结合仓库内日语、韩语指令文件实例理解其落地形态。

文档定位与适用场景

instructions/localization.instructions.md是 awesome-copilot 仓库中一条面向Copilot 本身的自定义指令（Custom Instruction）。它与其他指令文件一样，通过 YAML frontmatter 声明元信息：

--- description: 'Guidelines for localizing markdown documents' applyTo: '**/*.md' ---

• description：一句话说明本指令的用途——为 Markdown 文档本地化提供指导。
• applyTo：'**/*.md'，表示该指令对工作区内所有 Markdown 文件生效，一旦装入工作区，Copilot 在遇到 .md 文件处理任务时就会自动遵循其中的规则。

根据 instructions.instructions.md 的说明，指令文件的典型用法是复制到工作区的.github/copilot-instructions.md，或放在.github/instructions/目录下，安装后即自动作用于 Copilot 行为。因此，这条本地化指令适合文档维护者、开源项目翻译贡献者在需要把一批英文 Markdown 技术文档翻译为指定语言时，要求 Copilot 以"本地化专家"身份执行任务。

核心规则总览

原文档将本地化任务定义为一条由若干硬性规则组成的流程，任何一步都不能省略：

1. 找出工作区内所有 Markdown 文档，并将其本地化到给定的目标语言（locale）。
2. 所有本地化产物必须统一放置在localization/{{locale}}目录下。
3. locale 命名必须遵循{{language code}}-{{region code}}格式。
4. 原文档中的每一个章节、每一个段落都必须被翻译，不得遗漏任何部分。
5. 图片链接默认指向原始图片，文档链接默认指向本地化后的文档（外部链接除外）。
6. 翻译完成后，必须与原文比对结果，尤其是行数；行数不一致即说明存在缺失，需逐行复查修正。
7. 每个本地化文档末尾必须追加免责声明，且免责声明本身也要被本地化，其中的链接始终指向 issue 页面。

目录结构与 locale 命名规范

统一输出目录

所有本地化文档都应放入localization/{{locale}}目录，而不是散落在原文旁边或随意新建目录。这一约定保证了多语言产物的可发现性与可维护性：

localization/ └── {{locale}}/ ├── guide.md ├── api-reference.md └── ...

locale 格式：语言代码 + 区域代码

locale 的格式固定为{{language code}}-{{region code}}：

• 语言代码（language code）：依据 ISO 639-1 标准，如en、fr、ja、ko、pt、zh；
• 区域代码（region code）：依据 ISO 3166 标准（两位大写国家/地区代码），如US、CA、JP、KR、BR、CN。

原文档给出的合法示例：

注意：是language-region（如zh-cn、pt-br）这种带连字符的双段格式，而非单一语言代码（如zh或pt），也不是大小写混用的pt-BR。目录名应与 locale 名完全一致，例如localization/ja-jp/、localization/zh-cn/。

翻译完整性：不遗漏任何章节与段落

这是本地化质量的生命线。原文档明确要求：

• 本地化原文档中的全部章节和全部段落；
• 在本地化过程中不得遗漏任何章节、任何段落（DO NOT miss any sections nor any paragraphs）。

AI 翻译常见的失败模式是"偷工减料"：长文档翻译到一半就压缩、合并、跳段。为对抗这一点，原文档给出了一个极具操作性的校验手段——行数比对：

本地化完成后，始终将结果与原文比较，尤其是行数。如果每个结果的行数与原文不同，则必然存在缺失的章节或段落，应逐行复查并修正。

在命令行中可以这样快速完成行数校验：

# 原文行数 wc -l docs/guide.md # 本地化产物行数 wc -l localization/zh-cn/guide.md

当两者行数不一致时，逐行（line-by-line）对照原文复查：定位缺失的标题、列表项、代码块或表格行，补齐后再重新比对。这一"行数即完整性指标"的策略，把"翻译是否完整"从主观判断变成了可量化的客观检查。

链接处理策略：图片与文档链接

本地化不是简单地把正文文字换成另一种语言，文档内的引用关系同样需要正确处理。原文档给出了两条对应规则：

• 图片指向原文：图片资源通常不随语言变化（架构图、截图等），因此本地化文档中的图片应继续引用原始图片路径，避免复制图片或制造失效链接；
• 文档链接指向本地化版本：当文档 A 链接到同仓库的文档 B 时，在本地化版本文档中应将该链接改写为 B 的本地化版本（例如docs/guide.md→localization/zh-cn/guide.md），保证读者在目标语言环境中"点哪里都通"；
• 外部链接保持原样：指向仓库之外的绝对 URL（如官方文档、规范标准）无需改写，直接保留。

免责声明：每个本地化文档的强制结尾

本地化文档是机器翻译产物，原文档要求在每个本地化文档的末尾追加免责声明，其标准模板如下：

--- **DISCLAIMER**: This document is the localized by [GitHub Copilot](https://docs.github.com/copilot/about-github-copilot/what-is-github-copilot). Therefore, it may contain mistakes. If you find any translation that is inappropriate or mistake, please create an [issue](https://github.com/github/awesome-copilot/issues).

同时必须遵守三条附加规则：

1. 免责声明也要被本地化（"The disclaimer should also be localized"）——即追加到localization/zh-cn/下的文档时，声明内容本身应翻译为简体中文，而不是机械地粘贴英文原文；
2. 声明中的链接始终指向 issue 页面（"Make sure the link in the disclaimer should always point to the issue page"）——无论本地化成什么语言，其中的反馈链接都必须指向仓库的 issues 页面，确保读者能便捷地报告翻译错误；
3. 该声明追加在文档末尾，并以---分隔，与正文形成清晰边界。

这条规则的价值在于：机器翻译不可避免存在错误，通过强制声明 + 固定的反馈通道，把"翻译可能有误"的预期管理显性化，并将质量改进闭环引导到 issue 流程。

仓库中的本地化实践佐证

指令文件的多语言实例

awesome-copilot 仓库本身即是这条本地化指令的最佳应用样本。在 instructions/ 目录下可以看到同一指令文件的多语言形态：

• csharp-ja.instructions.md：C# 开发指令的日语版本，全文使用日文书写，frontmatter 描述同样本地化为日文（description: 'C# アプリケーション構築指針 by @tsubakimoto'）；
• csharp-ko.instructions.md：C# 指令的韩语版本，frontmatter 描述为韩文。

从这两个文件可以印证本地化指令在真实仓库中的落地要点：正文全部翻译、frontmatter 中的 description 一并翻译、文件名保留英文原样（csharp-ja/csharp-ko通过后缀标识语言，而非重命名整个文件）。这与本地化指令中"本地化所有章节与段落"的要求一致——连元数据描述也属于文档内容的一部分。

其他本地化 Skill 的互补视角

仓库中另有两个与本地化强相关的 Skill，可与本文主题互相印证：

• mkdocs-translations/SKILL.md：面向 MkDocs 文档站的翻译 Skill，同样要求按目标语言代码建目录、镜像原文目录结构、逐文件翻译不跳过、保留所有 Markdown 格式（标题、代码块、元数据、链接），并在文件末尾追加翻译署名。它与localization.instructions.md在"目录化输出、镜像结构、逐文件不遗漏"三方面高度一致，说明这是社区公认的文档本地化范式。
• vscode-ext-localization/SKILL.md：面向 VS Code 扩展的本地化 Skill，展示了不同资源类型的本地化载体——package.nls.LANGID.json（配置与命令）、walkthrough/someStep.pt-br.md（walkthrough 文档）、bundle.l10n.LANGID.json（源码字符串）。它揭示了语言代码在扩展生态中的普遍用法（如pt-br），与指令文档中language-region的命名规范一脉相承。

这些实例表明：localization.instructions.md并非孤立规则，而是与仓库内 i18n 生态共享同一套 locale 命名与"不遗漏、保结构、留出处"的质量原则。

如何在 Copilot 中使用这条本地化指令

结合 docs/README.instructions.md 与 instructions.instructions.md 的说明，将这条本地化指令投入实战的步骤如下：

1. 获取指令文件：将 localization.instructions.md 加入工作区的指令集合——可以复制到.github/copilot-instructions.md，或放到.github/instructions/目录下；
2. 触发本地化任务：在 Copilot 对话中给出明确指令，例如"找到仓库中所有 Markdown 文档，并将它们本地化为zh-cn"，Copilot 会以本地化专家身份启动流程；
3. 验收产物：检查localization/zh-cn/目录是否创建、目录名是否符合language-region格式、每个文档是否结尾带（本地化的）免责声明，并通过行数比对确认无章节遗漏。

小结

localization.instructions.md用一份精炼的规则清单，定义了"机器翻译技术文档"这一任务的完整质量闭环：统一的目录与 locale 命名（localization/{{locale}}、ISO 639-1 + ISO 3166）保证产物可发现；"不遗漏章节段落 + 行数比对"保证翻译完整；"图片指原文、文档链接指本地化版本"保证引用关系不破裂；"强制免责声明 + 指向 issue 的反馈链接"保证错误可回收、质量可持续改进。配合仓库内日语、韩语指令文件的真实样本，这套规范可直接迁移到任何以 Markdown 为主体的文档仓库中落地执行。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot