# 双语支持约定（zh / en）

> 本文件是「同一套流程，两种语言」的**唯一契约**：模板、门禁脚本、工具输出三者改语言时都以本文件为准。
> 一句话原则：**机器认标记，人读文字；文字可换语言，标记永不翻译。**

---

## 1. 语言解析优先级

任何组件（门禁脚本 / 工具 / 技能提供者）判定「这个仓库用哪种语言」时，按下列顺序取第一个命中的：

| 顺序 | 来源 | 取值 | 说明 |
| --- | --- | --- | --- |
| 1 | 环境变量 `PROCESS_KIT_LANG` | `zh` / `en` | 显式覆盖，优先级最高（按进程生效） |
| 2 | `docs/process/.process-kit.json` 的 `lang` | `zh` / `en` | `process_init` 写入，**仓库级真源** |
| 3 | `docs/process/PROJECT.md` frontmatter 的 `lang` | `zh` / `en` | 手改语言就走这里 |
| 4 | 自动推断 | `zh` / `en` | 看 `AGENTS.md`、`README.md` 的 CJK 占比；无判据 ⇒ `zh`（存量仓库零变化） |

`process_init` 的 `lang` 参数额外接受 `auto`（默认）：按**目标仓库**的 `AGENTS.md` / `README.md` 语言推断，判据不足回退 `zh`。

**切换语言** = 用 `process_init({ upgrade: true, lang: "en" })` 重跑升级：框架自有文件按新语言覆盖（先备份为 `<文件>.bak-<时间戳>`），项目可定制文件（`PROJECT.md` / `ui/tokens.md` / `ui/recipe.md`）**不覆盖**，只把包内新语言版本的位置报给人合并。

---

## 2. 文件与产物命名

**机器文件路径不随语言变化**（`docs/process/**` 骨架、`scripts/process/*.mjs`、`.process-kit.json`、`prd/<ID>.md`、`<ID>.journal.jsonl`、`<ID>-ui-spec.md`、`<ID>-design.md`、`<ID>-arch.md`、`<ID>-checklist.md`、`prototypes/<ID>/index.html`、`handoff.md`…）。语言只影响**内容**，不影响落点。

唯一带语言的命名是**需求核对件**（人读文件，两种都认）：

| 语言 | 核对件文件名 | 判据 |
| --- | --- | --- |
| zh | `docs/process/input/<ID>-需求核对件.md` | frontmatter `kind: requirement-check`（**权威判据**） |
| en | `docs/process/input/<ID>-check.md` | 同上 |

> 一律以 frontmatter `kind: requirement-check` 为准；文件名只作存量兼容的兜底，且**跳过 `_` 开头的模板**。

---

## 3. 机器标记（markers）

模板在**关键小节标题的上方一行**放 HTML 注释标记，门禁优先按标记定位小节，标记缺失才回退中英标题别名。标记本身不渲染、不翻译、不得改写。

| 标记 | 放在哪 | 锚定什么 |
| --- | --- | --- |
| `<!-- process:owner-table -->` | `PROJECT.md` §3「产物属主表 / Artifact ownership」标题正上方 | 属主表（落点门禁唯一放行来源） |
| `<!-- process:registry -->` | `tools/README.md` 的「登记区 / Registry」标题正上方 | 载体侧登记区 |

标题匹配规则（标记缺失时的兜底，**两种语言都认**）：

| 锚点 | 认的标题 | 认的表头列 |
| --- | --- | --- |
| §3 属主表 | `## 3. …`（编号）· 含「产物属主」· 含 `ownership`（大小写不敏感） | 含「可写路径」· 含 `writable path(s)` |
| §4 项目配置 | `## 4. …`（编号）· 含「项目配置」· 含 `project config` | — |
| §5 UAT 前置 | `## 5. …`（编号）· 含「UAT 前置」· 含 `UAT preflight` | — |
| 登记区 | `## 登记区` · `## Registry` | — |

**规则更新纪律**：新增一个解析锚点 = 同时给中英两种写法 + 给标记；只加中文别名不算完成。
代码位置：`scripts/project-config.mjs` 的 `ANCHOR` / `SECTION` / `CONFIG_KEYS` 常量。

