search-syntax-pro/.claude/specs/add-russian-korean-i18n/requirements-confirm.md

# 需求确认文档 - 添加俄语和韩语国际化支持

## 原始需求
"目前项目的国际化语言中只支持中文和英文，我希望再扩展支持俄语和韩语，请你评估一下"

## 用户澄清回答 (第一轮)

1. **翻译方式**: AI自动翻译,通过对比中英文和功能位置判断正确性
2. **语言变体**: 标准俄语(ru-RU) 和 韩国韩语(ko-KR)
3. **翻译策略**: 尽量缩短翻译文本(适应UI空间限制)
4. **发布计划**: 两种语言同时发布
5. **范围限定**: 仅翻译界面文本,搜索引擎内容语言选项无需翻译

## 仓库上下文应用

### 项目架构
- **类型**: Chrome浏览器扩展 (Manifest V3)
- **技术栈**: React 18 + TypeScript 5 + Vite 5
- **现有语言**: 简体中文(zh-CN)、英语(en-US)

### 双层i18n系统
1. **Chrome Extension i18n API**
   - 文件: `/public/_locales/{locale}/messages.json`
   - 数量: 14条消息/语言
   - 用途: manifest名称、页面标题、右键菜单

2. **React自定义i18n系统**
   - 文件: `/src/i18n/translations.ts`
   - 数量: 518条翻译/语言
   - 特点: 三级命名空间、变量插值、TypeScript类型安全

### 翻译工作量
- Chrome i18n: 14条 × 2语言 = 28条
- React i18n: 518条 × 2语言 = 1036条
- **总计**: 1064条翻译条目

## 需求质量评分 (第一轮)

### 功能清晰度 (30分)
- ✅ 明确输入输出: 中英文参考 → 俄韩译文
- ✅ 用户交互: 无需用户参与翻译过程
- ✅ 成功标准: 对比验证翻译准确性
- **得分**: 28/30 (缺少翻译质量的具体阈值)

### 技术特异性 (25分)
- ✅ 集成点: 双层i18n系统
- ✅ 技术约束: 保持变量插值格式
- ⚠️ 性能需求: 未明确翻译生成速度要求
- **得分**: 22/25

### 实现完整性 (25分)
- ✅ 边界情况: 文本长度限制(尽量缩短)
- ✅ 错误处理: 对比中英文判断正确性
- ⚠️ 数据验证: 未明确变量占位符验证规则
- **得分**: 21/25

### 业务上下文 (20分)
- ✅ 用户价值: 支持俄语和韩语用户
- ✅ 优先级: 同时发布两种语言
- ✅ 范围边界: 排除搜索内容语言
- **得分**: 20/20

**总分**: 91/100 ✅

## 用户确认 (第二轮 - 推荐方案)

✅ **用户选择**: 采用所有推荐方案

**推荐方案详情**:
1. **翻译审核**: ✅ 生成Markdown对照表,重点审核关键按钮和错误提示
2. **文本长度控制**: ✅ 优先使用缩写和简洁表达 (策略B)
3. **变量验证**: ✅ 自动检查所有 `{变量名}` 在翻译中保持完整
4. **构建测试**: ✅ 自动运行 `npm run build` 验证无类型错误
5. **文档同步**: ✅ 同步更新 README.md 的支持语言列表

## 最终确认需求 (质量评分: 96/100)

### 核心功能
**添加俄语(ru-RU)和韩语(ko-KR)国际化支持到Chrome扩展项目**

### 详细质量评分

**功能清晰度 (30/30)** ✅
- ✅ 输入输出: 中英文参考 → AI生成俄韩译文 → 对照表审核
- ✅ 用户交互: 自动生成 + Markdown审核表格
- ✅ 成功标准: 构建通过 + 变量验证 + 人工抽查关键文本

**技术特异性 (25/25)** ✅
- ✅ 集成点: 双层i18n系统 + TypeScript类型系统
- ✅ 技术约束: 变量插值格式 + 文本简洁优化
- ✅ 性能需求: 自动化验证,构建时检查

**实现完整性 (25/25)** ✅
- ✅ 边界情况: 文本长度优化策略 + 变量占位符自动验证
- ✅ 错误处理: 构建验证 + 对照表人工审核机制
- ✅ 数据验证: 自动检查变量完整性 + TypeScript类型检查

**业务上下文 (16/20)** ⚠️
- ✅ 用户价值: 支持俄韩语用户群体
- ✅ 优先级: 同时发布两种语言
- ⚠️ 缺少上线后的用户反馈机制 (-4分)

---

### 实施步骤

#### Step 1: TypeScript类型更新
```typescript
// src/types/index.ts
export type Language = 'zh-CN' | 'en-US' | 'ru-RU' | 'ko-KR'
```

#### Step 2: Chrome Extension i18n文件
创建两个新文件,参照 `public/_locales/en/messages.json` 结构:
- `/public/_locales/ru/messages.json` (14条消息)
- `/public/_locales/ko/messages.json` (14条消息)

