镜像自地址 https://github.com/lhly/search-syntax-pro.git 已同步 2026-10-20 22:37:48 +08:00

Zain 19525d16cd feat(i18n): 添加俄语和韩语国际化支持

- 更新 Language 类型定义，新增 ru-RU 和 ko-KR 支持
- 添加俄语和韩语的 Chrome i18n 消息文件
- 在 translations.ts 中新增俄语和韩语翻译
- 更新 README 文档中的支持语言列表
- 版本号升级至 1.8.7

2025-12-09 10:50:05 +08:00

27 KiB

原始文件 Blame 文件历史

技术规范 - 添加俄语和韩语国际化支持

项目: SearchSyntax Pro 版本: 1.8.6 规范生成时间: 2025-12-03 需求质量评分: 96/100

1. 实施概览

1.1 核心任务

添加俄语(ru-RU)和韩语(ko-KR)国际化支持到Chrome扩展项目,总计1064条翻译。

1.2 技术架构

双层i18n系统:

Chrome Extension i18n API: 28条 (14条×2语言)
React自定义i18n: 1036条 (518条×2语言)

1.3 实施原则

✅ AI辅助翻译 + 人工审核关键文本
✅ 优先简洁表达,适应UI空间
✅ 自动验证变量完整性
✅ 构建验证确保类型安全
✅ 文档同步更新

2. 详细实施步骤

Step 1: TypeScript类型定义更新

文件位置

/Users/lhly/chromeex/ssp/src/types/index.ts:339

当前代码

export type Language = 'zh-CN' | 'en-US';

修改后代码

export type Language = 'zh-CN' | 'en-US' | 'ru-RU' | 'ko-KR';

验证方法

# TypeScript类型检查
npx tsc --noEmit

Step 2: Chrome Extension i18n文件创建

2.1 创建俄语文件

文件路径: /Users/lhly/chromeex/ssp/public/_locales/ru/messages.json

完整内容:

{
  "app_name": {
    "message": "SearchSyntax Pro",
    "description": "SearchSyntax Pro - Advanced Search Syntax Tool"
  },
  "app_description": {
    "message": "Инструмент визуализации расширенного синтаксиса поиска для упрощения использования",
    "description": "App description"
  },
  "search_keyword": {
    "message": "Ключевое слово",
    "description": "Search keyword input label"
  },
  "search_button": {
    "message": "Поиск",
    "description": "Search button text"
  },
  "site_search": {
    "message": "Поиск по сайту",
    "description": "Site search function label"
  },
  "site_placeholder": {
    "message": "Введите домен, напр. example.com",
    "description": "Website domain input placeholder"
  },
  "file_type_search": {
    "message": "Поиск по типу файла",
    "description": "File type search function label"
  },
  "file_type_placeholder": {
    "message": "Выберите или введите тип, напр. PDF",
    "description": "File type input placeholder"
  },
  "query_preview": {
    "message": "Предпросмотр запроса",
    "description": "Query preview label"
  },
  "search_history": {
    "message": "История поиска",
    "description": "Search history label"
  },
  "clear_history": {
    "message": "Очистить историю",
    "description": "Clear history button"
  },
  "settings": {
    "message": "Настройки",
    "description": "Settings button label"
  },
  "default_engine": {
    "message": "Поисковик по умолчанию",
    "description": "Default search engine setting label"
  },
  "language": {
    "message": "Язык",
    "description": "Language setting label"
  },
  "enable_history": {
    "message": "Включить историю поиска",
    "description": "Enable search history toggle label"
  },
  "theme": {
    "message": "Тема",
    "description": "Theme setting label"
  },
  "light_theme": {
    "message": "Светлая",
    "description": "Light theme option"
  },
  "dark_theme": {
    "message": "Тёмная",
    "description": "Dark theme option"
  },
  "auto_theme": {
    "message": "Системная",
    "description": "Auto theme option"
  },
  "about": {
    "message": "О программе",
    "description": "About page label"
  },
  "version": {
    "message": "Версия",
    "description": "Version info label"
  },
  "author": {
    "message": "Автор",
    "description": "Author info label"
  },
  "export_data": {
    "message": "Экспорт данных",
    "description": "Export data button"
  },
  "import_data": {
    "message": "Импорт данных",
    "description": "Import data button"
  },
  "clear_all_data": {
    "message": "Очистить все данные",
    "description": "Clear all data button"
  },
  "popup_title": {
    "message": "SearchSyntax Pro",
    "description": "Popup window title"
  },
  "detached_title": {
    "message": "SearchSyntax Pro - Отдельное окно",
    "description": "Detached window title"
  },
  "options_title": {
    "message": "SearchSyntax Pro - Настройки",
    "description": "Options page title"
  }
}

