i18n

LobeHub 国际化指南

• 默认语言：英语（en-US）
• 核心框架：react-i18next
• 仅修改 packages/locales/src/default/ 目录下的文件 —— 严禁直接编辑 locales/ 中的 JSON 文件（手动编写的 en-US/zh-CN 预览文件除外）
• 自动生成的语言包默认交由每日运行的 auto-i18n.yml 工作流处理；仅在急需使用时才手动运行 bun run i18n

Key 命名规范

采用点语法分割的扁平化 Key（切勿使用嵌套对象）：

// ✅ 正确示例
export default {
  'alert.cloud.action': '立即体验',
  'sync.actions.sync': '立即同步',
  'sync.status.ready': '已连接',
};

// ❌ 避免嵌套结构
export default {
  alert: { cloud: { action: '...' } },
};

命名模式： {feature}.{context}.{action|status}

变量插值： 使用 {{variableName}} 语法

'alert.cloud.desc': '我们提供 {{credit}} 额度积分',

避免 Key 冲突：

// ❌ 存在冲突
'clientDB.solve': '自助解决',
'clientDB.solve.backup.title': '数据备份',

// ✅ 正确规范
'clientDB.solve.action': '自助解决',
'clientDB.solve.backup.title': '数据备份',

开发工作流

1. 在 packages/locales/src/default/{namespace}.ts 中新增 Key
2. 在 packages/locales/src/default/index.ts 中导出新命名空间
3. 本地开发预览：手动翻译并填充 locales/zh-CN/{namespace}.json 与 locales/en-US/{namespace}.json
4. 其他语种语言包交由 .github/workflows/auto-i18n.yml 自动生成，该工作流每日运行并会自动提交翻译 PR
5. 仅在分支急需即时生效时才手动执行 bun run i18n（该脚本耗时较长且依赖 OPENAI_API_KEY）

使用方法

import { useTranslation } from 'react-i18next';

const { t } = useTranslation('common');

t('newFeature.title');
t('alert.cloud.desc', { credit: '1000' });

// 使用多个命名空间
const { t } = useTranslation(['common', 'chat']);
t('common:save');

常用命名空间

高频使用： common（通用 UI 文案）、chat（聊天对话功能）、setting（系统设置）

其他命名空间：auth、changelog、components、discover、editor、electron、error、file、hotkey、knowledgeBase、memory、models、plugin、portal、providers、tool、topic