i18n 国际化

版本: v1.0.0+ | 4 语言支持 | 运行时切换

国际化模块为整个应用提供多语言支持，支持运行时动态切换语言，无需重启应用。

概述

i18n 国际化模块为 ChainlessChain 桌面应用提供完整的多语言支持，覆盖简体中文、English、Francais、Espanol 四种语言。系统支持运行时热切换（界面即时更新无需重启）、按功能模块命名空间组织翻译键、主进程与渲染进程统一翻译方案，以及翻译缺失时自动回退到默认语言的容错机制。

核心特性

🌍 4 语言支持: 简体中文、English、Francais、Espanol 完整翻译覆盖
🔄 运行时热切换: 动态切换语言，界面即时更新无需重启应用
📁 命名空间组织: 按功能模块（common/errors/menu/ai/...）结构化管理翻译键
🔗 前后端统一: 主进程与渲染进程共用同一套翻译方案，保持一致性
🛡️ 自动回退机制: 翻译缺失时自动回退到 zh-CN 默认语言，确保不出现空白

系统架构

┌──────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  渲染进程 (Vue3)  │────→│  i18n Core   │←────│  主进程 (Node)   │
│  t() / setLocale │     │  翻译引擎     │     │  t() / setLocale│
└──────────────────┘     └──────┬───────┘     └─────────────────┘
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
              ┌──────────┐ ┌────────┐ ┌──────────┐
              │ zh-CN.js │ │ en-US  │ │ fr-FR /  │
              │ 默认语言  │ │ .js    │ │ es-ES.js │
              └──────────┘ └────────┘ └──────────┘

回退链: 当前语言 → zh-CN (默认)

系统概述

支持语言

语言代码	语言	状态
`zh-CN`	简体中文	默认语言，完整翻译
`en-US`	English	完整翻译
`fr-FR`	Français	完整翻译
`es-ES`	Español	完整翻译

核心特性

运行时切换: 动态切换语言，界面即时更新
命名空间: 按功能模块组织翻译键
回退机制: 找不到翻译时自动回退到 zh-CN
主进程 + 渲染进程: 前后端统一的翻译方案

使用方式

翻译函数

javascript

const { t, setLocale, getLocale } = require("./i18n");

// 翻译
t("errors.notFound"); // "未找到" (zh-CN)
t("common.save"); // "保存"

// 切换语言
setLocale("en-US");
t("errors.notFound"); // "Not Found"

// 获取当前语言
getLocale(); // "en-US"

命名空间约定

翻译键结构:
├─ common.*          — 通用（保存、取消、确认...）
├─ errors.*          — 错误消息
├─ menu.*            — 菜单项
├─ settings.*        — 设置页面
├─ knowledge.*       — 知识库模块
├─ social.*          — 社交模块
├─ trading.*         — 交易模块
├─ ai.*              — AI 功能
└─ ...

API

函数	说明
`t(key)`	翻译键，返回当前语言的文本
`setLocale(locale)`	切换当前语言
`getLocale()`	获取当前语言代码
`getSupportedLocales()`	返回所有支持的语言列表

关键文件

文件	职责
`src/main/i18n/index.js`	i18n 核心模块
`src/main/i18n/locales/zh-CN.js`	简体中文翻译
`src/main/i18n/locales/en-US.js`	英文翻译
`src/main/i18n/locales/fr-FR.js`	法文翻译
`src/main/i18n/locales/es-ES.js`	西班牙文翻译

使用示例

主进程中使用翻译

javascript

const { t, setLocale, getLocale } = require('./i18n');

// 获取当前语言
console.log(getLocale()); // "zh-CN"

// 翻译错误消息
const msg = t('errors.networkTimeout'); // "网络连接超时"

// 切换到英文
setLocale('en-US');
console.log(t('errors.networkTimeout')); // "Network connection timed out"

// 获取所有支持的语言列表
const locales = getSupportedLocales();
// ['zh-CN', 'en-US', 'fr-FR', 'es-ES']

渲染进程（Vue3）中使用

vue

<template>
  <a-button @click="switchLang('en-US')">{{ t('common.switchLanguage') }}</a-button>
  <p>{{ t('settings.languageDescription') }}</p>
</template>

<script setup>
import { useI18n } from '@/composables/useI18n';
const { t, setLocale } = useI18n();

function switchLang(lang) {
  setLocale(lang); // 界面即时更新，无需重启
}
</script>

通过配置文件设置默认语言

json

{
  "app": {
    "language": "en-US"
  }
}

故障排查

翻译键显示为原始 key 而非翻译文本

当翻译缺失时系统会回退到 zh-CN。如果仍显示原始 key，说明 zh-CN 也缺少该翻译：