2.2 创建韩语文件

文件路径: /Users/lhly/chromeex/ssp/public/_locales/ko/messages.json

完整内容:

{
  "app_name": {
    "message": "SearchSyntax Pro",
    "description": "SearchSyntax Pro - Advanced Search Syntax Tool"
  },
  "app_description": {
    "message": "고급 검색 구문 시각화 도구로 검색 사용의 진입 장벽을 낮춥니다",
    "description": "App description"
  },
  "search_keyword": {
    "message": "검색어",
    "description": "Search keyword input label"
  },
  "search_button": {
    "message": "검색",
    "description": "Search button text"
  },
  "site_search": {
    "message": "사이트 검색",
    "description": "Site search function label"
  },
  "site_placeholder": {
    "message": "도메인 입력, 예: example.com",
    "description": "Website domain input placeholder"
  },
  "file_type_search": {
    "message": "파일 형식 검색",
    "description": "File type search function label"
  },
  "file_type_placeholder": {
    "message": "형식 선택 또는 입력, 예: PDF",
    "description": "File type input placeholder"
  },
  "query_preview": {
    "message": "쿼리 미리보기",
    "description": "Query preview label"
  },
  "search_history": {
    "message": "검색 기록",
    "description": "Search history label"
  },
  "clear_history": {
    "message": "기록 지우기",
    "description": "Clear history button"
  },
  "settings": {
    "message": "설정",
    "description": "Settings button label"
  },
  "default_engine": {
    "message": "기본 검색 엔진",
    "description": "Default search engine setting label"
  },
  "language": {
    "message": "언어",
    "description": "Language setting label"
  },
  "enable_history": {
    "message": "검색 기록 활성화",
    "description": "Enable search history toggle label"
  },
  "theme": {
    "message": "테마",
    "description": "Theme setting label"
  },
  "light_theme": {
    "message": "밝게",
    "description": "Light theme option"
  },
  "dark_theme": {
    "message": "어둡게",
    "description": "Dark theme option"
  },
  "auto_theme": {
    "message": "시스템 따름",
    "description": "Auto theme option"
  },
  "about": {
    "message": "정보",
    "description": "About page label"
  },
  "version": {
    "message": "버전",
    "description": "Version info label"
  },
  "author": {
    "message": "개발자",
    "description": "Author info label"
  },
  "export_data": {
    "message": "데이터 내보내기",
    "description": "Export data button"
  },
  "import_data": {
    "message": "데이터 가져오기",
    "description": "Import data button"
  },
  "clear_all_data": {
    "message": "모든 데이터 지우기",
    "description": "Clear all data button"
  },
  "popup_title": {
    "message": "SearchSyntax Pro",
    "description": "Popup window title"
  },
  "detached_title": {
    "message": "SearchSyntax Pro - 별도 창",
    "description": "Detached window title"
  },
  "options_title": {
    "message": "SearchSyntax Pro - 설정",
    "description": "Options page title"
  }
}

2.3 翻译策略说明

简洁化原则:

"默认搜索引擎" → 俄语: "Поисковик по умолчанию" (标准表达)
"默认搜索引擎" → 韩语: "기본 검색 엔진" (简洁表达)
"清除" → 俄语: "Очистить" (动词形式)
"清除" → 韩语: "지우기" (名词化动词)

功能性文本优先准确:

按钮: "Search" → "Поиск" (俄) / "검색" (韩)
设置项: "Settings" → "Настройки" (俄) / "설정" (韩)

Step 3: React i18n翻译添加

文件位置

/Users/lhly/chromeex/ssp/src/i18n/translations.ts

当前结构

import type { Language } from '@/types'

const translations: Record<Language, Record<string, string>> = {
  'zh-CN': { /* 518条翻译 */ },
  'en-US': { /* 518条翻译 */ },
}

修改方式

在 translations 对象中添加两个新的语言对象:

