镜像自地址
https://github.com/lhly/search-syntax-pro.git
已同步 2026-10-20 14:27:47 +08:00
19525d16cd
- 更新 Language 类型定义，新增 ru-RU 和 ko-KR 支持 - 添加俄语和韩语的 Chrome i18n 消息文件 - 在 translations.ts 中新增俄语和韩语翻译 - 更新 README 文档中的支持语言列表 - 版本号升级至 1.8.7
271 行
8.4 KiB
Markdown
271 行
8.4 KiB
Markdown
# 需求确认文档 - 添加俄语和韩语国际化支持
|
||
|
||
## 原始需求
|
||
"目前项目的国际化语言中只支持中文和英文，我希望再扩展支持俄语和韩语，请你评估一下"
|
||
|
||
## 用户澄清回答 (第一轮)
|
||
|
||
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"** / 提出修改意见 以继续完善需求
|