2026Technology-Competition/docs/superpowers/specs/2026-07-26-i18n-design.md

# i18n 国际化 — Extension Design Spec

## 1. 概述

为 vscode-code-reviewer 实现运行时动态语言切换。用户在设置面板选择语言后，所有 webview 面板、通知、QuickPick、报告等 UI 文字立即生效，无需重载 VS Code 窗口。

语言源：复用现有 `ai.outputLanguage` 配置项（`zh-CN` / `en` / `ja`）。

### 范围

| 区域 | 是否纳入 | 说明 |
|------|---------|------|
| Webview 面板（设置/审查报告/导入预览） | 是 | 动态重渲染 |
| 通知（showInformationMessage 等） | 是 | 下次调用用新语言 |
| QuickPick | 是 | 下次调用用新语言 |
| 进度条（withProgress） | 是 | 下次调用用新语言 |
| 报告导出（Markdown） | 是 | 导出时取当前语言 |
| 适配器错误消息 | 是 | 每次调用取当前语言 |
| `package.json` contributes | 否 | 跟随 VS Code 机制，不影响 |
| AI 提示词（engine.ts / fixer.ts） | 否 | 保持中文，保证 AI 输出质量稳定 |

---

## 2. 核心模块：`src/i18n/messages.ts`

### 2.1 类型定义

```typescript
export type Language = 'zh-CN' | 'en' | 'ja';

const defaultLang: Language = 'zh-CN';
```

### 2.2 消息注册

单文件注册所有文案，每条包含三种语言的值。命名采用 `模块.场景.含义`，点分隔，全小写。

```typescript
const messages = {
  'review.noEditor': {
    'zh-CN': '请先打开一个文件',
    en: 'Please open a file first',
    ja: '最初にファイルを開いてください',
  },
  // ...
};

类型约束：`Record<string, Record<Language, string>>`，确保所有消息三种语言都有值。

### 2.3 运行时语言

```typescript
let currentLang: Language = defaultLang;
```

### 2.4 `t()` 函数

```typescript
export function t(key: string): string {
  const msg = messages[key]?.[currentLang] ?? messages[key]?.[defaultLang];
  return msg ?? key;
}
```

插件内所有文案都通过 `t()` 获取，不再硬编码。无模板插值参数，简单直接。

### 2.5 语言切换

```typescript
const languageChangeEmitter = new vscode.EventEmitter<Language>();

export function setLanguage(lang: Language): void {
  if (currentLang === lang) return;
  currentLang = lang;
  languageChangeEmitter.fire(lang);
}

export function onLanguageChange(listener: (lang: Language) => void): vscode.Disposable {
  return languageChangeEmitter.event(listener);
}

export function getLanguage(): Language {
  return currentLang;
}
```

---

## 3. 语言切换流程

采用"写配置 → 事件驱动"的单一入口模式：

```
用户在设置面板改语言下拉
  ↓
webview postMessage 'setLanguage'
  ↓
extension 端 handleMessage:
  vscode.workspace.getConfiguration('vscode-code-reviewer')
    .update('ai.outputLanguage', lang, true)
  ↓
onDidChangeConfiguration 监听到变化（ext.activate 中注册）
  ↓
if (changed.key === 'vscode-code-reviewer.ai.outputLanguage')
  setLanguage(newLang)
  ↓
onLanguageChange 触发
  ↓
所有 webview 回调: postMessage 推送新翻译 → 全量重渲染
所有通知/QuickPick: 下次调用时 t() 取新语言
```

### 3.1 为什么不用同步 setLanguage + update

- 用户可能通过 VS Code 原生设置界面改语言，`onDidChangeConfiguration` 能自动捕获
- 单一入口、无分支、逻辑内聚

### 3.2 初始化

`extension.ts` 的 `activate()` 中：

```typescript
// 从当前配置初始化语言
const lang = getAIOutputLanguage() as Language;
setLanguage(lang);

// 监听配置变更
context.subscriptions.push(
  vscode.workspace.onDidChangeConfiguration(e => {
    if (e.affectsConfiguration('vscode-code-reviewer.ai.outputLanguage')) {
      const newLang = getAIOutputLanguage() as Language;
      setLanguage(newLang);
    }
  })
);
```

---

## 4. Webview 刷新策略

### 4.1 消息推送

扩展端构建翻译后的消息 map 通过 `postMessage` 发给 webview：

```typescript
// 只推送当前 webview 需要的 key
function pushLanguage(webview: vscode.Webview) {
  const translated: Record<string, string> = {};
  for (const key of webviewI18nKeys) {
    translated[key] = t(key);
  }
  webview.postMessage({ type: 'lang', lang: currentLang, messages: translated });
}
```

### 4.2 Webview 端处理

```javascript
window.addEventListener('message', e => {
  if (e.data.type === 'lang') {
    render(e.data.messages, e.data.lang);
  }
});
```

### 4.3 重渲染

全量重渲染。每个 webview 在收到 `lang` 消息后重建 HTML。

设置面板特殊处理：
- 保存表单当前值到 JS 变量中
- 语言下拉变化时：先持久化当前表单值（API Key 等），再改语言，最后重建
- 重建后用保存的变量回填表单

### 4.4 Webview HTML 生成方式

当前 webview 在扩展端生成 HTML 字符串。改造后：

- 被翻译的文案在生成 HTML 时用 `t()` 注入（扩展端调用）
- 生成完整 HTML 时文案已经翻译好，webview 端 JS 无需再翻译
- webview 端 JS 只是接收到 `lang` 消息时重新请求全集 HTML（或接受新 HTML 字符串替换）

三种面板处理方式：

| 面板 | 策略 |
|------|------|
| 审查报告 | 重新生成 HTML → postMessage → 替换 `document.body.innerHTML` |
| 设置面板 | 保留表单 JS 变量，重新生成 HTML 后回填 |
| 导入预览 | 重新生成 HTML → postMessage → 替换 |

---

## 5. 消息清单设计

预估约 60 条文案，按命名空间分组。

### 5.1 review.* （审查类）

| Key | zh-CN | en (参考) |
|-----|-------|-----------|
| `review.noEditor` | 请先打开一个文件 | Please open a file first |
| `review.running` | 正在审查... | Reviewing... |
| `review.staticAnalysis` | 运行静态分析... | Running static analysis... |
| `review.aiReview` | 运行 AI 审查... | Running AI review... |
| `review.completeSelection` | 选中代码审查完成: {0} 个问题 | Selection review: {0} issues |
| `review.needRunFirst` | 请先运行完整审查生成报告 | Run a full review first |
| `review.noSelection` | 请先选中要审查的代码 | Select code to review first |
| `review.needApiKey` | 请先在设置面板中配置 API Key | Configure API Key in Setup first |
| `review.fixNotAvailable` | 单条修复功能开发中 | Single fix under development |
| `review.fixAllNotAvailable` | 批量修复功能开发中 | Batch fix under development |

### 5.2 export.* （导出类）

| Key | Description |
|-----|-------------|
| `export.selectMethod` | 选择导出方式 |
| `export.copyToClipboard` | 复制到剪贴板 |
| `export.downloadMarkdown` | 下载 Markdown 文件 |
| `export.copied` | 报告已复制到剪贴板 |
| `export.saveDialogTitle` | 保存审查报告 |
| `export.saved` | 报告已保存到 {0} |

### 5.3 setup.* （设置面板）

| Key | Description |
|-----|-------------|
| `setup.header` | 净码特工 · 代码审查 · 设置 |
| `setup.quickStart` | 快速开始 |
| `setup.gettingStarted` | 三步启用代码审核 |
| `setup.step1` | 安装插件后，配置 AI 模型及 API Key... |
| `setup.step2` | 启用自定义规则，补充团队特有的编码规范 |
| `setup.step3` | 保存并测试连接，验证配置无误后即可触发审核 |
| `setup.step3Hint` | 按 Ctrl + Shift + R 快捷键触发审核... |
| `setup.engineSection` | 审核引擎 |
| `setup.commonRules` | 共通规则 |
| `setup.linterStatic` | Linter 静态分析 |
| `setup.customRules` | 自定义规则 |
| `setup.teamCoding` | 团队编码规范 |
| `setup.aiReview` | AI 审核 |
| `setup.deepReview` | 深度代码审查 |
| `setup.aiConfig` | AI 模型配置 |
| `setup.provider` | 模型提供商 |
| `setup.notConfigured` | 未配置 |
| `setup.model` | 模型名称 |
| `setup.modelHint` | 建议使用支持结构化输出的模型 |
| `setup.apiKey` | API Key |
| `setup.baseUrl` | Base URL |
| `setup.keyStorageHint` | Key 仅存储在本地 VS Code 安全存储中 |
| `setup.outputLang` | 输出语言 |
| `setup.outputLangHint` | AI 审查结果输出语言 |
| `setup.customRulesSection` | 自定义规则 |
| `setup.ruleList` | 规则列表 |
| `setup.ruleCount` | {0} 条 |
| `setup.ruleNamePlaceholder` | 输入规则名称... |
| `setup.add` | + 添加 |
| `setup.ruleNameHint` | 建议使用英文名称... |
| `setup.reset` | 重置 |
| `setup.saveAndTest` | 保存并测试连接 |
| `setup.testSuccess` | ✓ 连接成功 |
| `setup.testFail` | ✗ 连接失败: {0} |
| `setup.setApiKeyFirst` | 请先设置 API Key |
| `setup.setBaseUrlFirst` | 请先设置 Base URL |
| `setup.selectRuleFile` | 选择规则文件 |
| `setup.fileExists` | 文件 {0} 已存在 |
| `setup.importSuccess` | 规则文件已导入: {0} |
| `setup.importCancelled` | 导入已取消 |
| `setup.importDedupResult` | 规则已导入: ... ({0} 条，{1} 条重复已注释，{2} 条重叠已标注) |
| `setup.importFail` | 规则导入失败: {0} |
| `setup.openSetupFail` | 无法打开设置面板 |
| `setup.openSettingsJson` | 打开设置 (JSON) |
| `setup.noWorkspace` | 请先打开工作区 |
| `setup.manageRulesHint` | 请在设置面板中管理自定义规则 |
| `setup.languageLabels` | 中文（简体）/ English / 日本語 |

### 5.4 report.* （审查报告）

| Key | Description |
|-----|-------------|
| `report.title` | 代码审查报告 |
| `report.panelTitle` | 净码特工 · 代码审查报告 |
| `report.totalIssues` | 总计问题 |
| `report.errors` | 错误 |
| `report.warnings` | 警告 |
| `report.info` | 建议 |
| `report.fixAll` | 全部修复 |
| `report.rerun` | 重新审查 |
| `report.export` | 导出报告 |
| `report.sourceLinter` | Linter |
| `report.sourceCustom` | 自定义 |
| `report.sourceAI` | AI |
| `report.noIssues` | 未发现任何问题 |
| `report.noRuleViolations` | 未发现规则违规 |
| `report.noAIFindings` | 无 AI 审查建议 |
| `report.skipCustomRules` | 当前文件语言无匹配的自定义规则 |
| `report.executionErrors` | 执行错误 |
| `report.degraded` | AI 审查未完成，报告仅包含部分结果 |
| `report.degradedBanner` | 部分 AI 功能不可用，报告已降级 |
| `report.file` | 文件 |
| `report.language` | 语言 |
| `report.duration` | 耗时 |
| `report.tools` | 分析工具 |
| `report.totalSummary` | 总计: {0} \| 错误: {1} \| 警告: {2} \| 建议: {3} |
| `report.staticSection` | 静态分析 · {0} 个问题 |
| `report.customSection` | 自定义规则 · {0} 个问题 |
| `report.aiSection` | AI 审查 · {0} 条建议 |
| `report.suggestion` | 建议 |
| `report.noProblems` | 未发现问题 |

### 5.5 import.* （规则导入）

| Key | Description |
|-----|-------------|
| `import.previewTitle` | 规则导入预览 |
| `import.source` | 来源：{0} · 检测到 {1} 条规则 |
| `import.fullDuplicate` | 完全重复 {0} 条 |
| `import.partialOverlap` | 部分重叠 {0} 条 |
| `import.noDuplicate` | 无重复 {0} 条 |
| `import.willKeep` | 将保留 {0} 条规则，注释 {1} 条规则 |
| `import.keep` | 保留 |
| `import.comment` | 注释 |
| `import.cancel` | 取消 |
| `import.confirm` | 确认导入 |
| `import.emptyFile` | 所选文件为空 |
| `import.needApiKey` | 请先在设置面板中配置 API Key |
| `import.timeout` | AI 生成规则超时，请检查网络或增大 ai.timeout 配置 |
| `import.aiFail` | AI 生成规则失败: {0} |
| `import.emptyResponse` | AI 返回内容为空 |
| `import.excelReadFail` | 读取 Excel 文件失败: {0} |
| `import.excelEmpty` | Excel 文件没有工作表 |
| `import.excelNoData` | Excel 工作表中没有数据 |
| `import.docxReadFail` | 读取 Word 文件失败: {0} |
| `import.docxEmpty` | Word 文件中没有可提取的文本内容 |
| `import.pptxReadFail` | 读取 PowerPoint 文件失败: {0} |
| `import.pptxEmpty` | PowerPoint 文件中没有可提取的文本内容 |

### 5.6 adapter.* （适配器错误）

| Key | Description |
|-----|-------------|
| `adapter.javaNotInstalled` | Java 11+ 未安装或不在 PATH 中 |
| `adapter.sqlfluffNotInstalled` | sqlfluff 未安装，请执行 pip install sqlfluff |
| `adapter.invalidApiKey` | API Key 无效，请重新设置 |
| `adapter.noApiKey` | 未配置 API Key |
| `adapter.createProviderFail` | 创建 Provider 失败: {0} |
| `adapter.customRuleParseFail` | 自定义规则响应解析失败: {0} |
| `adapter.customRuleRequestFail` | 自定义规则请求失败: {0} |
| `adapter.aiReviewParseFail` | AI 审查响应解析失败: {0} |
| `adapter.aiReviewRequestFail` | AI 审查请求失败: {0} |

### 5.7 extension.* （插件级）

| Key | Description |
|-----|-------------|
| `extension.activated` | 净码特工 · Code Purifier 已激活 |

### 5.8 命令标题（仅作参考，不修改 package.json）

命令标题在 `package.json` 保持中文不变，不纳入本次范围。

---

## 6. 文件变更清单

| 变更类型 | 文件 | 说明 |
|----------|------|------|
| 新增 | `src/i18n/messages.ts` | 核心 i18n 模块 |
| 新增 | `src/i18n/messages.test.ts` | 消息完整性测试 |
| 修改 | `src/extension.ts` | activate 中初始化语言 + 监听配置变更 |
| 修改 | `src/activation/commands.ts` | 通知/进度条/QuickPick 文案替换为 t() |
| 修改 | `src/views/setupView.ts` | 设置面板 HTML 生成用 t()，语言下拉即时生效 |
| 修改 | `src/panel/webview.ts` | 审查报告 HTML 生成用 t()，监听语言变化重渲染 |
| 修改 | `src/views/import-preview.ts` | 导入预览 HTML 用 t() |
| 修改 | `src/utils/report.ts` | 报告生成用 t() |
| 修改 | `src/adapters/pmd.ts` | 错误消息替换 |
| 修改 | `src/adapters/sql-lint.ts` | 错误消息替换 |
| 修改 | `src/ai/engine.ts` | 错误消息替换（提示词不修改） |
| 修改 | `src/ai/providers/openai-compatible.ts` | 错误消息替换 |
| 修改 | `src/rules/import-service.ts` | 错误消息替换 |
| 修改 | `src/rules/converters/excel-converter.ts` | 错误消息替换 |
| 修改 | `src/rules/converters/docx-converter.ts` | 错误消息替换 |
| 修改 | `src/rules/converters/pptx-converter.ts` | 错误消息替换 |

---

## 7. 实现顺序

1. 创建 `src/i18n/messages.ts`（核心模块 + 全部消息注册）
2. 编写 `messages.test.ts`（验证三种语言完整性）
3. 改造 `src/extension.ts`（init + onDidChangeConfiguration）
4. 改造 `src/activation/commands.ts`
5. 改造 `src/panel/webview.ts`
6. 改造 `src/views/setupView.ts`
7. 改造 `src/views/import-preview.ts`
8. 改造 `src/utils/report.ts`
9. 改造 `src/adapters/pmd.ts`、`sql-lint.ts`
10. 改造 `src/ai/engine.ts`、`openai-compatible.ts`
11. 改造各 converter 错误消息
12. 运行 `npm test` 验证

---

## 8. 边界处理

| 场景 | 处理 |
|------|------|
| 某个 key 不存在于 messages | fallback zh-CN，再 fallback 返回 key 本身 |
| 某条消息缺某种语言翻译 | fallback zh-CN |
| 传入非法语言值 | TypeScript 类型系统 `Language` 防止编译时错误 |
| setLanguage 同语言重复调 | 短路 return，不触发事件 |
| 切换语言时 webview 未打开 | 下次打开 webview 时取当前语言渲染，无影响 |
| 切换语言时正在显示通知 | 已显示的通知不更新，下次通知用新语言 |

---

## 9. 验证标准

- 在设置面板切语言后：设置面板文字立即变，审查报告文字立即变
- 重新触发审查：通知/进度条用新语言
- 导出报告：报告标题和标签用新语言
- 重启 VS Code：语言保持上次设置的值
- AI 审查：提示词不变，审查质量不退化