const translations: Record<Language, Record<string, string>> = {
  'zh-CN': { /* 现有518条 */ },
  'en-US': { /* 现有518条 */ },
  'ru-RU': {
    // 新增518条俄语翻译
    // 以下为示例,完整列表见后续章节
    'common.languages.zh-CN': 'Упрощённый китайский',
    'common.languages.en-US': 'English',
    'common.languages.ru-RU': 'Русский',
    'common.languages.ko-KR': '한국어',
    'common.searchEngines.baidu': 'Baidu',
    'common.searchEngines.google': 'Google',
    'common.searchEngines.bing': 'Bing',
    // ... (完整518条)
  },
  'ko-KR': {
    // 新增518条韩语翻译
    'common.languages.zh-CN': '중국어 간체',
    'common.languages.en-US': 'English',
    'common.languages.ru-RU': 'Русский',
    'common.languages.ko-KR': '한국어',
    'common.searchEngines.baidu': 'Baidu',
    'common.searchEngines.google': 'Google',
    'common.searchEngines.bing': 'Bing',
    // ... (完整518条)
  },
}

翻译实施策略

基于中英文对照生成:

读取 zh-CN 和 en-US 的对应键值
对照分析功能上下文
生成简洁准确的俄韩语翻译
保留所有变量插值 {变量名}

变量插值处理:

识别模式: /\{[^}]+\}/g
规则: 变量名必须完全一致
语序: 可根据俄韩语语法调整变量位置

示例:

'zh-CN': '{count}条结果'
'en-US': '{count} results'
'ru-RU': '{count} результатов'  // 俄语: 数字在前
'ko-KR': '{count}개 결과'        // 韩语: 数字在前+量词

命名规范保持:

三级命名空间: 组件.子类.键
搜索引擎名称: 保持原始品牌名(不翻译)
文件类型: 使用通用技术术语

Step 4: 自动化验证机制

4.1 变量完整性检查脚本

创建临时验证脚本 (可选,用于开发阶段):

// verify-i18n-variables.js
const translations = require('./src/i18n/translations.ts').default;

function extractVariables(text) {
  const matches = text.match(/\{[^}]+\}/g);
  return matches ? matches.sort() : [];
}

function verifyTranslations() {
  const baseLanguage = 'en-US';
  const newLanguages = ['ru-RU', 'ko-KR'];
  const errors = [];

  const baseKeys = Object.keys(translations[baseLanguage]);

  newLanguages.forEach(lang => {
    baseKeys.forEach(key => {
      const baseText = translations[baseLanguage][key];
      const translatedText = translations[lang][key];

      if (!translatedText) {
        errors.push(`[${lang}] Missing key: ${key}`);
        return;
      }

      const baseVars = extractVariables(baseText);
      const transVars = extractVariables(translatedText);

      if (JSON.stringify(baseVars) !== JSON.stringify(transVars)) {
        errors.push(
          `[${lang}] Variable mismatch in "${key}":\n` +
          `  Expected: ${baseVars.join(', ')}\n` +
          `  Found: ${transVars.join(', ')}`
        );
      }
    });
  });

  if (errors.length > 0) {
    console.error('❌ Translation validation failed:\n');
    errors.forEach(err => console.error(err));
    process.exit(1);
  } else {
    console.log('✅ All translations validated successfully!');
  }
}

verifyTranslations();

4.2 TypeScript类型检查

# 编译检查(不生成文件)
npx tsc --noEmit

# 预期输出: 无错误
# 如果Language类型未更新,会报错

4.3 构建验证

# 执行完整构建
npm run build

# 验证检查点:
# 1. 构建成功无错误
# 2. dist/_locales/ru/messages.json 存在
# 3. dist/_locales/ko/messages.json 存在
# 4. dist目录包含所有4种语言文件

Step 5: 生成翻译对照表

文件路径

.claude/specs/add-russian-korean-i18n/translation-review.md

表格结构

5.1 优先审核区域 (必查)

## 🔴 优先审核: 按钮和操作

| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|------|------|------|------|------|------|------|
| common.save | 保存 | Save | Сохранить | 저장 | - | ⬜ |
| common.cancel | 取消 | Cancel | Отмена | 취소 | - | ⬜ |
| common.apply | 应用到搜索框 | Apply to search box | Применить | 검색창에 적용 | - | ⬜ |
| common.close | 关闭 (ESC) | Close (ESC) | Закрыть (ESC) | 닫기 (ESC) | - | ⬜ |
| common.edit | 编辑 | Edit | Редактировать | 편집 | - | ⬜ |
| common.reset | 重置 | Reset | Сбросить | 초기화 | - | ⬜ |

