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

适配器面板 UI + 配置文件模板 i18n 设计书

• 项目: vscode-code-reviewer
• 日期: 2026-07-28
• 设计范围: 适配器面板 UI 文本 + 配置文件模板注释的国际化接入

---

01 问题

适配器优化引入的新 UI 文本和配置文件模板注释为硬编码中文，未走 t() 通路，英文/日语用户看到的是中文文本。

涉及范围：

1. setupView.ts HTML 模板中 3 处硬编码（tooltip、图例、子标题）
2. setupView.js 前端渲染中 ~8 处硬编码（徽章、按钮、标签、tooltip）
3. setupView.ts 配置文件模板常量中 ~9 处中文注释

---

02 方案

2.1 数据流

用户切换语言 → pushConfig() 发送 initConfig 消息
  ├─ 已有字段：config, providers, ruleFiles, adapterStatus
  └─ 新增字段：i18n（包含前端需要的全部翻译文本）

setupView.js 从 msg.i18n.* 读取文本，不再硬编码

2.2 setupView.ts HTML 模板变更

直接在 getHtml() 模板字符串中将硬编码文本替换为 ${t('key')}，与现有 pattern 一致。

涉及键：

位置	当前文本	i18n 键
data-tooltip	点击展开/收起静态分析适配器	setup.adapter.tooltipTab
.engine-subtitle	静态分析适配器	setup.adapter.subtitle
.mode-legend-item 图例 x3	内置规则 / 项目配置 / 全局配置	setup.adapter.modeBuiltin / modeProject / modeGlobal
.mode-legend-desc	插件按 内置<全局<项目的优先级...	setup.adapter.modeLegend

2.3 setupView.js 前端变更

pushConfig() 在 initConfig 消息中新增 i18n 对象：

// pushConfig() 中
this._view.webview.postMessage({
  type: 'initConfig',
  // ... 现有字段 ...
  i18n: {
    configured: t('setup.configured'),
    notConfigured: t('setup.notConfigured'),
    connected: t('setup.connected'),
    retry: t('setup.retry'),
    saveTest: t('setup.saveAndTest'),
    ruleCount: t('setup.ruleCountFormat'),
    noRuleFiles: t('setup.noRuleFiles'),
    // 适配器相关
    modeBuiltin: t('setup.adapter.modeBuiltin'),
    modeProject: t('setup.adapter.modeProject'),
    modeGlobal: t('setup.adapter.modeGlobal'),
    configYes: t('setup.adapter.configYes'),
    configNo: t('setup.adapter.configNo'),
    langLabel: t('setup.adapter.langLabel'),
    btnCreateConfig: t('setup.adapter.btnCreateConfig'),
    btnEditGlobal: t('setup.adapter.btnEditGlobal'),
    tooltipCreatePrefix: t('setup.adapter.tooltipCreate'),
    tooltipEdit: t('setup.adapter.tooltipEdit'),
    tooltipToggleEnable: t('setup.adapter.toggleEnable'),
    tooltipToggleDisable: t('setup.adapter.toggleDisable'),
  },
});

setupView.js 中所有 '硬编码文本' 替换为 msg.i18n.xxx。

2.4 配置文件模板变更

四个模板常量从静态字符串改为运行时函数，使用 t() 生成注释：

function getPmdRulesetTemplate(): string {
  return `<?xml version="1.0" encoding="UTF-8"?>
<ruleset ...>
  <description>Custom PMD Ruleset</description>
  <!-- ${t('setup.template.pmdBestPractices')} -->
  <rule ref="category/java/bestpractices.xml" />
  <!-- ${t('setup.template.pmdCodeStyle')} -->
  <rule ref="category/java/codestyle.xml" />
</ruleset>`;
}

ADAPTER_METADATA 中的 configFileTemplate 改为 getter 函数（() => string），handleAdapterConfig() 在写入时调用。

2.5 修复已有硬编码

顺便修复 setupView.js 中已有的硬编码字符串：

行	当前文本	i18n 键
131, 136	'已配置' / '未配置'	setup.configured / setup.notConfigured (已存在)
142	'✓ 已连接'	setup.connected
144	'✗ 重试'	setup.retry
146	'保存并测试连接'	setup.saveAndTest (已存在)
153	'{n} 个文件'	setup.ruleCountFormat
161	'0 个文件'	同上
163	'暂无规则文件'	setup.noRuleFiles

---

03 新增 i18n 键清单

面板 UI（约12条）

