范智鹏
effcf30802
- 适配器 i18n 接入（eslint/pmd/sql-lint/stylelint） - Provider 动态注册机制（registry.ts + providers.json + factory 重构） - SetupView 全面重构（setupView.ts 新增 600+ 行） - i18n 消息扩展（messages.ts +210 行） - 规则导入流程优化（import-service / prompt-builder） - 新增 PMD jars 依赖及测试用例
175 lines
8.6 KiB
Markdown
175 lines
8.6 KiB
Markdown
# 适配器面板 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` 对象：
|
|
|
|
```typescript
|
|
// 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()` 生成注释：
|
|
|
|
```typescript
|
|
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 注释 `<!-- -->` / `//` / `#` 本身不翻译，仅注释内容翻译
|