## 🟠 优先审核: 错误和提示

| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|------|------|------|------|------|------|------|
| copyButton.copyError | 复制失败 | Copy failed | Ошибка копирования | 복사 실패 | - | ⬜ |
| popup.noSearchEngineError | 未选择搜索引擎 | No search engine selected | Не выбран поисковик | 검색 엔진 미선택 | - | ⬜ |

## 🟡 优先审核: 搜索引擎名称

| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|------|------|------|------|------|------|------|
| common.searchEngines.baidu | 百度 | Baidu | Baidu | Baidu | - | ⬜ |
| common.searchEngines.google | 谷歌 | Google | Google | Google | - | ⬜ |
| common.searchEngines.twitter | X (Twitter) | X (Twitter) | X (Twitter) | X (Twitter) | - | ⬜ |

## 🟢 抽查: 变量插值文本 (10%随机)

| 键名 | 中文 | 英文 | 俄语 | 韩语 | 变量 | 状态 |
|------|------|------|------|------|------|------|
| popup.currentEngine | 当前引擎: {engine} | Current engine: {engine} | Поисковик: {engine} | 현재 엔진: {engine} | {engine} | ⬜ |
| options.exportSuccess | 已导出 {count} 条记录 | Exported {count} records | Экспортировано {count} | {count}개 내보냄 | {count} | ⬜ |

## 📝 审核说明

**状态标记**:
- ⬜ 待审核
- ✅ 通过
- ⚠️ 需修改
- ❌ 严重错误

**审核重点**:
1. 功能性文本(按钮/菜单): 准确性优先
2. 错误提示: 清晰易懂
3. 搜索引擎名称: 保持品牌一致性
4. 变量插值: 确保 {变量名} 完全一致
5. 文本长度: 是否适合UI显示

**修改建议格式**:
- 键名: common.save
- 问题: 俄语文本过长
- 建议: "Сохранить" → "Сохр."

5.2 生成方式

使用脚本自动生成对照表骨架:

// generate-review-table.js
const translations = require('./src/i18n/translations.ts').default;

const priorityKeys = [
  // 按钮和操作
  'common.save', 'common.cancel', 'common.apply', 'common.close',
  'common.edit', 'common.reset',
  // 错误提示
  'copyButton.copyError', 'popup.noSearchEngineError',
  // 搜索引擎名称 (前3个)
  'common.searchEngines.baidu', 'common.searchEngines.google', 'common.searchEngines.twitter',
];

// 生成Markdown表格
priorityKeys.forEach(key => {
  const zhCN = translations['zh-CN'][key] || '';
  const enUS = translations['en-US'][key] || '';
  const ruRU = translations['ru-RU'][key] || '';
  const koKR = translations['ko-KR'][key] || '';
  const vars = extractVariables(enUS).join(', ') || '-';

  console.log(`| ${key} | ${zhCN} | ${enUS} | ${ruRU} | ${koKR} | ${vars} | ⬜ |`);
});

Step 6: 文档同步更新

6.1 更新README.md

文件路径: /Users/lhly/chromeex/ssp/README.md

修改位置: 查找 "支持语言" 或 "Supported Languages" 章节

修改前:

## 支持语言

- 🇨🇳 简体中文 (zh-CN)
- 🇺🇸 English (en-US)

修改后:

## 🌍 支持语言 / Supported Languages

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

6.2 检查manifest.json

文件路径: /Users/lhly/chromeex/ssp/public/manifest.json

检查项:

default_locale 是否正确设置 (通常是 "en")
name 和 description 是否使用 __MSG_app_name__ 格式

示例:

{
  "manifest_version": 3,
  "name": "__MSG_app_name__",
  "description": "__MSG_app_description__",
  "default_locale": "en",
  ...
}

6.3 更新package.json (可选)

如果package.json包含描述字段:

{
  "name": "search-syntax-pro",
  "version": "1.8.6",
  "description": "Search Syntax Visualizer - 支持中英俄韩四语言",
  ...
}

3. 完整翻译键值对照表 (核心示例)

3.1 语言名称翻译

// 在translations对象中
'ru-RU': {
  'common.languages.zh-CN': 'Упрощённый китайский',
  'common.languages.en-US': 'English',
  'common.languages.ru-RU': 'Русский',
  'common.languages.ko-KR': '한국어',
}

'ko-KR': {
  'common.languages.zh-CN': '중국어 간체',
  'common.languages.en-US': 'English',
  'common.languages.ru-RU': 'Русский',
  'common.languages.ko-KR': '한국어',
}

3.2 搜索引擎名称 (保持原名)

'ru-RU': {
  'common.searchEngines.baidu': 'Baidu',
  'common.searchEngines.google': 'Google',
  'common.searchEngines.bing': 'Bing',
  'common.searchEngines.twitter': 'X (Twitter)',
  'common.searchEngines.duckduckgo': 'DuckDuckGo',
  'common.searchEngines.brave': 'Brave Search',
  'common.searchEngines.yandex': 'Yandex',
  'common.searchEngines.reddit': 'Reddit',
  'common.searchEngines.github': 'GitHub',
  'common.searchEngines.stackoverflow': 'Stack Overflow',
  'common.searchEngines.yahoo': 'Yahoo',
  'common.searchEngines.startpage': 'Startpage',
  'common.searchEngines.ecosia': 'Ecosia',
  'common.searchEngines.qwant': 'Qwant',
  'common.searchEngines.naver': 'Naver',
  'common.searchEngines.sogou': 'Sogou',
  'common.searchEngines.so360': '360 Search',
}

// 韩语相同
'ko-KR': { /* 同上 */ }

3.3 文件类型翻译

'ru-RU': {
  'common.fileTypes.pdf': 'PDF-документ',
  'common.fileTypes.doc': 'Word-документ',
  'common.fileTypes.docx': 'Word-документ',
  'common.fileTypes.xls': 'Excel-таблица',
  'common.fileTypes.xlsx': 'Excel-таблица',
  'common.fileTypes.ppt': 'PowerPoint',
  'common.fileTypes.pptx': 'PowerPoint',
  'common.fileTypes.txt': 'Текстовый файл',
  'common.fileTypes.zip': 'ZIP-архив',
  'common.fileTypes.rar': 'RAR-архив',
  'common.fileTypes.jpg': 'Изображение',
  'common.fileTypes.png': 'Изображение',
  'common.fileTypes.gif': 'GIF-анимация',
}

'ko-KR': {
  'common.fileTypes.pdf': 'PDF 문서',
  'common.fileTypes.doc': 'Word 문서',
  'common.fileTypes.docx': 'Word 문서',
  'common.fileTypes.xls': 'Excel 표',
  'common.fileTypes.xlsx': 'Excel 표',
  'common.fileTypes.ppt': 'PPT',
  'common.fileTypes.pptx': 'PPT',
  'common.fileTypes.txt': '텍스트',
  'common.fileTypes.zip': 'ZIP',
  'common.fileTypes.rar': 'RAR',
  'common.fileTypes.jpg': '이미지',
  'common.fileTypes.png': '이미지',
  'common.fileTypes.gif': 'GIF',
}

3.4 按钮和操作

'ru-RU': {
  'common.save': 'Сохранить',
  'common.cancel': 'Отмена',
  'common.apply': 'Применить',
  'common.close': 'Закрыть (ESC)',
  'common.saving': 'Сохранение...',
  'common.edit': 'Редактировать',
  'common.reset': 'Сбросить',
}

'ko-KR': {
  'common.save': '저장',
  'common.cancel': '취소',
  'common.apply': '적용',
  'common.close': '닫기 (ESC)',
  'common.saving': '저장 중...',
  'common.edit': '편집',
  'common.reset': '초기화',
}

3.5 变量插值示例

'ru-RU': {
  'popup.currentEngine': 'Поисковик: {engine}',
  'options.exportSuccess': 'Экспортировано {count} записей',
  'floatingPanel.applyEngineLabel': 'Применить к {engine}',
  'popup.historyEntry': '{query} в {engine}',
}

'ko-KR': {
  'popup.currentEngine': '현재 엔진: {engine}',
  'options.exportSuccess': '{count}개 내보냄',
  'floatingPanel.applyEngineLabel': '{engine}에 적용',
  'popup.historyEntry': '{engine}에서 {query}',
}

4. 质量保证清单

4.1 自动化验证 (必须全部通过)

TypeScript类型检查通过

npx tsc --noEmit
# 预期: 无错误输出

所有翻译键完整覆盖
- 对比 en-US 的518个键
- 确保 ru-RU 和 ko-KR 都有对应翻译
- 无缺失键
变量占位符格式验证
- 所有 {变量名} 在新语言中保持一致
- 数量和名称完全匹配
- 语序可调整,但变量名不变

