I18n 消息系统

i18n 消息系统通过简单的 $i18n:key 格式实现主进程与渲染进程之间的无缝国际化。

概述

后端发送带有 i18n 键的消息（如 $i18n:devServer.disconnected），前端根据用户的语言偏好将其解析为本地化字符串。

介绍

适合用于主进程通知、插件报错、流程提示等场景，避免直接写死字符串。

后端使用（主进程）

import { i18nMsg, DevServerKeys, FlowTransferKeys } from '@talex-touch/utils/i18n'

// 基本用法 - 发送 i18n 键
win.webContents.send('notification', {
  title: i18nMsg(DevServerKeys.DISCONNECTED),
  message: i18nMsg(DevServerKeys.CONNECTION_LOST)
})

// 带参数（用于插值）
import { i18nMsgWithParams } from '@talex-touch/utils/i18n'

win.webContents.send('error', {
  message: i18nMsgWithParams('plugin.loadFailed', { name: 'my-plugin' })
})

前端使用（渲染进程）

import { resolveI18nMessage, i18nResolver, useI18nResolver } from '@talex-touch/utils/i18n'

// 设置语言（通常在应用初始化时）
i18nResolver.setLocale('zh')

// 解析消息
const text = resolveI18nMessage('$i18n:devServer.disconnected')
// => '开发服务器已断开'

// 非 i18n 字符串直接返回
const plain = resolveI18nMessage('Hello World')
// => 'Hello World'

// Vue composable
const { resolve, setLocale } = useI18nResolver()
const message = resolve(receivedMessage)

消息键

DevServerKeys（开发服务器）

键	英文	中文
`devServer.disconnected`	Dev Server Disconnected	开发服务器已断开
`devServer.reconnected`	Dev Server Reconnected	开发服务器已重连
`devServer.connectionLost`	Dev Server connection lost	开发服务器连接已断开

FlowTransferKeys（Flow Transfer）

键	英文	中文
`flowTransfer.shareComplete`	Share Complete	分享完成
`flowTransfer.shareFailed`	Share Failed	分享失败
`flowTransfer.copiedToClipboard`	Copied to Clipboard	已复制到剪贴板

PluginKeys（插件）

键	英文	中文
`plugin.loadFailed`	Plugin Load Failed	插件加载失败
`plugin.manifestInvalid`	Invalid Manifest	清单文件无效

SystemKeys（系统）

键	英文	中文
`system.networkError`	Network Error	网络错误
`system.timeout`	Request Timeout	请求超时

添加新消息

1. 添加消息键

// packages/utils/i18n/message-keys.ts
export const MyModuleKeys = {
  SUCCESS: 'myModule.success',
  ERROR: 'myModule.error',
} as const

2. 添加翻译

// packages/utils/i18n/locales/en.json
{
  "myModule": {
    "success": "Operation Successful",
    "error": "Operation Failed"
  }
}

// packages/utils/i18n/locales/zh.json
{
  "myModule": {
    "success": "操作成功",
    "error": "操作失败"
  }
}

插件自定义消息

插件可以添加自己的消息：

import { i18nResolver } from '@talex-touch/utils/i18n'

// 添加自定义消息
i18nResolver.addMessages('en', {
  myPlugin: {
    hello: 'Hello from plugin'
  }
})

i18nResolver.addMessages('zh', {
  myPlugin: {
    hello: '插件问好'
  }
})

最佳实践

统一在 message-keys.ts 定义键名，避免散落。
使用 i18nMsg 或 i18nMsgWithParams 发送键值。
文案改动只更新 locale 文件，避免修改业务逻辑。

技术原理

消息以 $i18n: 前缀标识，解析器根据当前 locale 查表。
Resolver 支持运行时注入消息，便于插件扩展。

文件结构

packages/utils/i18n/
├── index.ts           # 统一导出
├── message-keys.ts    # 键定义 + 工具函数
├── resolver.ts        # 前端解析器
└── locales/
    ├── en.json       # 英文翻译
    └── zh.json       # 中文翻译