键	zh-CN	en	ja
setup.configured	已配置	Configured	設定済み
setup.connected	✓ 已连接	✓ Connected	✓ 接続済み
setup.retry	✗ 重试	✗ Retry	✗ 再試行
setup.ruleCountFormat	{0} 个文件	{0} file(s)	{0} ファイル
setup.noRuleFiles	暂无规则文件	No rule files	ルールファイルなし
setup.adapter.subtitle	静态分析适配器	Static Analysis Adapters	静的解析アダプター
setup.adapter.modeBuiltin	内置规则	Built-in Rules	組み込みルール
setup.adapter.modeProject	项目配置	Project Config	プロジェクト設定
setup.adapter.modeGlobal	全局配置	Global Config	グローバル設定
setup.adapter.modeLegend	插件按 内置<全局<项目的优先级自动选择配置来源	Auto-selects config by priority: Built-in < Global < Project	優先順位に従って自動選択: 組み込み < グローバル < プロジェクト
setup.adapter.configYes	已配置	Configured	設定済み
setup.adapter.configNo	未配置	Not configured	未設定
setup.adapter.langLabel	可审查的语言：	Languages:	対応言語：
setup.adapter.tooltipTab	点击展开/收起静态分析适配器	Click to expand/collapse static analysis adapters	クリックで静的解析アダプターを展開/折りたたむ
setup.adapter.btnCreateConfig	创建项目配置	Create Project Config	プロジェクト設定を作成
setup.adapter.btnEditGlobal	修改全局设置	Modify Global Settings	グローバル設定を変更
setup.adapter.tooltipCreate	在项目根目录创建 {0}	Create {0} in project root	プロジェクトルートに {0} を作成
setup.adapter.tooltipEdit	修改 VS Code 设置中的全局参数	Modify global parameters in VS Code settings	VS Code設定のグローバルパラメータを変更
setup.adapter.toggleEnable	启用 {0} 适配器	Enable {0} adapter	{0} アダプターを有効化
setup.adapter.toggleDisable	禁用 {0} 适配器	Disable {0} adapter	{0} アダプターを無効化

模板注释（约6条）

键	zh-CN	en	ja
setup.template.pmdBestPractices	Java 最佳实践（如：避免空 catch、关闭流等）	Java best practices (avoid empty catch, close streams, etc.)	Javaベストプラクティス（空のcatch回避、ストリームクローズ等）
setup.template.pmdCodeStyle	Java 代码风格（如：命名规范、花括号位置等）	Java code style (naming conventions, brace placement, etc.)	Javaコードスタイル（命名規則、ブレース位置等）
setup.template.sqlfluffDialect	数据库方言：postgres / mysql / bigquery / snowflake 等	Database dialect: postgres / mysql / bigquery / snowflake etc.	データベース方言：postgres / mysql / bigquery / snowflake など
setup.template.sqlfluffRules	all = 启用全部规则，也可指定规则名逗号分隔	all = enable all rules, or specify rule names separated by commas	all = すべてのルールを有効、ルール名をカンマ区切りで指定可
setup.template.eslintComment1	未使用的变量 → 警告	Unused variables → warning	未使用変数 → 警告
setup.template.eslintComment2	允许使用 console	Allow console	consoleを許可
setup.template.eslintComment3	强制分号	Enforce semicolons	セミコロンを強制
setup.template.stylelintComment1	缩进 2 空格	Indentation: 2 spaces	インデント: 2スペース
setup.template.stylelintComment2	禁止空规则	No empty rules	空ルールを禁止

---

04 文件变更清单

文件	变更类型	说明
src/i18n/messages.ts	修改	新增 ~28 条 i18n 键（面板 UI + 模板注释）
src/views/setupView.ts	修改	HTML 模板硬编码替换为 t()；模板常量改为函数
src/views/setupView.js	修改	从 msg.i18n 读取文本替换全篇硬编码字符串

零破坏性原则：不修改任何现有 i18n 键，不修改现有逻辑分支，不修改 HTML 结构/JS 事件绑定逻辑。

---

05 风险与注意事项

• ADAPTER_METADATA 中 configFileTemplate 的类型从 string 改为 () => string，调用方 handleAdapterConfig() 需相应调整
• 部分键与已有键重复（如 setup.configured / setup.notConfigured），需确认是否复用现有 setup.notConfigured
• 模板中 XML/JS 注释 <!-- --> / // / # 本身不翻译，仅注释内容翻译