# Agent Note: 双语文档链接本地化

Status: implemented

[English](2026-08-18-localized-bilingual-links.md) | 中文

## Problem

GitHub 会直接解析仓库 Markdown 链接，不经过文档网站的 locale projector。若要求双语配对两侧保留相同的 `.md` 原始目标，即使已有经评审的 `.zh.md` 兄弟文件，中文源文件的读者也会被带到英文页面。文档网站会按当前 locale 路由普通链接，从而掩盖这个错误，导致仓库源码与发布网站产生不同的导航结果。

## Decision

目标属于活跃双语语料时，仓库相对文档链接跟随源文件 locale：英文源使用目标 `.md`，中文源使用其 `.zh.md`。两侧保持相同的语义目标以及完全相同的 query/fragment 后缀。该范围内缺少对侧属于配对完整性错误，不得回退；外部 URL、图片、纯页内 fragment 与范围外目标保持不变。语言切换行是显式跨 locale 例外。

意图进入教程首页的页面导航链接会显式写出 `index.md` 或 `index.zh.md`，使 GitHub 直接打开页面，而不是目录列表。已审计的 basic、framework 与 practice 入口均使用这些具体目标；普通 package、源码、示例与 manifest 目录引用仍然有效，不存在通用的目录链接禁止规则。

配对核心会依据仓库文件树解析相对路径，再应用活跃范围与 manifest 排除项谓词，并在结构比较时把配对的 locale 路径规范化为同一个英文兄弟文件身份。`verify-translation-pairing` 会另外拒绝 locale 错误的目标，并报告源文件、行号、实际 URL 与期望 URL。合并驱动、机械翻译简报与 Cordis 生成器使用同一套范围谓词和语义比较，因此既能接受正确的 locale 路径差异，又不会削弱其他结构要求。

Cordis subsystem 区块生成器先渲染同一个 catalog model，再为中文输出投影配对文档目标。生成区块比较只规范化这些配对 locale 路径；marker、正文、顺序、代码、非文档 URL 与 query/fragment 后缀仍须逐字节一致。

现有活跃双语源文件均使用 locale 正确的目标。若中文目标缺少英文 fragment id，则在对应译文标题前提供显式 `<a id>` 别名，使两个源文件无需第二份翻译映射即可保留同一个稳定 fragment 后缀。配对一致性记录指向迁移后的内容。

## Verification

配对测试覆盖中英文 locale 选择、存在兄弟文件的范围外目标、范围内缺少对侧的目标、语言切换行排除、query/fragment 原样保留、不从目录目标推断索引页、定义式链接、重写与诊断。文档网站测试还会固定中英文两侧已审计的 basic、framework 与 practice 入口，要求它们指向具体索引页。合并驱动、翻译简报与 Cordis 生成器测试分别覆盖各自消费路径。全语料检查要求 locale 错误链接为零、fragment 可解析、生成区块新鲜、配对记录为当前内容，并要求文档网站成功构建。

## Alternatives considered

**两侧都保留 `.md` 目标。** 这种方式能保持原始目标相等，却会让 GitHub 导航离开中文语料。网站重写无法修复仓库渲染结果。

**使用翻译后的标题 fragment。** 各 locale 专属 fragment 会要求每个链接生成方了解译文标题，还会引入一份可能发生漂移的映射。共享同一个后缀，并由目标文档提供显式别名，能让稳定标识归目标文档所有。

**维护 locale 链接 manifest。** 配对发现、只含排除项的 manifest 与兄弟命名约定已经能够确定目标是否属于语料以及配对路径。第二份注册表会重复身份事实，并要求每次移动文件或新增配对时同步更新。

**只在发布时重写链接。** 文档网站已经这样处理，但 GitHub 与其他仓库渲染器会直接消费源文件。正确的源码路径本身就是用户可见行为。

## Consequences

目标属于活跃双语语料时，GitHub 读者会留在自己选择的语言中；未来回退会由拥有双语结构的同一道全语料配对检查拒绝。配对两侧会有意使用不同的配对文档路径拼写，而链接的其他属性仍保持一致。稳定的英文 fragment 别名会为翻译目标增加少量永久标识；同时拥有两侧输出的生成器必须先投影 locale 路径，再记录配对。