**翻译策略**:
- 基于英文版本翻译 (更简洁准确)
- 保持JSON结构: `{"key": {"message": "...", "description": "..."}}`
- 优先使用简洁表达

#### Step 3: React i18n翻译
在 `src/i18n/translations.ts` 中添加:

```typescript
export const translations = {
  'zh-CN': { /* 现有518条 */ },
  'en-US': { /* 现有518条 */ },
  'ru-RU': {
    /* 新增518条俄语翻译 */
    // 基于zh-CN和en-US对照生成
    // 保持三级命名空间结构 (例: common.button.confirm)
    // 保留所有 {变量名} 插值
    // 优先简洁表达
  },
  'ko-KR': {
    /* 新增518条韩语翻译 */
    // 同上
  }
}
```

**翻译原则**:
1. **功能性文本** (按钮、菜单、标签): 准确性优先
2. **描述性文本** (提示、说明): 简洁优先,可适度缩减
3. **变量插值**: 必须保留完整的 `{变量名}` 格式
4. **语序调整**: 允许根据俄韩语语法调整变量位置,但变量名必须一致

#### Step 4: 自动化验证

**变量完整性检查**:
- 对比 `en-US` 和新语言的每个翻译键
- 提取所有 `{变量名}` 占位符
- 确保变量名称完全一致 (数量和名称)
- 如发现不匹配,立即报错

**构建验证**:
```bash
npm run build
```
验证要求:
1. TypeScript类型检查通过
2. dist目录包含所有4种语言文件
3. 无构建错误或警告

#### Step 5: 生成审核对照表

创建 `translation-review.md` 包含:

**优先审核部分** (必查):
- 所有按钮文本 (确认/取消/搜索/设置等)
- 所有错误提示信息
- 搜索引擎名称翻译
- 右键菜单项

**抽查部分** (10%随机):
- 常规界面文本
- 描述性提示文本

**表格格式**:
| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|------|------|------|------|------|------|------|
| common.button.confirm | 确认 | Confirm | Подтвердить | 확인 | - | ✅ |
| search.result.count | {count}条结果 | {count} results | {count} результатов | {count}개 결과 | {count} | ✅ |

#### Step 6: 文档同步更新

**README.md**:
```markdown
## 🌍 支持语言 / Supported Languages

- 🇨🇳 简体中文 (zh-CN)
- 🇺🇸 English (en-US)
- 🇷🇺 Русский (ru-RU)  ← 新增
- 🇰🇷 한국어 (ko-KR)     ← 新增
```

### 排除范围
- ❌ 搜索引擎适配器中的内容语言选项 (已存在,无需修改)
- ❌ 后端API响应内容
- ❌ 代码注释和开发文档

### 质量保证清单

**自动化验证** (必须全部通过):
- [ ] TypeScript类型检查通过
- [ ] 所有翻译键完整覆盖 (518条 × 2语言)
- [ ] 变量占位符格式验证通过 (所有 `{变量名}` 一致)
- [ ] `npm run build` 成功
- [ ] dist目录包含4种语言文件

**人工审核** (基于对照表):
- [ ] 关键按钮翻译准确 (确认/取消/搜索/设置等)
- [ ] 错误提示翻译清晰易懂
- [ ] 搜索引擎名称翻译正确
- [ ] 抽查10%常规文本无明显错误
- [ ] README.md语言列表已更新

### 交付物清单
1. ✅ 修改后的 `src/types/index.ts`
2. ✅ 新建的 `public/_locales/ru/messages.json` (14条)
3. ✅ 新建的 `public/_locales/ko/messages.json` (14条)
4. ✅ 更新的 `src/i18n/translations.ts` (添加ru-RU和ko-KR共1036条)
5. ✅ 翻译对照表 `.claude/specs/add-russian-korean-i18n/translation-review.md`
6. ✅ 更新的 `README.md`
7. ✅ 构建验证报告

### 成功标准
- ✅ 所有自动化验证通过
- ✅ 关键文本人工审核通过 (基于对照表)
- ✅ 构建成功且无警告
- ✅ 文档同步更新完成
- ✅ 可直接发布到Chrome Web Store

---

## 最终确认

**需求质量评分**: 96/100 ✅
**评分构成**:
- 功能清晰度: 30/30
- 技术特异性: 25/25
- 实现完整性: 25/25
- 业务上下文: 16/20

**状态**: ✅ 需求已完全明确,已达到实施标准 (超过90分阈值)

---

## 🛑 用户批准检查点

**需求摘要**:
添加俄语(ru-RU)和韩语(ko-KR)国际化支持,共1064条翻译,包含:
- 双层i18n系统 (Chrome API + React自定义)
- AI辅助翻译 + 人工审核机制
- 自动化验证 (变量检查 + 构建测试)
- 文档同步更新

**集成方式**:
- 完全遵循现有双层i18n架构
- 保持三级命名空间结构
- TypeScript类型安全
- 自动化构建流程

**需求已明确 (96分质量分数)。是否开始实施?**

请回复 **"yes"** / **"确认"** / **"proceed"** / **"continue"** 开始实施

或回复 **"no"** / 提出修改意见 以继续完善需求