bash

# 检查翻译文件中是否存在对应的 key
# 在 src/main/i18n/locales/zh-CN.js 中搜索缺失的 key
# 添加翻译后重启应用即可

切换语言后部分界面未更新

确认组件使用了响应式的 t() 函数，而非在初始化时缓存了翻译结果：

javascript

// 错误：翻译结果在初始化时固化，切换语言后不会更新
const title = t('common.save');

// 正确：在 computed 或模板中使用，保持响应式
// <span>{{ t('common.save') }}</span>

新增语言后未显示在语言列表

确保在 src/main/i18n/index.js 的 supportedLocales 数组中注册了新语言，并在 locales/ 目录下创建对应的翻译文件。

配置参考

配置项	类型	默认值	说明
`app.language`	string	`"zh-CN"`	应用默认语言，写入 `.chainlesschain/config.json`
`i18n.fallbackLocale`	string	`"zh-CN"`	翻译缺失时的回退语言
`i18n.supportedLocales`	string[]	`["zh-CN","en-US","fr-FR","es-ES"]`	已注册的支持语言列表
`i18n.warnOnMissingKey`	boolean	`true`	翻译键缺失时是否在控制台打印警告
`i18n.persistLocale`	boolean	`true`	是否将用户切换的语言持久化到配置文件
`i18n.mainProcessSync`	boolean	`true`	渲染进程切换语言时是否同步通知主进程

通过配置文件设置初始语言：

json

{
  "app": {
    "language": "en-US"
  }
}

运行时通过 API 切换后语言选择会自动持久化（persistLocale: true），下次启动无需重新选择。

性能指标

指标	典型值	说明
模块初始化时间	< 5 ms	启动时加载全部 4 个语言包
单次 `t()` 调用耗时	< 0.05 ms	基于对象属性路径查找，O(1)
`setLocale()` 切换耗时	< 2 ms	切换内部引用，不重新解析文件
单语言包文件大小	~30 KB	未压缩，含所有命名空间键
全部 4 语言包总内存	~480 KB	已解析 JS 对象，常驻内存
Vue3 响应式更新延迟	< 16 ms	切换后下一帧完成界面重绘（60 fps）
主进程同步 IPC 开销	< 1 ms	`setLocale` 通过 IPC 同步到主进程

测试覆盖率

测试文件	测试数	覆盖内容
`tests/unit/i18n/i18n-core.test.js`	28	`t()` 路径查找、缺键回退、嵌套命名空间
`tests/unit/i18n/locale-switching.test.js`	16	`setLocale` / `getLocale`、持久化、IPC 同步
`tests/unit/i18n/supported-locales.test.js`	10	`getSupportedLocales()`、新增语言注册
`tests/unit/i18n/fallback-chain.test.js`	14	多级回退、`warnOnMissingKey` 日志验证
`tests/integration/i18n/vue3-composable.test.ts`	18	`useI18n()` 响应式绑定、组件热更新
总计	86	覆盖率 ≥ 95%

安全考虑

XSS 防护: 翻译文本在渲染时经过 Vue3 的自动转义，防止注入攻击
翻译文件来源: 仅加载本地 locales/ 目录下的翻译文件，不从网络动态加载，防止远程代码注入
用户输入隔离: 翻译系统仅处理预定义的翻译键，用户输入不会被当作翻译键解析
敏感信息排除: 翻译文件中不包含 API Key、密码等敏感信息，所有敏感数据通过配置系统管理
审计追踪: 语言切换操作记录在应用日志中，便于问题排查

i18n 国际化 ​

概述 ​

核心特性 ​

系统架构 ​

系统概述 ​

支持语言 ​

核心特性 ​

使用方式 ​

翻译函数 ​

命名空间约定 ​

API ​

关键文件 ​

使用示例 ​

主进程中使用翻译 ​

渲染进程（Vue3）中使用 ​

通过配置文件设置默认语言 ​

故障排查 ​

翻译键显示为原始 key 而非翻译文本 ​

切换语言后部分界面未更新 ​

新增语言后未显示在语言列表 ​

配置参考 ​

性能指标 ​

测试覆盖率 ​

安全考虑 ​

相关文档 ​

i18n 国际化

概述

核心特性

系统架构

系统概述

支持语言

核心特性

使用方式

翻译函数

命名空间约定

API

关键文件

使用示例

主进程中使用翻译

渲染进程（Vue3）中使用

通过配置文件设置默认语言

故障排查

翻译键显示为原始 key 而非翻译文本

切换语言后部分界面未更新

新增语言后未显示在语言列表

配置参考

性能指标

测试覆盖率

安全考虑

相关文档