22globs: *.tsx
33alwaysApply: false
44---
5- # LobeChat 国际化指南
5+ # LobeChat Internationalization Guide
66
7- ## 架构概览
7+ ## Key Points
88
9- LobeChat 使用 react-i18next 进行国际化,采用良好的命名空间架构:
9+ - Default language: Chinese (zh-CN) as the source language
10+ - Supported languages: 18 languages including English, Japanese, Korean, Arabic, etc.
11+ - Framework: react-i18next with Next.js app router
12+ - Translation automation: @lobehub/i18n-cli for automatic translation, config file: .i18nrc.js
13+ - Never manually modify any json file. You can only modify files in `default` folder
1014
11- - 默认语言:中文(zh-CN),作为源语言
12- - 支持语言:18 种语言,包括英语、日语、韩语、阿拉伯语等
13- - 框架:react-i18next 配合 Next.js app router
14- - 翻译自动化:@lobehub/i18n-cli 用于自动翻译,配置文件:.i18nrc.js
15-
16- ## 目录结构
15+ ## Directory Structure
1716
1817```
1918src/locales/
20- ├── default/ # 源语言文件( zh-CN)
21- │ ├── index.ts # 命名空间导出
22- │ ├── common.ts # 通用翻译
23- │ ├── chat.ts # 聊天相关翻译
24- │ ├── setting.ts # 设置翻译
25- │ └── ... # 其他命名空间文件
26- └── resources.ts # 类型定义和语言配置
27-
28- locales/ # 翻译文件
29- ├── en-US/ # 英语翻译
30- │ ├── common.json # 通用翻译
31- │ ├── chat.json # 聊天翻译
32- │ ├── setting.json # 设置翻译
33- │ └── ... # 其他命名空间 JSON 文件
34- ├── ja-JP/ # 日语翻译
19+ ├── default/ # Source language files ( zh-CN)
20+ │ ├── index.ts # Namespace exports
21+ │ ├── common.ts # Common translations
22+ │ ├── chat.ts # Chat-related translations
23+ │ ├── setting.ts # Settings translations
24+ │ └── ... # Other namespace files
25+ └── resources.ts # Type definitions and language configuration
26+
27+ locales/ # Translation files
28+ ├── en-US/ # English translations
29+ │ ├── common.json # Common translations
30+ │ ├── chat.json # Chat translations
31+ │ ├── setting.json # Settings translations
32+ │ └── ... # Other namespace JSON files
33+ ├── ja-JP/ # Japanese translations
3534│ ├── common.json
3635│ ├── chat.json
3736│ └── ...
38- └── ... # 其他语言文件夹
37+ └── ... # Other language folders
3938```
4039
41- ## 添加新翻译的工作流程
40+ ## Workflow for Adding New Translations
4241
43- ### 1. 添加新的翻译键
42+ ### 1. Adding New Translation Keys
4443
45- 第一步:在 src/locales/default 目录下的相应命名空间文件中添加翻译键
44+ Step 1: Add translation keys in the corresponding namespace files under src/locales/default directory
4645
4746```typescript
48- // 示例: src/locales/default/common.ts
47+ // Example: src/locales/default/common.ts
4948export default {
50- // ... 现有键
51- newFeature: {
52- title: " 新功能标题" ,
53- description: " 功能描述文案" ,
54- button: " 操作按钮" ,
55- },
49+ // ... existing keys
50+ newFeature: {
51+ title: ' 新功能标题' ,
52+ description: ' 功能描述文案' ,
53+ button: ' 操作按钮' ,
54+ },
5655};
5756```
5857
59- 第二步:如果创建新命名空间,需要在 src/locales/default/index.ts 中导出
58+ Step 2: If creating a new namespace, export it in src/locales/default/index.ts
6059
6160```typescript
62- import newNamespace from " ./newNamespace" ;
61+ import newNamespace from ' ./newNamespace' ;
6362
6463const resources = {
65- // ... 现有命名空间
66- newNamespace,
64+ // ... existing namespaces
65+ newNamespace,
6766} as const;
6867```
6968
70- ### 2. 翻译过程
69+ ### 2. Translation Process
7170
72- 开发模式:
71+ Development mode:
7372
74- 一般情况下不需要你帮我跑自动翻译工具,跑一次很久,需要的时候我会自己跑。
75- 但是为了立马能看到效果,还是需要先翻译 `locales/zh-CN/namespace.json`,不需要翻译其它语言。
73+ Generally, you don't need to help me run the automatic translation tool as it takes a long time. I'll run it myself when needed. However, to see immediate results, you still need to translate `locales/zh-CN/namespace.json` first, no need to translate other languages.
7674
77- 生产模式:
75+ Production mode:
7876
7977```bash
80- # 为所有语言生成翻译
78+ # Generate translations for all languages
8179npm run i18n
8280```
8381
84- ## 在组件中使用
82+ ## Usage in Components
8583
86- ### 基本用法
84+ ### Basic Usage
8785
8886```tsx
89- import { useTranslation } from " react-i18next" ;
87+ import { useTranslation } from ' react-i18next' ;
9088
9189const MyComponent = () => {
92- const { t } = useTranslation(" common" );
93-
94- return (
95- <div>
96- <h1>{t(" newFeature.title" )}</h1>
97- <p>{t(" newFeature.description" )}</p>
98- <button>{t(" newFeature.button" )}</button>
99- </div>
100- );
90+ const { t } = useTranslation(' common' );
91+
92+ return (
93+ <div>
94+ <h1>{t(' newFeature.title' )}</h1>
95+ <p>{t(' newFeature.description' )}</p>
96+ <button>{t(' newFeature.button' )}</button>
97+ </div>
98+ );
10199};
102100```
103101
104- ### 带参数的用法
102+ ### Usage with Parameters
105103
106104```tsx
107- const { t } = useTranslation(" common" );
105+ const { t } = useTranslation(' common' );
108106
109- <p>{t(" welcome.message" , { name: " John" })}</p>;
107+ <p>{t(' welcome.message' , { name: ' John' })}</p>;
110108
111- // 对应的语言文件:
112- // welcome: { message: '欢迎 {{name}} 使用 !' }
109+ // Corresponding language file:
110+ // welcome: { message: 'Welcome {{name}}!' }
113111```
114112
115- ### 多个命名空间
113+ ### Multiple Namespaces
116114
117115```tsx
118116const { t } = useTranslation(['common', 'chat']);
@@ -121,59 +119,63 @@ const { t } = useTranslation(['common', 'chat']);
121119<span>{t('chat:typing')}</span>
122120```
123121
124- ## 类型安全
122+ ## Type Safety
125123
126- 项目使用 TypeScript 实现类型安全的翻译,类型从 src/locales/resources.ts 自动生成:
124+ The project uses TypeScript to implement type-safe translations, with types automatically generated from src/locales/resources.ts:
127125
128126```typescript
129- import type { DefaultResources, NS, Locales } from " @/locales/resources" ;
127+ import type { DefaultResources, Locales, NS } from ' @/locales/resources' ;
130128
131- // 可用类型:
132- // - NS: 可用命名空间键 ('common' | 'chat' | 'setting' | ...)
133- // - Locales: 支持的语言代码 ('en-US' | 'zh-CN' | 'ja-JP' | ...)
129+ // Available types:
130+ // - NS: Available namespace keys ('common' | 'chat' | 'setting' | ...)
131+ // - Locales: Supported language codes ('en-US' | 'zh-CN' | 'ja-JP' | ...)
134132
135- const namespace: NS = " common" ;
136- const locale: Locales = " en-US" ;
133+ const namespace: NS = ' common' ;
134+ const locale: Locales = ' en-US' ;
137135```
138136
139- ## 最佳实践
137+ ## Best Practices
140138
141- ### 1. 命名空间组织
139+ ### 1. Namespace Organization
142140
143- - common: 共享 UI 元素(按钮、标签、操作)
144- - chat: 聊天特定功能
145- - setting: 配置和设置
146- - error: 错误消息和处理
147- - [feature]: 功能特定或页面特定的命名空间
148- - components: 可复用组件文案
141+ - common: Shared UI elements (buttons, labels, actions)
142+ - chat: Chat-specific functionality
143+ - setting: Configuration and settings
144+ - error: Error messages and handling
145+ - [feature]: Feature-specific or page-specific namespaces
146+ - components: Reusable component text
149147
150- ### 2. 键命名约定
148+ ### 2. Key Naming Conventions
151149
152150```typescript
153- // ✅ 好:层次结构
151+ // ✅ Good: Hierarchical structure
154152export default {
155- modal: {
156- confirm: {
157- title: "确认操作",
158- message: "确定要执行此操作吗?",
159- actions: {
160- confirm: "确认",
161- cancel: "取消",
162- },
163- },
153+ modal: {
154+ confirm: {
155+ title: '确认操作',
156+ message: '确定要执行此操作吗?',
157+ actions: {
158+ confirm: '确认',
159+ cancel: '取消',
160+ },
164161 },
162+ },
165163};
166164
167- // ❌ 避免:扁平结构
165+ // ❌ Avoid: Flat structure
168166export default {
169- modalConfirmTitle: " 确认操作" ,
170- modalConfirmMessage: " 确定要执行此操作吗?" ,
167+ modalConfirmTitle: ' 确认操作' ,
168+ modalConfirmMessage: ' 确定要执行此操作吗?' ,
171169};
172170```
173171
174- ## 故障排除
172+ ## Troubleshooting
173+
174+ ### Missing Translation Keys
175175
176- ### 缺少翻译键
176+ - Check if the key exists in src/locales/default/namespace.ts
177+ - Ensure the namespace is correctly imported in the component
178+ - Ensure new namespaces are exported in src/locales/default/index.ts
177179
178180- 检查键是否存在于 src/locales/default/namespace.ts 中
179181- 确保在组件中正确导入命名空间
0 commit comments