This document describes LobeChat's internationalization (i18n) and localization (l10n) system, which supports 13+ languages across the application UI, settings, plugins, and model catalog. It covers the locale file structure, automated translation workflows, and runtime locale detection.
For information about model configuration and provider setup, see AI Model Provider System. For deployment options and environment variables, see Deployment Options.
LobeChat's i18n system uses TypeScript as the source of truth for locale definitions, with JSON files for each language translation. The system separates concerns by domain (common UI, settings, plugins, model catalog) and automates translation updates using GitHub Actions and OpenAI.
Diagram: Localization System Architecture
Sources: High-level system architecture Diagram 8, src/locales/default/common.ts1-50 locales/en-US/common.json1-50 locales/zh-CN/common.json1-50
TypeScript files in src/locales/default/ serve as the canonical source of truth for all locale strings. These files define the structure, keys, and default English values.
Key Source Files:
| File | Purpose | Example Keys |
|---|---|---|
src/locales/default/common.ts | Common UI elements, buttons, labels | 'about', 'advanceSettings', 'alert.cloud.action' |
src/locales/default/setting.ts | Settings interface, configuration | 'about.title', 'accountDeletion.cancelButton' |
src/locales/default/plugin.ts | Plugin/skill system, tool descriptions | 'arguments.title', 'builtins.lobe-agent-builder.apiName' |
Each TypeScript file exports a default object with nested string keys:
Sources: src/locales/default/common.ts1-100 src/locales/default/setting.ts1-100 src/locales/default/plugin.ts1-100
JSON files in locales/{locale}/ directories contain translations for each supported language. The structure mirrors the TypeScript source files but uses JSON format.
Directory Structure:
locales/
├── en-US/
│ ├── common.json
│ ├── setting.json
│ ├── plugin.json
│ └── models.json
├── zh-CN/
│ ├── common.json
│ ├── setting.json
│ ├── plugin.json
│ └── models.json
├── ja-JP/
│ └── ...
├── ko-KR/
│ └── ...
└── ... (11+ other locales)
Sources: locales/en-US/common.json1-10 locales/zh-CN/common.json1-10 locales/ja-JP/models.json1-10
LobeChat separates locale strings by functional domain to improve maintainability and reduce file size:
| Domain | File Name | Content |
|---|---|---|
| Common UI | common.json | Shared UI components, buttons, error messages, navigation |
| Settings | setting.json | Settings pages, configuration options, account management |
| Plugins | plugin.json | Plugin/skill descriptions, tool parameters, marketplace content |
| Models | models.json | AI model descriptions (800+ models), provider information |
Diagram: Domain-Specific Locale Loading
Sources: locales/en-US/common.json1-10 locales/en-US/setting.json1-10 locales/en-US/plugin.json1-10 locales/ko-KR/models.json1-10 src/features/PluginDevModal/index.tsx1-50 src/features/AgentSetting/AgentPlugin/index.tsx1-50
LobeChat supports 13+ languages with comprehensive translation coverage:
| Language | Locale Code | Coverage |
|---|---|---|
| English | en-US | 100% (source) |
| Chinese (Simplified) | zh-CN | 100% |
| Chinese (Traditional) | zh-TW | 100% |
| Japanese | ja-JP | 100% |
| Korean | ko-KR | 100% |
| French | fr-FR | 100% |
| German | de-DE | 100% |
| Spanish | es-ES | 100% |
| Portuguese (Brazil) | pt-BR | 100% |
| Russian | ru-RU | 100% |
| Italian | it-IT | 100% |
| Dutch | nl-NL | 100% |
| Polish | pl-PL | 100% |
| Turkish | tr-TR | 100% |
| Arabic | ar | 100% |
| Bulgarian | bg-BG | 100% |
Sources: locales/en-US/common.json1-5 locales/zh-CN/common.json1-5 locales/ja-JP/models.json1-5 locales/ko-KR/models.json1-5 locales/fr-FR/models.json1-5 locales/de-DE/models.json1-5 locales/ru-RU/models.json1-5 locales/it-IT/models.json1-5 locales/nl-NL/models.json1-5 locales/pl-PL/models.json1-5 locales/es-ES/models.json1-5 locales/pt-BR/models.json1-5 locales/tr-TR/models.json1-5 locales/ar/models.json1-5 locales/bg-BG/models.json1-5
A unique aspect of LobeChat's i18n system is the comprehensive localization of AI model descriptions. The models.json file contains descriptions for 800+ AI models across 13 languages.
Each model description follows a key-value pattern:
Example from Multiple Languages:
| Language | Key | Description (excerpt) |
|---|---|---|
| English | "DeepSeek-R1.description" | "DeepSeek-R1 applies large-scale reinforcement learning..." |
| Japanese | "DeepSeek-R1.description" | "DeepSeek-R1はポストトレーニングで大規模な強化学習を活用し..." |
| Korean | "DeepSeek-R1.description" | "DeepSeek-R1은 후학습 단계에서 대규모 강화학습을 적용하여..." |
| French | "DeepSeek-R1.description" | "DeepSeek-R1 applique un apprentissage par renforcement..." |
Diagram: Model Description Localization Flow
Sources: locales/en-US/models.json1-50 locales/ja-JP/models.json1-50 locales/ko-KR/models.json1-50 locales/fr-FR/models.json1-50 locales/de-DE/models.json1-50 src/features/AgentSetting/AgentPlugin/index.tsx1-50
The model descriptions include:
Example keys from model descriptions:
DeepSeek-R1.description
Qwen/Qwen2.5-7B-Instruct.description
anthropic.claude-3-5-sonnet-20241022-v2:0.description
Meta-Llama-3.3-70B-Instruct.description
360gpt-pro.description
Sources: locales/ko-KR/models.json1-100 locales/ja-JP/models.json1-100 locales/fr-FR/models.json1-100
LobeChat uses GitHub Actions and the lobe-i18n CLI tool to automate translation updates, leveraging OpenAI's API for high-quality translations.
Diagram: Automated Translation Workflow
src/locales/default/*.ts fileslobe-i18n CLI with OpenAI API to generate translationslocales/{locale}/ directoriesThe lobe-i18n CLI tool is a specialized translation utility that:
{{name}}, {{credit}})Sources: High-level system architecture Diagram 8, .eslintrc.js1-50
The application automatically detects the user's preferred language at runtime using browser preferences.
Locale Detection Flow:
Locale files are loaded dynamically at runtime based on the detected or selected language:
Locale strings support variable interpolation for dynamic content:
Example from common.ts:
At runtime, {{credit}} is replaced with the actual value.
Sources: src/locales/default/common.ts1-50 locales/en-US/common.json1-50
To add or update translations manually:
Update TypeScript Source (if adding new keys):
src/locales/default/{domain}.tsUpdate JSON Files:
locales/{locale}/{domain}.json for each target languageTest Locally:
For bulk translation updates:
src/locales/default/Translation Quality Considerations:
| Aspect | Approach |
|---|---|
| Technical Terms | Preserved in original language or transliterated |
| Brand Names | Kept in original (e.g., "LobeChat", "OpenAI") |
| Variable Placeholders | Maintained exactly (e.g., {{name}}) |
| Nested Keys | Structure preserved across all languages |
| Context Preservation | Domain-specific terminology respected |
Sources: src/locales/default/common.ts1-100 src/locales/default/setting.ts1-100 locales/zh-CN/common.json1-50
Structure of common.json:
| Key | Purpose | Example (en-US) | Example (zh-CN) |
|---|---|---|---|
about | About link | "About" | "关于" |
advanceSettings | Advanced settings label | "Advanced Settings" | "高级设置" |
alert.cloud.action | Cloud service CTA | "Try now" | "立即体验" |
alert.cloud.desc | Cloud service description | "All registered users get {{credit}} free..." | "所有注册用户每月获得 {{credit}} 免费..." |
Structure of setting.json:
| Key Pattern | Purpose |
|---|---|
_cloud.officialProvider | Provider branding with variable |
accountDeletion.* | Account deletion flow strings |
about.title | Settings page titles |
llm.{provider}.* | Provider-specific settings |
Structure of plugin.json:
| Key Pattern | Purpose |
|---|---|
arguments.title | Plugin argument section title |
builtins.{plugin}.apiName.* | Built-in plugin API names |
builtins.{plugin}.description | Plugin descriptions |
Sources: locales/en-US/common.json1-50 locales/zh-CN/common.json1-50 locales/en-US/setting.json1-50 locales/zh-CN/setting.json1-50 locales/en-US/plugin.json1-50
LobeChat's i18n system provides comprehensive language support through:
This architecture enables rapid internationalization while maintaining translation quality and developer experience.
Sources: High-level system architecture Diagram 8, src/locales/default/common.ts1-50 locales/en-US/common.json1-50 locales/zh-CN/common.json1-50 locales/ja-JP/models.json1-50 locales/ko-KR/models.json1-50
Refresh this wiki