镜像自地址
https://github.com/lhly/search-syntax-pro.git
已同步 2026-10-20 06:17:47 +08:00
19525d16cd
- 更新 Language 类型定义，新增 ru-RU 和 ko-KR 支持 - 添加俄语和韩语的 Chrome i18n 消息文件 - 在 translations.ts 中新增俄语和韩语翻译 - 更新 README 文档中的支持语言列表 - 版本号升级至 1.8.7
8.4 KiB
8.4 KiB
需求确认文档 - 添加俄语和韩语国际化支持
原始需求
"目前项目的国际化语言中只支持中文和英文，我希望再扩展支持俄语和韩语，请你评估一下"
用户澄清回答 (第一轮)
- 翻译方式: AI自动翻译,通过对比中英文和功能位置判断正确性
- 语言变体: 标准俄语(ru-RU) 和 韩国韩语(ko-KR)
- 翻译策略: 尽量缩短翻译文本(适应UI空间限制)
- 发布计划: 两种语言同时发布
- 范围限定: 仅翻译界面文本,搜索引擎内容语言选项无需翻译
仓库上下文应用
项目架构
- 类型: Chrome浏览器扩展 (Manifest V3)
- 技术栈: React 18 + TypeScript 5 + Vite 5
- 现有语言: 简体中文(zh-CN)、英语(en-US)
双层i18n系统
-
Chrome Extension i18n API
- 文件:
/public/_locales/{locale}/messages.json - 数量: 14条消息/语言
- 用途: manifest名称、页面标题、右键菜单
- 文件:
-
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 ✅
用户确认 (第二轮 - 推荐方案)
✅ 用户选择: 采用所有推荐方案
推荐方案详情:
- 翻译审核: ✅ 生成Markdown对照表,重点审核关键按钮和错误提示
- 文本长度控制: ✅ 优先使用缩写和简洁表达 (策略B)
- 变量验证: ✅ 自动检查所有
{变量名}在翻译中保持完整 - 构建测试: ✅ 自动运行
npm run build验证无类型错误 - 文档同步: ✅ 同步更新 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类型更新
// 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 中添加:
export const translations = {
'zh-CN': { /* 现有518条 */ },
'en-US': { /* 现有518条 */ },
'ru-RU': {
/* 新增518条俄语翻译 */
// 基于zh-CN和en-US对照生成
// 保持三级命名空间结构 (例: common.button.confirm)
// 保留所有 {变量名} 插值
// 优先简洁表达
},
'ko-KR': {
/* 新增518条韩语翻译 */
// 同上
}
}
翻译原则:
- 功能性文本 (按钮、菜单、标签): 准确性优先
- 描述性文本 (提示、说明): 简洁优先,可适度缩减
- 变量插值: 必须保留完整的
{变量名}格式 - 语序调整: 允许根据俄韩语语法调整变量位置,但变量名必须一致
Step 4: 自动化验证
变量完整性检查:
- 对比
en-US和新语言的每个翻译键 - 提取所有
{变量名}占位符 - 确保变量名称完全一致 (数量和名称)
- 如发现不匹配,立即报错
构建验证:
npm run build
验证要求:
- TypeScript类型检查通过
- dist目录包含所有4种语言文件
- 无构建错误或警告
Step 5: 生成审核对照表
创建 translation-review.md 包含:
优先审核部分 (必查):
- 所有按钮文本 (确认/取消/搜索/设置等)
- 所有错误提示信息
- 搜索引擎名称翻译
- 右键菜单项
抽查部分 (10%随机):
- 常规界面文本
- 描述性提示文本
表格格式:
| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|---|---|---|---|---|---|---|
| common.button.confirm | 确认 | Confirm | Подтвердить | 확인 | - | ✅ |
| search.result.count | {count}条结果 | {count} results | {count} результатов | {count}개 결과 | {count} | ✅ |
Step 6: 文档同步更新
README.md:
## 🌍 支持语言 / Supported Languages
- 🇨🇳 简体中文 (zh-CN)
- 🇺🇸 English (en-US)
- 🇷🇺 Русский (ru-RU) ← 新增
- 🇰🇷 한국어 (ko-KR) ← 新增
排除范围
- ❌ 搜索引擎适配器中的内容语言选项 (已存在,无需修改)
- ❌ 后端API响应内容
- ❌ 代码注释和开发文档
质量保证清单
自动化验证 (必须全部通过):
- TypeScript类型检查通过
- 所有翻译键完整覆盖 (518条 × 2语言)
- 变量占位符格式验证通过 (所有
{变量名}一致) npm run build成功- dist目录包含4种语言文件
人工审核 (基于对照表):
- 关键按钮翻译准确 (确认/取消/搜索/设置等)
- 错误提示翻译清晰易懂
- 搜索引擎名称翻译正确
- 抽查10%常规文本无明显错误
- README.md语言列表已更新
交付物清单
- ✅ 修改后的
src/types/index.ts - ✅ 新建的
public/_locales/ru/messages.json(14条) - ✅ 新建的
public/_locales/ko/messages.json(14条) - ✅ 更新的
src/i18n/translations.ts(添加ru-RU和ko-KR共1036条) - ✅ 翻译对照表
.claude/specs/add-russian-korean-i18n/translation-review.md - ✅ 更新的
README.md - ✅ 构建验证报告
成功标准
- ✅ 所有自动化验证通过
- ✅ 关键文本人工审核通过 (基于对照表)
- ✅ 构建成功且无警告
- ✅ 文档同步更新完成
- ✅ 可直接发布到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" / 提出修改意见 以继续完善需求