Skip to content

设计并实现多语言国际化支持（i18n）- 支持中文和英文 #270

Open
Open
设计并实现多语言国际化支持（i18n）- 支持中文和英文#270
Assignees
cubxxw
Labels
backenddesignenhancementNew feature or requestfrontendi18n
@kubbot

Description

@kubbot
kubbot
opened on Jul 27, 2025

🌍 多语言国际化支持设计方案

📋 需求背景

为了让 Nexus AI 阅读助手能够服务更广泛的用户群体，需要实现完整的多语言支持。初期目标是支持中文（zh-CN）和英文（en-US），并为后续语言扩展奠定基础。

🎯 设计目标

主要目标

  • 支持界面语言的动态切换（中文/英文）
  • 保证所有用户界面元素的完整本地化
  • AI 输出内容的多语言智能处理
  • 用户偏好的持久化存储
  • 为后续语言扩展提供可扩展架构

非功能性目标

  • 语言切换响应时间 < 200ms
  • 支持 RTL 语言的架构预留
  • SEO 友好的多语言 URL 结构
  • 无缝的用户体验，不中断工作流

🏗️ 系统架构设计

1. 多语言架构分层

┌─────────────────────────────────────────────────────┐
│                UI 展示层                             │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │  Web App    │ │ Mobile App  │ │   Plugin    │    │
│  │ (React)     │ │(React Native│ │  (Chrome)   │    │
│  └─────────────┘ └─────────────┘ └─────────────┘    │
└─────────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────────┐
│                国际化中间层                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │ i18n Store  │ │Language     │ │Locale       │    │
│  │ (Zustand)   │ │Detector     │ │Formatter    │    │
│  └─────────────┘ └─────────────┘ └─────────────┘    │
└─────────────────────────────────────────────────────┘
                        │
┌─────────────────────────────────────────────────────┐
│                后端服务层                            │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │ User Pref   │ │Content      │ │AI Language  │    │
│  │ Service     │ │Service      │ │Service      │    │
│  └─────────────┘ └─────────────┘ └─────────────┘    │
└─────────────────────────────────────────────────────┘

2. 前端国际化架构

2.1 技术选型

  • Web App: React + react-i18next + i18next
  • Mobile App: React Native + react-i18next + i18next
  • 状态管理: Zustand 集成 i18n store
  • 插件: 独立的 i18n 实现，共享翻译资源

2.2 翻译资源管理结构

/locales
├── en-US/
│   ├── common.json          # 通用翻译
│   ├── navigation.json      # 导航相关
│   ├── content.json         # 内容相关
│   ├── ai-prompts.json      # AI 指令模板
│   ├── errors.json          # 错误信息
│   └── notifications.json   # 通知消息
├── zh-CN/
│   ├── common.json
│   ├── navigation.json
│   ├── content.json
│   ├── ai-prompts.json
│   ├── errors.json
│   └── notifications.json
└── index.ts                 # 语言配置入口

2.3 命名空间设计

{
  "common": {
    "actions": {
      "save": "保存",
      "cancel": "取消",
      "delete": "删除",
      "edit": "编辑",
      "share": "分享"
    },
    "labels": {
      "title": "标题",
      "content": "内容",
      "tags": "标签"
    },
    "status": {
      "loading": "加载中...",
      "success": "成功",
      "error": "错误"
    }
  },
  "navigation": {
    "sidebar": {
      "home": "首页",
      "library": "内容库",
      "notebook": "笔记本",
      "settings": "设置"
    },
    "tabs": {
      "original": "原文",
      "insights": "洞察",
      "analysis": "分析"
    }
  },
  "content": {
    "document": {
      "types": {
        "article": "文章",
        "book": "书籍",
        "pdf": "PDF文档",
        "webpage": "网页"
      }
    },
    "ai_cards": {
      "summary": "摘要",
      "keypoints": "要点",
      "analysis": "分析",
      "questions": "思考题"
    }
  }
}

3. AI 内容多语言处理策略

3.1 AI 指令模板的多语言化

{
  "ai-prompts": {
    "summarize": {
      "en-US": "Please provide a concise summary of the following content in English:",
      "zh-CN": "请用中文对以下内容进行简洁的总结："
    },
    "extract_keypoints": {
      "en-US": "Extract the key points from this content and present them in English:",
      "zh-CN": "从这段内容中提取要点，并用中文呈现："
    },
    "explain_concept": {
      "en-US": "Explain this concept in simple terms for English speakers:",
      "zh-CN": "用简单的中文解释这个概念："
    }
  }
}

3.2 AI 输出语言智能识别与处理

AI 内容处理流程:
  1. 检测用户界面语言偏好
  2. 识别原文档语言
  3. 应用语言匹配策略:
     - 同语言: 直接处理
     - 不同语言: 提供翻译选项
     - 多语言混合: 智能分段处理
  4. 生成符合目标语言习惯的 AI 卡片

4. 后端多语言支持设计

4.1 用户语言偏好存储

{
  "user_preferences": {
    "user_id": "user_123",
    "language": "zh-CN",
    "ai_output_language": "zh-CN", 
    "auto_translate": true,
    "fallback_language": "en-US",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

4.2 多语言 API 设计

API 端点设计:
  - GET /api/v1/i18n/languages
    # 获取支持的语言列表
  
  - GET /api/v1/i18n/translations/{lang}
    # 获取指定语言的翻译资源
  
  - PUT /api/v1/users/{id}/language-preferences
    # 更新用户语言偏好
  
  - POST /api/v1/ai/process
    # AI 处理请求（包含目标语言参数）
    headers:
      Accept-Language: zh-CN,en-US;q=0.9
    body:
      target_language: "zh-CN"
      content: "..."

🎨 用户界面设计

1. 语言切换组件设计

1.1 全局语言切换器

位置选项:
  - 主导航栏右上角
  - 用户头像下拉菜单
  - 设置页面专门区域

交互设计:
  - 下拉选择器显示语言名称（中文/English）
  - 当前语言高亮标识
  - 切换后立即生效，无需刷新页面
  - 保存用户选择到本地存储和后端

1.2 首次访问语言检测

检测逻辑:
  1. 检查用户已保存的语言偏好
  2. 读取浏览器 Accept-Language 头
  3. 基于用户地理位置推断（可选）
  4. 默认回退到英文
  
引导流程:
  - 新用户显示语言选择引导页
  - 支持"检测我的语言"按钮
  - 可以跳过，稍后在设置中修改

2. 响应式文本处理

2.1 文本长度适配

设计考虑:
  - 中文通常比英文简洁，UI 组件需要自适应
  - 长语言文本（如德语）的 UI 适配预留
  - 按钮、卡片、弹窗的动态宽度调整
  
实现策略:
  - CSS Grid/Flexbox 弹性布局
  - 文本截断和 tooltip 显示完整内容
  - 移动端特殊优化

2.2 字体和排版优化

字体选择:
  - 中文: PingFang SC, Noto Sans CJK SC
  - 英文: Inter, Roboto, system fonts
  - 代码: JetBrains Mono, Fira Code
  
排版规则:
  - 中文行高: 1.6-1.8
  - 英文行高: 1.5-1.6  
  - 混合文本的智能断行
  - 数字和英文在中文中的间距处理

3. AI 卡片多语言展示

3.1 卡片类型本地化

卡片标题翻译:
  Summary → 摘要
  Key Points → 要点
  Analysis → 分析  
  Q&A → 问答
  Outline → 大纲
  
卡片操作本地化:
  - "Save to Notebook" → "保存到笔记本"
  - "Generate more" → "生成更多"
  - "Translate" → "翻译"
  - "Explain further" → "深入解释"

3.2 混合语言内容处理

场景处理:
  1. 英文文档 + 中文界面:
     - 提供"翻译摘要"选项
     - 显示双语对照卡片
     
  2. 中文文档 + 英文界面:
     - AI 生成英文分析
     - 保留原文引用的中文
     
  3. 多语言文档:
     - 按语言分段处理
     - 提供统一语言的整体分析

🔧 技术实现细节

1. 前端状态管理

1.1 Zustand i18n Store 设计

interface I18nState {
  currentLanguage: string;
  availableLanguages: string[];
  isLoading: boolean;
  translations: Record<string, any>;
  
  // Actions
  setLanguage: (lang: string) => void;
  loadTranslations: (lang: string) => Promise<void>;
  t: (key: string, options?: any) => string;
}

1.2 React Hook 封装

// useI18n Hook 设计
const useI18n = () => {
  const { t, currentLanguage, setLanguage } = useI18nStore();
  
  return {
    t,
    currentLanguage,
    changeLanguage: setLanguage,
    formatDate: (date: Date) => formatDateByLocale(date, currentLanguage),
    formatNumber: (num: number) => formatNumberByLocale(num, currentLanguage)
  };
};

2. 翻译资源管理

2.1 动态加载策略

加载方案:
  - 初始加载: 只加载当前语言的核心翻译
  - 懒加载: 按需加载页面级翻译资源
  - 缓存策略: 本地存储 + CDN 缓存
  - 版本控制: 翻译资源版本号管理

2.2 翻译更新机制

更新流程:
  1. 开发阶段: 开发者添加新的翻译 key
  2. 提取阶段: 自动扫描代码提取待翻译文本
  3. 翻译阶段: 翻译团队/工具完成翻译
  4. 集成阶段: CI/CD 自动打包翻译资源
  5. 部署阶段: 热更新翻译内容（无需重新部署）

3. SEO 和 URL 多语言化

3.1 URL 结构设计

路径前缀方案:
  - /en/dashboard
  - /zh/dashboard
  - /en/content/library  
  - /zh/content/library

默认语言处理:
  - / 重定向到用户偏好语言
  - /dashboard 重定向到 /{userLang}/dashboard
  
hreflang 标记:
  - 每个页面包含所有语言版本的链接
  - 搜索引擎友好的多语言索引

4. 移动端和插件适配

4.1 React Native 适配

特殊考虑:
  - 字体加载优化
  - 原生组件的文本适配
  - RTL 布局支持预留
  - 系统语言变更监听

4.2 浏览器插件适配

插件特性:
  - 独立的 i18n 配置
  - 与主应用共享翻译资源
  - 网页语言检测和匹配
  - 右键菜单多语言化

📊 数据迁移和兼容性

1. 现有数据处理

迁移策略:
  - 现有用户默认语言根据注册地区设定
  - AI 输出历史数据保持原语言
  - 提供批量翻译现有内容的选项
  
向后兼容:
  - API 保持向后兼容
  - 旧版本客户端显示默认语言
  - 渐进式升级机制

2. A/B 测试和灰度发布

发布策略:
  1. 内部测试版本（开发团队）
  2. 小范围用户测试（5%）
  3. 地区性发布（特定语言用户）
  4. 全量发布
  
监控指标:
  - 语言切换成功率
  - 翻译质量反馈
  - 用户满意度调研
  - 性能影响评估

✅ 验收标准

功能验收

  • 支持中文和英文界面切换
  • 所有 UI 元素完全本地化
  • AI 输出支持目标语言生成
  • 用户语言偏好持久化保存
  • SEO 友好的多语言 URL
  • 移动端和插件同步支持

性能验收

  • 语言切换响应时间 < 200ms
  • 翻译资源加载时间 < 500ms
  • 不影响现有功能性能
  • 内存占用增长 < 20%

用户体验验收

  • 首次访问语言检测准确率 > 90%
  • 混合语言内容处理合理
  • 文本长度变化不破坏 UI 布局
  • 字体渲染清晰美观

质量验收

  • 翻译准确性人工审核通过
  • 无安全漏洞和性能问题
  • 自动化测试覆盖率 > 80%
  • 跨浏览器兼容性测试通过

🚀 分阶段实现计划

Phase 1: 基础架构搭建

  • 前端 i18n 框架集成
  • 翻译资源结构设计
  • 基础 UI 组件本地化

Phase 2: 核心功能本地化

  • 主要页面和功能翻译
  • 语言切换器实现
  • 用户偏好存储

Phase 3: AI 功能多语言化

  • AI 指令模板多语言化
  • AI 输出语言处理
  • 混合语言内容优化

Phase 4: 高级功能和优化

  • SEO 多语言化
  • 性能优化
  • 用户体验完善

📝 后续扩展考虑

  • 支持更多语言（日语、韩语、法语等）
  • RTL 语言支持（阿拉伯语、希伯来语）
  • 语音输入输出的多语言支持
  • 实时翻译功能集成
  • 多语言知识库构建

分配任务:

测试要求:

  • 通过多语言自动化测试套件
  • 人工翻译质量审核
  • 跨平台兼容性验证

Metadata

Metadata

Assignees

Labels

backenddesignenhancementNew feature or requestfrontendi18n

Type

No type

Projects

nexus

Status

Backlog

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions