Northern_Lights/cherry-studio
1
0
Fork 0
mirror of https://github.com/CherryHQ/cherry-studio.git synced 2026-01-05 20:41:30 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs(i18n): update i18n documentation to reflect english as source language

Browse Source 
- Change source language from Chinese to English in both docs
- Update script names from check:i18n/sync:i18n/auto:i18n to i18n:check/i18n:sync/i18n:auto
- Remove deprecated update:i18n script references
- Clarify base locale behavior and environment variable usage
This commit is contained in:
icarus 2025-10-23 12:25:27 +08:00
parent 7365c1ca1a
commit e5232b1fbb
2 changed files with 38 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/technical/how-to-i18n-en.md
View File

@ -107,7 +107,7 @@ By avoiding template strings, you gain better developer experience, more reliabl
The project includes several scripts to automate i18n-related tasks: The project includes several scripts to automate i18n-related tasks:
### `check:i18n` - Validate i18n Structure ### `i18n:check` - Validate i18n Structure
This script checks: This script checks:
@ -116,28 +116,30 @@ This script checks:
- Whether keys are properly sorted - Whether keys are properly sorted
```bash ```bash
yarn check:i18n yarn i18n:check
``` ```
### `sync:i18n` - Synchronize JSON Structure and Sort Order ### `i18n:sync` - Synchronize JSON Structure and Sort Order
This script uses `zh-cn.json` as the source of truth to sync structure across all language files, including: By default, this script uses `en-us.json` as the source of truth to sync structure across all language files, including:
1. Adding missing keys, with placeholder `[to be translated]` 1. Adding missing keys, with placeholder `[to be translated]`
2. Removing obsolete keys 2. Removing obsolete keys
3. Sorting keys automatically 3. Sorting keys automatically
You can override this behavior by setting the `BASE_LOCALE` environment variable.
```bash ```bash
yarn sync:i18n yarn i18n:sync
``` ```
### `auto:i18n` - Automatically Translate Pending Texts ### `i18n:auto` - Automatically Translate Pending Texts
This script fills in texts marked as `[to be translated]` using machine translation. This script automatically translates texts marked as `[to be translated]` using machine translation. Similar to `i18n:sync`, it defaults to using `en-us.json` as the base, but you can override this behavior by setting the `BASE_LOCALE` environment variable.
Typically, after adding new texts in `zh-cn.json`, run `sync:i18n`, then `auto:i18n` to complete translations. Typically, after adding required texts to `en-us.json`, running `i18n:sync && i18n:auto` will automatically complete the translations.
Before using this script, set the required environment variables: Before using this script, you need to configure environment variables, for example:
```bash ```bash
API_KEY="sk-xxx" API_KEY="sk-xxx"
@ -145,33 +147,23 @@ BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1/"
MODEL="qwen-plus-latest" MODEL="qwen-plus-latest"
``` ```
Alternatively, add these variables directly to your `.env` file. You can also add environment variables by directly editing the `.env` file.
```bash ```bash
yarn auto:i18n yarn i18n:auto
```
### `update:i18n` - Object-level Translation Update
Updates translations in language files under `src/renderer/src/i18n/translate` at the object level, preserving existing translations and only updating new content.
**Not recommended** — prefer `auto:i18n` for translation tasks.
```bash
yarn update:i18n
``` ```
### Workflow ### Workflow
1. During development, first add the required text in `zh-cn.json` 1. During development, first add the required text in `en-us.json`. You can use the quick fix functionality provided by the i18n-ally plugin to easily accomplish this.
2. Confirm it displays correctly in the Chinese environment 2. Confirm the text displays correctly in the UI
3. Run `yarn sync:i18n` to propagate the keys to other language files 3. Use `yarn i18n:sync` to sync the text to other language files
4. Run `yarn auto:i18n` to perform machine translation 4. Use `yarn i18n:auto` to perform automatic translation
5. Grab a coffee and let the magic happen! 5. Grab a coffee and wait for the translation to complete!
## Best Practices ## Best Practices
1. **Use Chinese as Source Language**: All development starts in Chinese, then translates to other languages. 1. **Use English as Source Language**: All development starts in English, then translates to other languages.
2. **Run Check Script Before Commit**: Use `yarn check:i18n` to catch i18n issues early. 2. **Run Check Script Before Commit**: Use `yarn i18n:check` to catch i18n issues early.
3. **Translate in Small Increments**: Avoid accumulating a large backlog of untranslated content. 3. **Translate in Small Increments**: Avoid accumulating a large backlog of untranslated content.
4. **Keep Keys Semantically Clear**: Keys should clearly express their purpose, e.g., `user.profile.avatar.upload.error` 4. **Keep Keys Semantically Clear**: Keys should clearly express their purpose, e.g., `user.profile.avatar.upload.error`

