mirror of https://github.com/CherryHQ/cherry-studio.git synced 2025-12-24 10:40:07 +08:00

chore(i18n): forced nested structure to support i18n ally (#8457 )

* chore(i18n): 更新i18n文件为嵌套结构以适应插件

* feat(i18n): 添加自动翻译脚本处理待翻译文本

添加自动翻译脚本auto-translate-i18n.ts，用于处理以[to be translated]开头的待翻译文本
在package.json中添加对应的运行命令auto:i18n

* chore(i18n): 更新嵌套结构

* chore(i18n): 更新多语言翻译文件并改进翻译逻辑

更新了多个语言的翻译文件，替换了"[to be translated]"标记为实际翻译内容
改进auto-translate-i18n.ts中的翻译逻辑，添加错误处理和日志输出
部分数组格式的翻译描述自动改为对象格式

* fix(i18n): 修复嵌套结构检查并改进错误处理

添加对嵌套结构中使用点符号的检查，确保使用严格嵌套结构
改进错误处理，在检查失败时输出更清晰的错误信息

* fix(测试): 更新下载失败测试中的翻译键名

* test(下载): 移除重复的下载失败翻译并更新测试

* feat(eslint): 添加规则，警告不建议在t()函数中使用模板字符串

* style: 使用单引号替换模板字符串中的反引号

* docs(.vscode): 添加i18n-ally扩展推荐到vscode配置

* fix: 在自动翻译脚本中停止进度条显示

确保在脚本执行完成后正确停止进度条，避免控制台输出混乱

* fix(i18n): 修复模型列表添加确认对话框的翻译键名

更新多语言文件中模型管理部分的翻译结构，将"add_listed"从字符串改为包含"confirm"和"key"的对象
同时修正EditModelsPopup组件中对应的翻译键引用

* chore: 注释掉i18n-ally命名空间配置

* docs: 添加国际化(i18n)最佳实践文档

添加中英文双语的技术文档，详细介绍项目中的i18n实现方案、工具链和最佳实践
包含i18n ally插件使用指南、自动化脚本说明以及代码规范要求

* docs(国际化): 更新i18n文档中的键名格式示例

将文档中错误的flat格式示例从下划线命名改为点分隔命名，以保持一致性

* refactor(i18n): 统一翻译键名从.key后缀改为.label后缀

* chore(i18n): sort

* refactor(locales): 使用 Object.fromEntries 重构 locales 对象

* feat(i18n): 添加机器翻译的语言支持

新增希腊语、西班牙语、法语和葡萄牙语的机器翻译支持，并调整语言资源加载顺序

2025-07-25 17:36:04 +08:00

4.4 KiB

Raw Blame History

如何优雅地做好 i18n

使用i18n ally插件提升开发体验

i18n ally是一个强大的VSCode插件，它能在开发阶段提供实时反馈，帮助开发者更早发现文案缺失和错译问题。

项目中已经配置好了插件设置，直接安装即可。

开发时优势

实时预览：翻译文案会直接显示在编辑器中
错误检测：自动追踪标记出缺失的翻译或未使用的key
快速跳转：可通过key直接跳转到定义处（Ctrl/Cmd + click)
自动补全：输入i18n key时提供自动补全建议

效果展示

i18n 约定

绝对避免使用flat格式

绝对避免使用flat格式，如"add.button.tip": "添加"。应采用清晰的嵌套结构：

// 错误示例 - flat结构
{
  "add.button.tip": "添加",
  "delete.button.tip": "删除"
}

// 正确示例 - 嵌套结构
{
  "add": {
    "button": {
      "tip": "添加"
    }
  },
  "delete": {
    "button": {
      "tip": "删除"
    }
  }
}

为什么要使用嵌套结构

自然分组：通过对象结构天然能将相关上下文的文案分到一个组别中
插件要求：i18n ally 插件需要嵌套或flat格式其一的文件才能正常分析

避免在`t()`中使用模板字符串

强烈建议避免使用模板字符串进行动态插值。虽然模板字符串在JavaScript开发中非常方便，但在国际化场景下会带来一系列问题。

插件无法跟踪 i18n ally等工具无法解析模板字符串中的动态内容，导致：
- 无法正确显示实时预览
- 无法检测翻译缺失
- 无法提供跳转到定义的功能
```
// 不推荐 - 插件无法解析
const message = t(`fruits.${fruit}`);
```
编辑器无法实时渲染 在IDE中，模板字符串会显示为原始代码而非最终翻译结果，降低了开发体验。
更难以维护 由于插件无法跟踪这样的文案，编辑器中也无法渲染，开发者必须人工确认语言文件中是否存在相应的文案。

自动化脚本

项目中有一系列脚本来自动化i18n相关任务：

`check:i18n` - 检查i18n结构

此脚本会检查：

所有语言文件是否为嵌套结构
是否存在缺失的key
是否存在多余的key
是否已经有序

yarn check:i18n

`sync:i18n` - 同步json结构与排序

此脚本以zh-cn.json文件为基准，将结构同步到其他语言文件，包括：

添加缺失的键。缺少的翻译内容会以[to be translated]标记
删除多余的键
自动排序

yarn sync:i18n

`auto:i18n` - 自动翻译待翻译文本

次脚本自动将标记为待翻译的文本通过机器翻译填充。

通常，在zh-cn.json中添加所需文案后，执行sync:i18n即可自动完成翻译。

使用该脚本前，需要配置环境变量，例如：

API_KEY="sk-xxx"
BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1/"
MODEL="qwen-plus-latest"

你也可以通过直接编辑.env文件来添加环境变量。

yarn auto:i18n

`update:i18n` - 对象级别翻译更新

对src/renderer/src/i18n/translate中的语言文件进行对象级别的翻译更新，保留已有翻译，只更新新增内容。

不建议使用该脚本，更推荐使用auto:i18n进行翻译。

yarn update:i18n

工作流

开发阶段，先在zh-cn.json中添加所需文案
确认在中文环境下显示无误后，使用yarn sync:i18n将文案同步到其他语言文件
使用yarn auto:i18n进行自动翻译
喝杯咖啡，等翻译完成吧！

最佳实践

以中文为源语言：所有开发首先使用中文，再翻译为其他语言
提交前运行检查脚本：使用yarn check:i18n检查i18n是否有问题
小步提交翻译：避免积累大量未翻译文本
保持key语义明确：key应能清晰表达其用途，如user.profile.avatar.upload.error

4.4 KiB Raw Blame History Unescape Escape