mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-19 14:41:24 +08:00
f2b4a2382b
* refactor: rename i18n commands for better consistency - Rename `check:i18n` to `i18n:check` - Rename `sync:i18n` to `i18n:sync` - Rename `update:i18n` to `i18n:translate` (clearer purpose) - Rename `auto:i18n` to `i18n:all` (runs check, sync, and translate) - Update lint script to use new `i18n:check` command name This follows the common naming convention of grouping related commands under a namespace prefix (e.g., `test:main`, `test:renderer`). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor: update i18n command names and improve documentation - Renamed i18n commands for consistency: `sync:i18n` to `i18n:sync`, `check:i18n` to `i18n:check`, and `auto:i18n` to `i18n:translate`. - Updated relevant documentation and scripts to reflect new command names. - Improved formatting and clarity in i18n-related guides and scripts. This change enhances the clarity and usability of i18n commands across the project. --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
162 lines
4.5 KiB
Markdown
162 lines
4.5 KiB
Markdown
# 如何优雅地做好 i18n
|
||
|
||
## 使用 i18n ally 插件提升开发体验
|
||
|
||
i18n ally 是一个强大的 VSCode 插件，它能在开发阶段提供实时反馈，帮助开发者更早发现文案缺失和错译问题。
|
||
|
||
项目中已经配置好了插件设置，直接安装即可。
|
||
|
||
### 开发时优势
|
||
|
||
- **实时预览**：翻译文案会直接显示在编辑器中
|
||
- **错误检测**：自动追踪标记出缺失的翻译或未使用的 key
|
||
- **快速跳转**：可通过 key 直接跳转到定义处（Ctrl/Cmd + click)
|
||
- **自动补全**：输入 i18n key 时提供自动补全建议
|
||
|
||
### 效果展示
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## i18n 约定
|
||
|
||
### **绝对避免使用 flat 格式**
|
||
|
||
绝对避免使用 flat 格式，如`"add.button.tip": "添加"`。应采用清晰的嵌套结构：
|
||
|
||
```json
|
||
// 错误示例 - flat结构
|
||
{
|
||
"add.button.tip": "添加",
|
||
"delete.button.tip": "删除"
|
||
}
|
||
|
||
// 正确示例 - 嵌套结构
|
||
{
|
||
"add": {
|
||
"button": {
|
||
"tip": "添加"
|
||
}
|
||
},
|
||
"delete": {
|
||
"button": {
|
||
"tip": "删除"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 为什么要使用嵌套结构
|
||
|
||
1. **自然分组**：通过对象结构天然能将相关上下文的文案分到一个组别中
|
||
2. **插件要求**：i18n ally 插件需要嵌套或 flat 格式其一的文件才能正常分析
|
||
|
||
### **避免在`t()`中使用模板字符串**
|
||
|
||
**强烈建议避免使用模板字符串**进行动态插值。虽然模板字符串在 JavaScript 开发中非常方便，但在国际化场景下会带来一系列问题。
|
||
|
||
1. **插件无法跟踪**
|
||
i18n ally 等工具无法解析模板字符串中的动态内容，导致：
|
||
|
||
- 无法正确显示实时预览
|
||
- 无法检测翻译缺失
|
||
- 无法提供跳转到定义的功能
|
||
|
||
```javascript
|
||
// 不推荐 - 插件无法解析
|
||
const message = t(`fruits.${fruit}`);
|
||
```
|
||
|
||
2. **编辑器无法实时渲染**
|
||
在 IDE 中，模板字符串会显示为原始代码而非最终翻译结果，降低了开发体验。
|
||
|
||
3. **更难以维护**
|
||
由于插件无法跟踪这样的文案，编辑器中也无法渲染，开发者必须人工确认语言文件中是否存在相应的文案。
|
||
|
||
### 推荐做法
|
||
|
||
为了避免键的缺失，所有需要动态翻译的文本都应当先维护一个`FooKeyMap`，再通过函数获取翻译文本。
|
||
|
||
例如：
|
||
|
||
```ts
|
||
// src/renderer/src/i18n/label.ts
|
||
const themeModeKeyMap = {
|
||
dark: "settings.theme.dark",
|
||
light: "settings.theme.light",
|
||
system: "settings.theme.system",
|
||
} as const;
|
||
|
||
export const getThemeModeLabel = (key: string): string => {
|
||
return themeModeKeyMap[key] ? t(themeModeKeyMap[key]) : key;
|
||
};
|
||
```
|
||
|
||
通过避免模板字符串，可以获得更好的开发体验、更可靠的翻译检查以及更易维护的代码库。
|
||
|
||
## 自动化脚本
|
||
|
||
项目中有一系列脚本来自动化 i18n 相关任务：
|
||
|
||
### `i18n:check` - 检查 i18n 结构
|
||
|
||
此脚本会检查：
|
||
|
||
- 所有语言文件是否为嵌套结构
|
||
- 是否存在缺失的 key
|
||
- 是否存在多余的 key
|
||
- 是否已经有序
|
||
|
||
```bash
|
||
yarn i18n:check
|
||
```
|
||
|
||
### `i18n:sync` - 同步 json 结构与排序
|
||
|
||
此脚本以`zh-cn.json`文件为基准，将结构同步到其他语言文件，包括：
|
||
|
||
1. 添加缺失的键。缺少的翻译内容会以`[to be translated]`标记
|
||
2. 删除多余的键
|
||
3. 自动排序
|
||
|
||
```bash
|
||
yarn i18n:sync
|
||
```
|
||
|
||
### `i18n:translate` - 自动翻译待翻译文本
|
||
|
||
次脚本自动将标记为待翻译的文本通过机器翻译填充。
|
||
|
||
通常，在`zh-cn.json`中添加所需文案后，执行`i18n:sync`即可自动完成翻译。
|
||
|
||
使用该脚本前，需要配置环境变量，例如：
|
||
|
||
```bash
|
||
API_KEY="sk-xxx"
|
||
BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1/"
|
||
MODEL="qwen-plus-latest"
|
||
```
|
||
|
||
你也可以通过直接编辑`.env`文件来添加环境变量。
|
||
|
||
```bash
|
||
yarn i18n:translate
|
||
```
|
||
|
||
### 工作流
|
||
|
||
1. 开发阶段，先在`zh-cn.json`中添加所需文案
|
||
2. 确认在中文环境下显示无误后，使用`yarn i18n:sync`将文案同步到其他语言文件
|
||
3. 使用`yarn i18n:translate`进行自动翻译
|
||
4. 喝杯咖啡，等翻译完成吧！
|
||
|
||
## 最佳实践
|
||
|
||
1. **以中文为源语言**：所有开发首先使用中文，再翻译为其他语言
|
||
2. **提交前运行检查脚本**：使用`yarn i18n:check`检查 i18n 是否有问题
|
||
3. **小步提交翻译**：避免积累大量未翻译文本
|
||
4. **保持 key 语义明确**：key 应能清晰表达其用途，如`user.profile.avatar.upload.error`
|