# 国际化与本地化

1. 目的与范围 #

本文档介绍Ragflow-Plus的国际化（i18n）和本地化（l10n）实现，详细说明系统如何支持多种语言并提供本地化的用户界面。系统目前通过基于react-i18next的结构化翻译框架支持英语、简体中文、繁体中文和葡萄牙语（巴西）。

关于RAG引擎中的跨语言搜索能力，请参阅 翻译与跨语言支持。

2. 翻译文件架构 #

本地化系统采用结构化方法，为每种支持的语言使用单独的翻译文件，以一致的嵌套JSON格式组织。

翻译文件结构：

所有翻译文件都遵循相同的嵌套对象结构，包含以下主要部分：

• common: 通用UI元素和消息
• login: 登录和认证表单
• header: 导航和头部组件
• knowledgeList: 知识库列表
• knowledgeDetails: 知识库详情和管理
• chat: 聊天界面
• write: 文档编写界面
• setting: 用户设置
• fileManager: 文件管理操作
• flow: Agent工作流

3. 语言支持矩阵 #

系统在四种语言中提供全面的翻译覆盖，具有一致的键结构：

语言检测和切换：

• 自动检测：使用i18next-browser-languagedetector自动检测浏览器语言
• 本地存储：语言选择保存在localStorage中（键：lng）
• 动态切换：支持运行时语言切换，无需刷新页面
• 回退语言：默认回退到英语（en）

4. 翻译键组织 #

4.1 键类别 #

翻译键按功能模块组织，便于维护和扩展：

主要类别：

1. common（通用）：

   • 按钮文本（确定、取消、保存等）
   • 通用消息（成功、错误、警告等）
   • 状态文本（加载中、已完成等）

2. 功能模块：

   • login: 登录、注册、密码重置
   • header: 导航菜单、用户菜单
   • knowledgeList: 知识库列表、搜索、筛选
   • knowledgeDetails: 文档管理、分块编辑
   • chat: 消息输入、历史记录、设置
   • write: 文档编辑、模板、导出
   • setting: 用户配置、偏好设置
   • fileManager: 文件上传、下载、管理
   • flow: 工作流设计、节点配置

键命名规范：

• 使用驼峰命名法（camelCase）
• 使用描述性名称
• 保持键名与功能一致
• 避免缩写和歧义

4.2 嵌套结构 #

翻译键采用嵌套结构，便于组织和管理：

结构示例：

{
  translation: {
    common: {
      confirm: "确定",
      cancel: "取消",
      save: "保存"
    },
    chat: {
      input: {
        placeholder: "输入消息...",
        send: "发送"
      },
      message: {
        user: "用户",
        assistant: "助手"
      }
    }
  }
}

访问方式：

• 使用点号分隔的路径：common.confirm
• 支持深层嵌套：chat.input.placeholder
• 自动类型推断和补全

5. 实现架构 #

5.1 i18n配置 #

系统使用react-i18next进行国际化配置：

核心配置：

i18n
  .use(initReactI18next)
  .use(LanguageDetector)
  .init({
    detection: {
      lookupLocalStorage: 'lng',
    },
    supportedLngs: ['en', 'zh', 'zh-traditional', 'pt-br'],
    resources: {
      en: translation_en,
      zh: translation_zh,
      'zh-traditional': translation_zh_traditional,
      'pt-br': translation_pt_br
    },
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false,
    },
  });

配置特性：

• 语言检测：自动从localStorage检测用户语言偏好
• 支持语言：明确列出所有支持的语言代码
• 资源加载：按需加载翻译资源
• 回退机制：缺失翻译时回退到英语
• 插值配置：禁用HTML转义，支持富文本内容

5.2 Hook使用模式 #

系统提供两种主要的翻译Hook：

1. useTranslation Hook（标准模式）：

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();
  return <div>{t('common.confirm')}</div>;
}

2. useTranslate Hook（命名空间模式）：

import { useTranslate } from '@/hooks/common-hooks';

function MyComponent() {
  const { t } = useTranslate('chat');
  return <div>{t('input.placeholder')}</div>;
}

Hook选择建议：

• useTranslation：适用于通用翻译，需要访问多个命名空间
• useTranslate：适用于特定功能模块，提供更好的类型推断

5.3 组件集成 #

Ant Design组件本地化：

系统集成Ant Design的国际化支持：

import { ConfigProvider } from 'antd';
import enUS from 'antd/locale/en_US';
import zhCN from 'antd/locale/zh_CN';

const AntLanguageMap = {
  en: enUS,
  zh: zhCN,
  'zh-traditional': zhCN,
  'pt-br': ptBR
};

function Root() {
  const [locale, setLocale] = useState(
    getLocale(storage.getLanguage())
  );

  i18n.on('languageChanged', (lng: string) => {
    storage.setLanguage(lng);
    setLocale(getLocale(lng));
  });

  return (
    <ConfigProvider locale={locale}>
      <App />
    </ConfigProvider>
  );
}

集成特性：

• 自动同步：i18n语言变化自动更新Ant Design语言
• 组件本地化：日期选择器、表格、表单等组件自动本地化
• 样式适配：支持RTL（从右到左）语言布局

6. 动态内容和占位符 #

6.1 参数替换 #

翻译系统支持参数替换，用于动态内容：

基本用法：

// 翻译文件
{
  welcome: "欢迎, {{name}}!"
}

// 组件使用
t('welcome', { name: '张三' })
// 输出: "欢迎, 张三!"

多参数支持：

// 翻译文件
{
  message: "{{count}} 条消息来自 {{sender}}"
}

// 组件使用
t('message', { count: 5, sender: '系统' })
// 输出: "5 条消息来自 系统"

格式化选项：