构建成功

npm run build
# 预期:
# - BUILD SUCCESSFUL
# - dist/_locales/ru/messages.json 存在
# - dist/_locales/ko/messages.json 存在
# - dist/_locales/en/messages.json 存在
# - dist/_locales/zh_CN/messages.json 存在

dist目录结构验证

ls -la dist/_locales/
# 预期输出:
# drwxr-xr-x  en/
# drwxr-xr-x  zh_CN/
# drwxr-xr-x  ru/       ← 新增
# drwxr-xr-x  ko/       ← 新增

4.2 人工审核 (基于对照表)

关键按钮翻译准确 (参考对照表 🔴 区域)
- 保存/取消/应用/关闭/编辑/重置
- 确认功能对应正确
错误提示翻译清晰易懂 (参考对照表 🟠 区域)
- 复制失败/未选择搜索引擎等
- 用户能理解错误原因
搜索引擎名称翻译正确 (参考对照表 🟡 区域)
- 保持品牌原名(不翻译)
- X (Twitter), GitHub, Stack Overflow 等
抽查10%常规文本无明显错误 (参考对照表 🟢 区域)
- 随机抽取50条左右
- 检查语法和语义正确性
- 确保变量插值位置合理
README.md语言列表已更新
- 包含 🇷🇺 Русский (ru-RU)
- 包含 🇰🇷 한국어 (ko-KR)

4.3 UI显示测试 (可选,推荐)

俄语文本长度适配
- 俄语文本通常比英语长20-30%
- 检查按钮、菜单、标签是否溢出
- 特别关注: "Поисковик по умолчанию" 等长文本
韩语字符显示正常
- Hangul字符正确渲染
- 无字体fallback问题
- 字符高度不影响布局
语言切换功能正常
- 在设置中切换到俄语/韩语
- 界面立即刷新显示新语言
- 无白屏或加载错误

5. 成功标准

5.1 功能性标准

✅ 所有4种语言可正常切换
✅ 俄语和韩语界面文本显示正确
✅ 变量插值正常工作 (如 {engine}, {count})
✅ Chrome扩展的manifest名称和描述显示新语言

5.2 技术标准

✅ TypeScript编译无类型错误
✅ 构建成功且无警告
✅ 所有翻译键100%覆盖
✅ 变量占位符验证通过

5.3 质量标准

✅ 关键文本(按钮/错误)人工审核通过
✅ 翻译简洁,适合UI显示
✅ 功能性文本准确无误
✅ 文档同步更新完成

5.4 发布标准

✅ README.md已更新支持语言列表
✅ package.json版本号已更新 (如需要)
✅ Git commit包含清晰的提交信息
✅ 可直接发布到Chrome Web Store

6. 交付物清单

6.1 代码文件 (必须)

✅ /Users/lhly/chromeex/ssp/src/types/index.ts (Line 339修改)
✅ /Users/lhly/chromeex/ssp/public/_locales/ru/messages.json (新建,14条)
✅ /Users/lhly/chromeex/ssp/public/_locales/ko/messages.json (新建,14条)
✅ /Users/lhly/chromeex/ssp/src/i18n/translations.ts (添加ru-RU和ko-KR,共1036条)

6.2 文档文件 (必须)

✅ /Users/lhly/chromeex/ssp/.claude/specs/add-russian-korean-i18n/translation-review.md (对照表)
✅ /Users/lhly/chromeex/ssp/README.md (更新语言列表)

6.3 验证报告 (推荐)

✅ 构建验证输出日志
✅ TypeScript检查结果截图
✅ 翻译对照表审核结果

7. 实施注意事项

7.1 翻译质量保证

专业术语一致性: 搜索引擎、文件类型等技术术语保持一致
上下文准确性: 基于中英文对照理解功能后翻译,避免直译
简洁性优先: 俄语倾向动词形式,韩语使用名词化动词

7.2 变量插值处理

严格验证: 自动检查所有变量名一致性
语序灵活: 允许根据语法调整变量位置

示例:

en-US: "Search {query} on {engine}"
ru-RU: "Искать {query} в {engine}"  ← 语序保持
ko-KR: "{engine}에서 {query} 검색"  ← 语序调整(韩语后置词结构)

7.3 UI适配建议

俄语长文本: 如遇溢出,优先使用缩写或简洁表达
韩语排版: 韩文字符较方块,行高可能需微调
响应式布局: 确保不同语言文本长度不破坏布局

