mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-25 11:20:07 +08:00
docs(i18n): update i18n documentation to reflect english as source language
- 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
parent
7365c1ca1a
commit
e5232b1fbb
@ -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:
|
||||
|
||||
### `check:i18n` - Validate i18n Structure
|
||||
### `i18n:check` - Validate i18n Structure
|
||||
|
||||
This script checks:
|
||||
|
||||
@ -116,28 +116,30 @@ This script checks:
|
||||
- Whether keys are properly sorted
|
||||
|
||||
```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]`
|
||||
2. Removing obsolete keys
|
||||
3. Sorting keys automatically
|
||||
|
||||
You can override this behavior by setting the `BASE_LOCALE` environment variable.
|
||||
|
||||
```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
|
||||
API_KEY="sk-xxx"
|
||||
@ -145,33 +147,23 @@ BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1/"
|
||||
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
|
||||
yarn auto:i18n
|
||||
```
|
||||
|
||||
### `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
|
||||
yarn i18n:auto
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
1. During development, first add the required text in `zh-cn.json`
|
||||
2. Confirm it displays correctly in the Chinese environment
|
||||
3. Run `yarn sync:i18n` to propagate the keys to other language files
|
||||
4. Run `yarn auto:i18n` to perform machine translation
|
||||
5. Grab a coffee and let the magic happen!
|
||||
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 the text displays correctly in the UI
|
||||
3. Use `yarn i18n:sync` to sync the text to other language files
|
||||
4. Use `yarn i18n:auto` to perform automatic translation
|
||||
5. Grab a coffee and wait for the translation to complete!
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Chinese as Source Language**: All development starts in Chinese, then translates to other languages.
|
||||
2. **Run Check Script Before Commit**: Use `yarn check:i18n` to catch i18n issues early.
|
||||
1. **Use English as Source Language**: All development starts in English, then translates to other languages.
|
||||
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.
|
||||
4. **Keep Keys Semantically Clear**: Keys should clearly express their purpose, e.g., `user.profile.avatar.upload.error`
|
||||
|
||||
@ -23,9 +23,9 @@ i18n ally是一个强大的VSCode插件，它能在开发阶段提供实时反
|
||||
|
||||
## i18n 约定
|
||||
|
||||
### **绝对避免使用flat格式**
|
||||
### **避免使用flat格式**
|
||||
|
||||
绝对避免使用flat格式，如`"add.button.tip": "添加"`。应采用清晰的嵌套结构：
|
||||
避免使用flat格式，如`"add.button.tip": "添加"`。应采用清晰的嵌套结构：
|
||||
|
||||
```json
|
||||
// 错误示例 - flat结构
|
||||
@ -101,7 +101,7 @@ export const getThemeModeLabel = (key: string): string => {
|
||||
|
||||
项目中有一系列脚本来自动化i18n相关任务：
|
||||
|
||||
### `check:i18n` - 检查i18n结构
|
||||
### `i18n:check` - 检查i18n结构
|
||||
|
||||
此脚本会检查：
|
||||
|
||||
@ -111,26 +111,28 @@ export const getThemeModeLabel = (key: string): string => {
|
||||
- 是否已经有序
|
||||
|
||||
```bash
|
||||
yarn check:i18n
|
||||
yarn i18n:check
|
||||
```
|
||||
|
||||
### `sync:i18n` - 同步json结构与排序
|
||||
### `i18n:sync` - 同步json结构与排序
|
||||
|
||||
此脚本以`zh-cn.json`文件为基准，将结构同步到其他语言文件，包括：
|
||||
此脚本默认以`en-us.json`文件为基准，将结构同步到其他语言文件，包括：
|
||||
|
||||
1. 添加缺失的键。缺少的翻译内容会以`[to be translated]`标记
|
||||
2. 删除多余的键
|
||||
3. 自动排序
|
||||
|
||||
你也可以设置环境变量`BASE_LOCALE`来覆盖这一行为。
|
||||
|
||||
```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`文件来添加环境变量。
|
||||
|
||||
```bash
|
||||
yarn auto:i18n
|
||||
```
|
||||
|
||||
### `update:i18n` - 对象级别翻译更新
|
||||
|
||||
对`src/renderer/src/i18n/translate`中的语言文件进行对象级别的翻译更新，保留已有翻译，只更新新增内容。
|
||||
|
||||
**不建议**使用该脚本，更推荐使用`auto:i18n`进行翻译。
|
||||
|
||||
```bash
|
||||
yarn update:i18n
|
||||
yarn i18n:auto
|
||||
```
|
||||
|
||||
### 工作流
|
||||
|
||||
1. 开发阶段，先在`zh-cn.json`中添加所需文案
|
||||
2. 确认在中文环境下显示无误后，使用`yarn sync:i18n`将文案同步到其他语言文件
|
||||
3. 使用`yarn auto:i18n`进行自动翻译
|
||||
1. 开发阶段，先在`en-us.json`中添加所需文案。你可以利用 i18n-ally 插件提供的快速修复功能轻松完成这一点。
|
||||
2. 确认文案在 UI 中显示无误后，使用`yarn i18n:sync`将文案同步到其他语言文件
|
||||
3. 使用`yarn i18n:auto`进行自动翻译
|
||||
4. 喝杯咖啡，等翻译完成吧！
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **以中文为源语言**：所有开发首先使用中文，再翻译为其他语言
|
||||
2. **提交前运行检查脚本**：使用`yarn check:i18n`检查i18n是否有问题
|
||||
1. **以英文为源语言**：所有开发首先使用英文，再翻译为其他语言
|
||||
2. **提交前运行检查脚本**：使用`yarn i18n:check`检查i18n是否有问题
|
||||
3. **小步提交翻译**：避免积累大量未翻译文本
|
||||
4. **保持key语义明确**：key应能清晰表达其用途，如`user.profile.avatar.upload.error`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user