44
docs/technical/how-to-i18n-zh.md
View File

@ -23,9 +23,9 @@ i18n ally是一个强大的VSCode插件，它能在开发阶段提供实时反
## i18n 约定 ## i18n 约定
### **绝对避免使用flat格式** ### **避免使用flat格式**
绝对避免使用flat格式，如`"add.button.tip": "添加"`。应采用清晰的嵌套结构： 避免使用flat格式，如`"add.button.tip": "添加"`。应采用清晰的嵌套结构：
```json ```json
// 错误示例 - flat结构 // 错误示例 - flat结构
@ -101,7 +101,7 @@ export const getThemeModeLabel = (key: string): string => {
项目中有一系列脚本来自动化i18n相关任务： 项目中有一系列脚本来自动化i18n相关任务：
### `check:i18n` - 检查i18n结构 ### `i18n:check` - 检查i18n结构
此脚本会检查： 此脚本会检查：
@ -111,26 +111,28 @@ export const getThemeModeLabel = (key: string): string => {
- 是否已经有序 - 是否已经有序
```bash ```bash
yarn check:i18n yarn i18n:check
``` ```
### `sync:i18n` - 同步json结构与排序 ### `i18n:sync` - 同步json结构与排序
此脚本以`zh-cn.json`文件为基准，将结构同步到其他语言文件，包括： 此脚本默认以`en-us.json`文件为基准，将结构同步到其他语言文件，包括：
1. 添加缺失的键。缺少的翻译内容会以`[to be translated]`标记 1. 添加缺失的键。缺少的翻译内容会以`[to be translated]`标记
2. 删除多余的键 2. 删除多余的键
3. 自动排序 3. 自动排序
你也可以设置环境变量`BASE_LOCALE`来覆盖这一行为。
```bash ```bash
yarn sync:i18n yarn i18n:auto
``` ```
### `auto:i18n` - 自动翻译待翻译文本 ### `i18n:auto` - 自动翻译待翻译文本
次脚本自动将标记为待翻译的文本通过机器翻译填充。 此脚本自动将标记为待翻译的文本通过机器翻译填充。与 `i18n:sync` 相同，默认以`en-us.json`文件为基准，也可以设置环境变量`BASE_LOCALE`来覆盖这一行为。
通常，在`zh-cn.json`中添加所需文案后，执行`sync:i18n`即可自动完成翻译。 通常，在`en-us.json`中添加所需文案后，执行`i18n:sync && i18n:auto`即可自动完成翻译。
使用该脚本前，需要配置环境变量，例如： 使用该脚本前，需要配置环境变量，例如：
@ -143,29 +145,19 @@ MODEL="qwen-plus-latest"
你也可以通过直接编辑`.env`文件来添加环境变量。 你也可以通过直接编辑`.env`文件来添加环境变量。
```bash ```bash
yarn auto:i18n yarn i18n:auto
```
### `update:i18n` - 对象级别翻译更新
对`src/renderer/src/i18n/translate`中的语言文件进行对象级别的翻译更新，保留已有翻译，只更新新增内容。
**不建议**使用该脚本，更推荐使用`auto:i18n`进行翻译。
```bash
yarn update:i18n
``` ```
### 工作流 ### 工作流
1. 开发阶段，先在`zh-cn.json`中添加所需文案 1. 开发阶段，先在`en-us.json`中添加所需文案。你可以利用 i18n-ally 插件提供的快速修复功能轻松完成这一点。
2. 确认在中文环境下显示无误后，使用`yarn sync:i18n`将文案同步到其他语言文件 2. 确认文案在 UI 中显示无误后，使用`yarn i18n:sync`将文案同步到其他语言文件
3. 使用`yarn auto:i18n`进行自动翻译 3. 使用`yarn i18n:auto`进行自动翻译
4. 喝杯咖啡，等翻译完成吧！ 4. 喝杯咖啡，等翻译完成吧！
## 最佳实践 ## 最佳实践
1. **以中文为源语言**：所有开发首先使用中文，再翻译为其他语言 1. **以英文为源语言**：所有开发首先使用英文，再翻译为其他语言
2. **提交前运行检查脚本**：使用`yarn check:i18n`检查i18n是否有问题 2. **提交前运行检查脚本**：使用`yarn i18n:check`检查i18n是否有问题
3. **小步提交翻译**：避免积累大量未翻译文本 3. **小步提交翻译**：避免积累大量未翻译文本
4. **保持key语义明确**：key应能清晰表达其用途，如`user.profile.avatar.upload.error` 4. **保持key语义明确**：key应能清晰表达其用途，如`user.profile.avatar.upload.error`