7.4 构建和发布

版本号: 考虑升级到 1.9.0 (新增语言是 minor 版本)
Chrome Web Store: 更新商店列表页的语言支持信息
发布说明: 在Release Notes中明确提及新增俄语和韩语支持

8. 故障排查指南

问题1: TypeScript类型错误

症状: Type '"ru-RU"' is not assignable to type 'Language'

解决方案:

// 检查 src/types/index.ts:339
export type Language = 'zh-CN' | 'en-US' | 'ru-RU' | 'ko-KR';
//                                         ^^^^^^^^  ^^^^^^^^ 确保已添加

问题2: 构建后语言文件未生成

症状: dist/_locales/ru/ 或 dist/_locales/ko/ 目录不存在

排查步骤:

检查 public/_locales/ru/messages.json 是否存在
检查 public/_locales/ko/messages.json 是否存在
检查 Vite 配置中的 publicDir 设置
手动删除 dist/ 目录后重新构建

问题3: 界面显示 `undefined` 或键名

症状: 切换到俄语/韩语后显示 common.save 而非 "Сохранить"

排查步骤:

检查 translations.ts 中 'ru-RU' 对象是否存在
检查对应的键是否完整
检查是否有拼写错误 (如 ru-ru vs ru-RU)
在浏览器控制台查看具体错误信息

问题4: 变量插值不工作

症状: 显示 "Поисковик: {engine}" 而非 "Поисковик: Google"

排查步骤:

检查翻译中 {engine} 是否保留
检查变量名拼写是否与 en-US 完全一致
检查代码中调用 t() 函数时是否传递了 variables 参数

9. 后续优化建议

9.1 翻译质量持续改进

收集用户反馈,优化翻译准确性
建立术语库,确保专业术语一致性
定期审查高频文本的翻译质量

9.2 技术债务

考虑引入 i18n 库 (如 react-i18next) 以获得更好的类型支持
实现翻译文件的热更新机制
添加缺失翻译的自动告警

9.3 用户体验增强

自动检测用户浏览器语言并设置默认语言
提供翻译贡献渠道 (如 GitHub PR)
添加 RTL 语言支持 (如阿拉伯语,未来扩展)

规范版本: 1.0 最后更新: 2025-12-03 状态: ✅ 已批准,可开始实施

27 KiB 原始文件 Blame 文件历史 Unescape Escape

技术规范 - 添加俄语和韩语国际化支持

1. 实施概览

1.1 核心任务

1.2 技术架构

1.3 实施原则

2. 详细实施步骤

Step 1: TypeScript类型定义更新

文件位置

当前代码

修改后代码

验证方法

Step 2: Chrome Extension i18n文件创建

2.1 创建俄语文件

2.2 创建韩语文件

2.3 翻译策略说明

Step 3: React i18n翻译添加

文件位置

当前结构

修改方式

翻译实施策略

Step 4: 自动化验证机制

4.1 变量完整性检查脚本

4.2 TypeScript类型检查

4.3 构建验证

Step 5: 生成翻译对照表

文件路径

表格结构

5.2 生成方式

Step 6: 文档同步更新

6.1 更新README.md

6.2 检查manifest.json

6.3 更新package.json (可选)

3. 完整翻译键值对照表 (核心示例)

3.1 语言名称翻译

3.2 搜索引擎名称 (保持原名)

3.3 文件类型翻译

3.4 按钮和操作

3.5 变量插值示例

4. 质量保证清单

4.1 自动化验证 (必须全部通过)

4.2 人工审核 (基于对照表)

4.3 UI显示测试 (可选,推荐)

5. 成功标准

5.1 功能性标准

5.2 技术标准

5.3 质量标准

5.4 发布标准

6. 交付物清单

6.1 代码文件 (必须)

6.2 文档文件 (必须)

6.3 验证报告 (推荐)

7. 实施注意事项

7.1 翻译质量保证

7.2 变量插值处理

7.3 UI适配建议

7.4 构建和发布

8. 故障排查指南

问题1: TypeScript类型错误

问题2: 构建后语言文件未生成

问题3: 界面显示 undefined 或键名

问题4: 变量插值不工作

9. 后续优化建议

9.1 翻译质量持续改进

9.2 技术债务

9.3 用户体验增强

27 KiB

原始文件 Blame 文件历史

问题3: 界面显示 `undefined` 或键名