• 数字格式化：{{count, number}}
• 日期格式化：{{date, date}}
• 货币格式化：{{amount, currency}}

6.2 富内容支持 #

系统支持在翻译中包含HTML和React组件：

HTML内容：

// 翻译文件
{
  description: "点击 <a href='{{url}}'>这里</a> 了解更多"
}

// 组件使用
<Trans i18nKey="description" values={{ url: '/help' }} />

React组件：

import { Trans } from 'react-i18next';

<Trans
  i18nKey="welcome"
  components={[
    <strong />,
    <a href="/profile" />
  ]}
/>

使用场景：

• 链接和按钮
• 强调文本
• 复杂布局
• 交互式内容

6.3 复数形式 #

系统支持复数形式的处理：

复数规则：

// 翻译文件
{
  item: "{{count}} 项",
  item_plural: "{{count}} 项",
  item_zero: "无项"
}

// 自动选择正确的复数形式
t('item', { count: 0 })  // "无项"
t('item', { count: 1 })  // "1 项"
t('item', { count: 5 })  // "5 项"

语言特定规则：

• 不同语言有不同的复数规则
• 系统自动根据语言选择正确的形式
• 支持零、一、多等特殊情况

7. 语言切换 #

7.1 用户界面 #

系统提供语言选择界面：

语言选择器：

• 显示所有支持的语言
• 显示当前选中的语言
• 支持快速切换
• 立即生效，无需刷新

实现位置：

• web/src/pages/user-setting/setting-locale/ - 用户设置中的语言选择
• 系统设置中的语言选项
• 登录页面的语言选择

7.2 语言切换流程 #

切换特性：

• 即时生效：切换后立即更新所有文本
• 持久化：语言选择保存到localStorage
• 全局同步：所有组件自动更新
• 无刷新：无需刷新页面

8. 添加新翻译 #

8.1 添加新语言 #

要添加对新语言的支持：

步骤：

1. 创建翻译文件：在web/src/locales/目录下创建新文件，如fr.ts（法语）
2. 遵循结构：从en.ts复制嵌套对象结构
3. 翻译所有键：确保所有翻译键都有对应的翻译
4. 注册语言：在web/src/locales/config.ts中注册新语言
5. 添加语言选项：在语言选择器中添加新语言选项
6. 测试集成：验证所有UI元素正确显示

翻译文件要求：

• 必须导出默认对象
• 必须包含translation属性
• 必须保持与en.ts相同的键结构
• 所有键都必须有翻译值

8.2 更新现有翻译 #

更新流程：

1. 识别缺失键：检查是否有未翻译的键
2. 更新翻译文件：在相应的语言文件中添加或更新翻译
3. 验证一致性：确保所有语言文件的键结构一致
4. 测试验证：在UI中验证翻译正确显示

最佳实践：

• 保持所有语言文件的键同步
• 使用版本控制跟踪翻译更改
• 定期审查翻译质量
• 提供翻译上下文说明

8.3 翻译质量保证 #

质量检查清单：

• 所有键都有翻译
• 翻译准确且符合语境
• 术语使用一致
• 格式和标点正确
• 长度适合UI布局
• 文化适应性考虑

工具支持：

• 使用翻译表对比不同语言的键
• 自动检测缺失的翻译键
• 验证键结构一致性
• 提供翻译统计信息

9. 性能优化 #

9.1 资源加载 #

按需加载：

• 只加载当前语言的翻译资源
• 支持懒加载未使用的语言
• 减少初始加载时间
• 优化内存使用

缓存策略：

• 翻译资源缓存到浏览器
• 减少重复加载
• 提高切换速度
• 支持离线使用

9.2 渲染优化 #

优化技巧：

• 使用useMemo缓存翻译结果
• 避免在渲染中重复调用t()函数
• 使用Trans组件处理复杂内容
• 减少不必要的重新渲染

10. 故障排除 #

10.1 常见问题 #

问题：翻译不显示

• 检查翻译键是否正确
• 确认语言文件已正确加载
• 查看浏览器控制台错误
• 验证i18n配置

问题：语言切换不生效

• 检查localStorage是否可用
• 确认语言代码是否正确
• 查看i18n事件监听器
• 验证组件是否正确订阅语言变化

问题：部分翻译缺失

• 检查翻译文件是否完整
• 确认键路径是否正确
• 查看回退语言设置
• 验证命名空间配置

10.2 调试技巧 #

• 使用i18n调试模式查看详细信息
• 检查浏览器开发者工具中的网络请求
• 查看localStorage中的语言设置
• 使用React DevTools检查组件状态
• 验证翻译键的访问路径

11. 最佳实践 #

11.1 翻译管理 #

1. 键命名：使用清晰、描述性的键名
2. 结构组织：按功能模块组织翻译键
3. 一致性：保持所有语言文件的键结构一致
4. 文档化：为复杂翻译提供上下文说明

11.2 开发建议 #

1. 类型安全：使用TypeScript确保类型安全
2. 代码审查：审查翻译更改的质量
3. 测试覆盖：测试所有语言下的UI显示
4. 性能监控：监控翻译加载和切换性能

11.3 维护建议 #

1. 定期更新：定期更新翻译内容
2. 质量检查：定期检查翻译质量
3. 用户反馈：收集用户对翻译的反馈
4. 版本管理：使用版本控制管理翻译更改

12. 总结 #

国际化与本地化是Ragflow-Plus的重要特性，通过react-i18next框架提供了全面的多语言支持。系统采用结构化的翻译文件组织方式，支持动态内容、参数替换和富文本内容，为用户提供了流畅的多语言体验。通过合理的架构设计和最佳实践，系统能够轻松扩展支持更多语言，满足全球用户的需求。