# I18n Workflow

当前 i18n 结构已切为 `core + domain adapter`：

- `i18n/core` 负责通用 occurrence、reference、output reference、authority、workset、report 模型
- `i18n/domains/manifest` 负责 `package.json` / `package.nls*` 的提取、对账与生成
- `i18n/domains/webviews` 当前覆盖 `settings` 静态 HTML shell 的端到端提取/生成，以及 `welcome` / `rebase` / `home` / `commitDetails` / `timeline` / `graph` / `composer` 受控入口的构建期本地化源码派生；本分支将本地化 webview 产物直接发布为 canonical `dist/webviews` 运行时产物，`patchDetails` 与其他 mixed-renderer 或后续页面族仍通过 deferred issues 显式保留在后续范围
- `i18n/domains/runtimeDynamic` 负责 formatter / quickpicks / webviewHost 这类扩展宿主动态 UI 文案的只读源码提取、对账、报告与 `.work` 本地化源码产物生成；webpack 构建期 loader 会在不修改 `src/**` 调用点的前提下将这些产物注入扩展 bundle

`i18n/authority/zh-cn/overrides.json` 统一承载 `occurrence` / `anchor` / `scope` / `output` 四类覆盖规则。

## 常用流程

### 首选聚合命令

普通人工介入流程优先使用顶层聚合命令，不再默认拆成 manifest / formatter / quickpicks / webviewHost / webviews 五组分别执行：

```bash
node ./i18n/cli.mts sync
node ./i18n/cli.mts report --base HEAD
node ./i18n/cli.mts promote
node ./i18n/cli.mts generate
```

- `sync` 刷新 catalog、reconciliation report 与 workset
- `report` 刷新各 domain 的 pending report，并在控制台输出聚合摘要；如需额外保存聚合摘要，可加 `--write aggregate-pending.json`
- `promote` 将已批准 workset 条目提升到 authority
- `generate` 基于既有 catalog 与 authority 生成运行时产物

`sync` / `report` 默认覆盖 manifest、formatter、quickpicks、webviewHost 与 webviews。webviews 静态 HTML 从 `src/webviews/apps/settings/settings.html` 及其 `partials/*.html` 提取，不依赖预先构建出的 `dist/webviews/settings.html`；只在明确不需要 webviews 时加 `--skip-webviews`。

### 手动修改 authority 后

如果只修改了 `i18n/authority/zh-cn/messages.json`、`terms.json`、`aliases.json` 或 `overrides.json`，通常不需要分别运行 formatter、quickpicks、webviews 的分域生成命令。直接运行：

```bash
node ./i18n/cli.mts generate
```

这个聚合命令会基于既有 catalog 与 authority 生成：

- formatter runtime dynamic 本地化源码
- quickpicks runtime dynamic 本地化源码
- webviewHost runtime dynamic 本地化源码
- webviews 动态源码
- webviews settings HTML 源镜像

如果手动修改的 authority 也影响 manifest / `package.nls*` staging，使用：

```bash
node ./i18n/cli.mts generate --with-manifest
```

如果随后需要把本地化源码编进 extension/webview bundle，运行：

```bash
pnpm run build:quick
```

`pnpm run build:quick` 本身也会触发 runtime dynamic 与 webviews 的生成步骤；如果 VS Code Extension Host 已启动，需要重新加载窗口才能看到新的 bundle。

分域 `generate` 命令仍保留给开发期定位问题或只刷新单一域时使用，不作为人工修改 authority 后的默认路径。

### 上游源码变更后

当上游英文源码、manifest 或 webview 文案发生变化时，先运行：

```bash
node ./i18n/cli.mts sync
node ./i18n/cli.mts report --base HEAD
```

确认并批准 workset 翻译后，再运行：

```bash
node ./i18n/cli.mts promote
node ./i18n/cli.mts generate
```

如果随后需要把本地化源码编进 extension/webview bundle，继续运行 `pnpm run build:quick`。

分域 `sync` / `report` / `promote` / `generate` 命令仍保留给开发期定位问题、只刷新单一 domain 或验证某个 extractor/generator 行为时使用，不作为常规人工流程入口。

## Manifest Domain

- `i18n/catalog/package.catalog.json` 保留 manifest domain 的 occurrence、source reference、output reference 与对账信息
- `i18n/worksets/package.zh-cn.json` 保留 manifest 翻译工作状态与 `occurrenceIds`
- `i18n/reports/package-pending.json` 是 manifest 域的派生进度视图
- `.work/i18n/extension-root/zh-cn/{package.json,package.nls.json,package.nls.zh-cn.json}` 是 manifest 域的可重放运行时/打包 staging 产物；根目录 `package.json` 保持上游英文源码, 不承载 `%key%` 本地化 token

常用命令：

