国际化和本地化

相关源文件

• locales/ar/models.json
• locales/ar/setting.json
• locales/bg-BG/models.json
• locales/de-DE/models.json
• locales/de-DE/setting.json
• locales/en-US/models.json
• locales/en-US/setting.json
• locales/es-ES/models.json
• locales/es-ES/setting.json
• locales/fr-FR/models.json
• locales/fr-FR/setting.json
• locales/it-IT/models.json
• locales/it-IT/setting.json
• locales/ja-JP/models.json
• locales/ja-JP/setting.json
• locales/ko-KR/models.json
• locales/ko-KR/setting.json
• locales/nl-NL/models.json
• locales/nl-NL/setting.json
• locales/pl-PL/models.json
• locales/pl-PL/setting.json
• locales/pt-BR/setting.json
• locales/tr-TR/setting.json
• locales/vi-VN/setting.json
• locales/zh-CN/setting.json
• locales/zh-TW/setting.json
• src/locales/default/common.ts
• src/locales/default/setting.ts

目的与范围

本文档介绍了 LobeChat 中的国际化 (i18n) 和本地化 (l10n) 系统，该系统使应用程序能够支持多种语言，并为全球用户提供本地化体验。该系统通过使用 TypeScript 源文件和 JSON 语言环境文件，采用结构化的文件方法，支持 16 种以上语言的 UI 元素、模型描述和设置。

有关配置 LobeChat 其他方面的信息，请参阅配置管理。

翻译文件结构

LobeChat 根据语言环境代码以目录结构组织翻译文件，应用程序的不同组件使用单独的文件。

本地化文件结构

LobeChat 使用两层系统组织翻译：TypeScript 源文件用于默认语言环境，JSON 文件用于编译后的翻译。

来源：src/locales/default/common.ts src/locales/default/setting.ts locales/ 目录结构

翻译模式和结构

i18n 系统使用两个主要的翻译文件，它们具有分层的嵌套对象结构。

通用字符串模式

设置模式

来源：src/locales/default/common.ts1-363 src/locales/default/setting.ts1-532

模型模式

来源：locales/en-US/models.json、locales/nl-NL/models.json

支持的语言

LobeChat 支持 16 种语言，提供完整的 UI 和模型描述翻译

区域码	语言	本地名称
en-US	英语（美国）	英语
zh-CN	中文（简体）	简体中文
zh-TW	中文（繁体）	繁体中文
ar	阿拉伯语	العربية
bg-BG	保加利亚语	Български
de-DE	德语	德语
es-ES	西班牙语	西班牙语
fr-FR	法语	法语
it-IT	意大利语	意大利语
ja-JP	日语	日语
ko-KR	韩语	韩语
nl-NL	荷兰语	荷兰语
pl-PL	波兰语	波兰语
pt-BR	葡萄牙语（巴西）	葡萄牙语（巴西）
tr-TR	土耳其语	土耳其语
vi-VN	越南语	越南语

语言名称映射定义在通用翻译文件中的 lang 对象中。

来源：locales/ 目录结构, src/locales/default/common.ts233-270

AI 模型本地化

每个语言环境都包含一个 models.json 文件，为来自不同供应商的 AI 模型提供本地化描述。该结构将模型 ID 映射到描述对象

模型描述覆盖范围

LobeChat 提供主要 AI 供应商的模型翻译

同一模型在不同语言下的翻译示例

语言	模型：01-ai/yi-1.5-34b-chat 描述
英语	"零一万物，最新的开源微调模型，拥有 340 亿参数，支持各种对话场景，高质量训练数据与人类偏好对齐。"
德语	"Yi 1.5，最新的开源微调模型，拥有 340 亿参数，支持各种对话场景，高质量训练数据与人类偏好对齐。"
意大利语	"零一万物，最新的开源微调模型，拥有 340 亿参数，支持各种对话场景，高质量训练数据与人类偏好对齐。"

来源：locales/en-US/models.json2-4 locales/de-DE/models.json2-4 locales/it-IT/models.json2-4

UI 元素本地化

系统使用两个主要的翻译文件用于 UI 元素

通用 UI 元素 (common.ts/json)

包含通用应用程序字符串，包括导航、操作和系统消息

设置 UI 元素 (setting.ts/json)

包含按功能区域组织的设置特定翻译

来源：src/locales/default/common.ts src/locales/default/setting.ts

国际化实现架构

LobeChat 使用基于 TypeScript 的源系统实现国际化，并输出编译后的 JSON 文件

翻译键访问模式

系统使用分层点表示法访问嵌套翻译键

• common.copy → "复制" (Copy)
• setting.agentTab.chat → "聊天偏好" (Chat Preferences)
• setting.llm.apiKey.title → "API 密钥"
• common.lang['zh-CN'] → "简体中文" (Simplified Chinese)

来源：src/locales/default/setting.ts250-253

动态内容和插值

翻译系统支持使用双花括号进行变量插值以实现动态内容

常见插值模式

模式	使用示例	运行时替换
{{appName}}	"帮助 {{appName}} 做得更好"	应用程序名称
{{name}}	"{{name}} 开始公测"	功能/服务名称
{{credit}}	"免费的 {{credit}} 额度"	信用额度
{{count}}	"共 {{count}} 个模型可用"	模型数量
{{version}}	"有新版本可用：{{version}}"	版本号

复杂插值示例

来自遥测系统

来自云服务公告

来源：src/locales/default/common.ts331 src/locales/default/common.ts7 src/locales/default/setting.ts16

语言选择与配置

语言选择系统通过设置界面实现，并具有自动检测功能

语言选择选项

语言配置结构

系统将语言偏好存储在 settingCommon 配置部分

用户可以通过 tab 配置中定义的设置面板选项卡结构访问语言设置。

来源：src/locales/default/setting.ts250-253 src/locales/default/common.ts233-270 src/locales/default/setting.ts506-518

添加新语言

添加新语言支持

1. 在 /locales 下创建一个新目录，并使用适当的语言环境代码（例如，sv-SE 代表瑞典语）
2. 创建必要的 JSON 文件
   • models.json 用于 AI 模型描述
   • setting.json 用于 UI 元素和设置
3. 确保所有键与现有语言环境文件中的结构匹配
4. 翻译所有值，同时保留任何占位符变量（例如，{{appName}}）
5. 通过在设置中切换到新语言来测试翻译

最佳实践

使用国际化系统时

1. 始终使用翻译键而不是硬编码字符串
2. 在所有语言环境文件中保持一致的键结构
3. 保留动态内容的占位符
4. 设计 UI 组件时，请考虑不同语言的文本长度差异
5. 在实际情境中测试翻译，以确保正确显示

结论

LobeChat 中的国际化和本地化系统为支持多种语言提供了强大的框架，使应用程序能够面向全球用户。结构化的翻译方法便于维护和扩展语言支持。

通过将翻译文件分离成针对不同组件和语言的结构化 JSON 文件，LobeChat 维护了一个清晰且可扩展的国际化架构，可以随着应用程序的发展适应新的语言和功能。