---

## 4. PROJECT.md 配置键对照（`check-rules` / `check-artifact-paths` / `check-uat-readiness` / `sync-prd-version` 读）

**键名照抄、不得改名**（脚本按单元格原文精确匹配，大小写不敏感）；两种语言任写一种即可。

### 4.1 §4 项目配置

| zh（存量） | en（新） |
| --- | --- |
| `测试扫描目录` | `Test scan dirs` |
| `测试文件后缀` | `Test file suffixes` |
| `流程测试目录` | `Flow test dirs` |
| `需求包测试目录` | `Package test dirs` |
| `import 白名单` | `Import allowlist` |
| `自动化类型` | `Automation types` |
| `@case 载体类型` | `@case carrier types` |
| `junit 测试目录` | `JUnit test dirs` |
| `待裁定字样` | `Pending-decision patterns` |
| `台账目录` | `Rules dir` |
| `PRD 目录` | `PRD dir` |
| `登记区文件` | `Registry file` |
| `UI 项目令牌` | `UI project tokens` |
| `UI 原型目录` | `UI prototypes dir` |

### 4.2 §5 UAT 前置自检

| zh（存量） | en（新） |
| --- | --- |
| `core 后端` | `Core backend` |
| `web 前端` | `Web frontend` |
| `移动端` | `Mobile` |
| `验收账号` | `UAT account` |
| `验收口令` | `UAT password` |
| `目标端点` | `Target endpoints` |
| `端点前缀` | `API prefix` |
| `登录路径` | `Login path` |
| `令牌字段` | `Token field` |
| `真机 CDP` | `Device CDP` |
| `清单目录` | `Checklist dir` |
| `证据目录` | `Evidence dir` |

> 取值列仍然**不能含空格与竖线**（`parseList` 按空白与 `、,，;；` 切分）；英文取值请写单 token 或反引号包裹的单 token。

---

## 5. 「只写一处语言」清单

| 内容 | zh 源 | en 源 | 落地方式 |
| --- | --- | --- | --- |
| 流程骨架（总纲 / 调度手册 / 模板 / UI 默认层） | `scaffold/**` | `scaffold/en/**` | `process_init({ lang })` 选源，落到同一批 `docs/process/**` 路径 |
| 角色技能 | `skills/<role>/SKILL.md` | `skills/<role>/SKILL.en.md` | 技能 provider 按仓库语言选文件；`skills=true` 落地 **SKILL.md**（内容随语言） |
| 项目常驻指针 | `AGENTS.template.md` | `AGENTS.template.en.md` | `process_init` 按语言选模板 |
| 门禁脚本运行期消息 | 脚本内 `msg(zh, en)` 成对 | 同左 | 按仓库语言取其一 |
| 工具描述（模型读） | 中英并列 | 同左 | `bi()` 拼接：英文段 + 中文段 |
| 工具输出报告 | `lib/index.js` 内 `t(lang)` 成对字面量 | 同左 | 按仓库语言渲染（语言取自 `repoLang(root)`） |
| 用户 / 贡献者文档 | `README.md`、`docs/*.md` | `README.en.md`、`docs/*.en.md` | 两份独立文件，逐节对应；顶部一行互指（`> **中文**: see …` / `> **English**: see …`）。`test/i18n.test.mjs` 核对小节数一致、除互指行外零中文 |

**维护纪律**：改任一语言都必须同轮改另一语言；`test/i18n.test.mjs` 会核对两套骨架的**文件清单一致**、**标记齐备**、**配置键与别名表一致**，漏改即红。

---

## 6. 验收口径

一种语言算「支持」，必须同时满足：

1. `process_init({ lang })` 落地后，`docs/process/**` 通篇该语言（除机器标记与代码块示例）；
2. 两道门禁在**该语言仓库**里能跑到绿，在越界时能红（虚构一次越界实测）；
3. 用该语言造的核对件 / PRD 能被 `process_status` 正常读状态位（`kind` / `status` / `gateN` 全英文键）；
4. 技能正文是纯该语言（不含另一种语言的整段说明）。