1. 常规刷新使用顶层 `node ./i18n/cli.mts sync` / `report --base HEAD` / `promote`
2. `node ./i18n/cli.mts generate --with-manifest` 刷新 manifest staging；仅排查 manifest 时使用 `node ./i18n/cli.mts manifest generate`
3. `node ./i18n/cli.mts manifest package` 先从真实仓库根目录运行生产 bundle, 再生成 staged extension root, 并从该 root 运行不会再次触发 staged `vscode:prepublish` 的 `vsce package`

`.vscode/launch.json` 中的 `Run` 与 `Watch & Run` 会先运行 manifest staging 生成任务, 再使用 `.work/i18n/extension-root/zh-cn` 作为 `--extensionDevelopmentPath`。因此这两个桌面调试入口读取 staged `package.json`，而不是根目录英文 manifest。

## Webviews Domain

- `i18n/catalog/webviews.catalog.json` 保留 webviews domain 的 occurrence、source reference 与 runtime output reference
- `i18n/worksets/webviews.zh-cn.json` 保留 webviews 翻译工作状态与 `occurrenceIds`
- `i18n/reports/webviews-pending.json` 是 webviews 域的派生进度视图
- `.work/i18n/generated/zh-cn/src/webviews/apps/**` 是由 workflow 基于上游英文源码 AST/HTML 派生的本地化源码镜像；webpack 会再将其编译为 canonical `dist/webviews/*` 运行时产物
- `settings` 静态 HTML 按 `src/webviews/apps/settings/settings.html` 与 `src/webviews/apps/settings/partials/*.html` 分别生成镜像，不在 i18n workflow 中预聚合 partials；最终聚合由 HtmlWebpackPlugin/html-loader 在构建阶段完成
- `--dynamic-sources-only` 与 `--settings-sources-only` 只根据既有 catalog / authority 生成对应 webview 源镜像，不重跑全量 sync，避免构建过程刷新翻译根源数据
- `patchDetails` 与其余尚未接入的 mixed-renderer / follow-up 页面当前不会生成本地化脚本产物，而是通过 catalog reconciliation 中的 deferred issues 暴露后续范围

常用命令：

1. 常规刷新使用顶层 `node ./i18n/cli.mts sync` / `report --base HEAD` / `promote`
2. `node ./i18n/cli.mts generate` 刷新 webviews 动态源码与 settings HTML 源镜像；仅排查 webviews 时使用 `node ./i18n/cli.mts webviews generate`
3. `pnpm run build:webviews`

## Runtime Dynamic Domain

- `i18n/catalog/formatter.catalog.json` / `i18n/catalog/quickpicks.catalog.json` / `i18n/catalog/webviewHost.catalog.json` 保留 runtime dynamic domain 的 occurrence、source reference、runtime output reference 与对账信息
- `i18n/worksets/formatter.zh-cn.json` / `i18n/worksets/quickpicks.zh-cn.json` / `i18n/worksets/webviewHost.zh-cn.json` 保留对应翻译工作状态与 `occurrenceIds`
- `i18n/reports/formatter-pending.json` / `i18n/reports/quickpicks-pending.json` / `i18n/reports/webviewHost-pending.json` 是对应域的派生进度视图
- `.work/i18n/generated/zh-cn/<repo-relative-path>` 是由 workflow 基于上游英文源码 AST 派生的本地化源码镜像；构建时通过 `i18n/domains/runtimeDynamic/localizedRuntimeDynamicSourceLoader.cjs` 以内存替换方式注入 extension bundle, 不直接修改或替代 `src/**`
- `webviewHost` 当前覆盖 `src/webviews/**/registration.ts` 中的 WebviewView descriptor 标题，用于避免 VS Code manifest 本地化标题在视图 resolve 后被英文 runtime descriptor 覆盖。
- 任何需要改动应用源码以消费 runtime dynamic 产物的路径, 必须先通过 source-touchpoint review; 禁止为了本地化在上层 commands、picker flows、views、services 中大面积添加调用点
- `node ./i18n/cli.mts generate` / `pnpm run build:quick` / `pnpm run watch:quick` 会触发 runtime dynamic source generation；如果 VS Code Extension Host 已启动, 需要重新加载窗口才能看到新的 bundle

常用命令：

1. 常规刷新使用顶层 `node ./i18n/cli.mts sync` / `report --base HEAD` / `promote`
2. `node ./i18n/cli.mts generate` 或仅排查单一域时使用 `node ./i18n/cli.mts formatter generate` / `node ./i18n/cli.mts quickpicks generate` / `node ./i18n/cli.mts webviewHost generate`
3. `pnpm run build:quick` 或启动对应 watch 任务后重新加载 Extension Host

## Override Selector 语义

- `occurrence`：只覆盖一个具体 occurrence
- `anchor`：覆盖同一稳定锚点
- `scope`：覆盖某个 domain scope 下的 occurrence
- `output`：覆盖某个具体输出目标
