vue-cli UI 国际化实战指南:翻译标准 UI 与 Vue CLI 插件的本地化机制
vue-cli UI 国际化实战指南:翻译标准 UI 与 Vue CLI 插件的本地化机制
本文围绕 vue-cli 官方文档《UI 本地化》展开,系统讲解如何为 Vue CLI UI 贡献新的语言翻译包,以及如何为自己的 Vue CLI 插件接入 vue-i18n 兼容的本地化文件。结合开源仓库 packages/@vue/cli-ui 的服务端连接器与前端 i18n 模块源码,你将理解从语言代码检测、unpkg 远程加载、插件 locales 目录自动扫描到 GraphQL 订阅推送的完整国际化链路,并掌握 ClientAddonApi.addLocalization 等 API 的正确用法。
一、vue-cli UI 国际化体系总览
Vue CLI UI(由 vue ui 命令启动)基于 Vue 2 + vue-i18n 构建,其国际化体系分为三层:
- 服务端(Apollo Server):
@vue/cli-ui的 apollo-server 侧维护一份内存中的 locales 集合,负责加载内置语言文件并扫描项目内各插件的locales目录; - 传输层(GraphQL 订阅):服务端通过 PubSub 的
localeAdded事件把新增/变更的语言包推送给浏览器客户端; - 客户端(VueI18n 实例):前端维护一个全局
i18n实例(默认语言en,回退语言en),通过mergeLocale函数把各来源的字符串 deepmerge 合并进对应语言的消息表。
三层之间的关键实现分别位于 i18n.js、locales.js 和 LocaleLoader.vue。理解了这条链路,下面文档中的两类翻译方案就都有了底层依据。
语言检测与自动加载机制
客户端启动时会执行语言自动检测。i18n.js 中的 detectLanguage() 依次读取 window.navigator.languages、window.navigator.language、window.navigator.userLanguage,并生成形如 ['fr-FR', 'fr_fr', 'fr'] 的候选语言码列表(- 会被替换为 _)。
随后 autoDetect()(i18n.js)按候选顺序逐个尝试 tryAutoLang(),其核心是 autoInstallLocale():
async function autoInstallLocale (lang) {
try {
const response = await fetch(`https://unpkg.com/vue-cli-locales/locales/${lang}.json`)
if (response.ok) {
const data = await response.json()
mergeLocale(lang, data)
return true
}
} catch (e) {}
return false
}
从源码可以看到:UI 会直接通过 unpkg 这个 CDN 按语言码拉取语言文件,拉取成功后调用 mergeLocale 合并进 i18n 实例并把 i18n.locale 切换为该语言。这正是后文“为翻译包设置 unpkg 字段”能起作用的原因——npm 包的 unpkg 字段决定了该包在 unpkg CDN 上的入口路径。若所有候选语言都拉取失败,控制台会输出 No locale data was found for your locale ... 并回退到英文。此外该函数还会根据当前语言码重新创建 VueTimeago 时间相对化组件(zh 会映射为 zh-CN,因为 date-fns 只提供 zh-CN)。
mergeLocale 的定义(i18n.js)非常简洁:
export function mergeLocale (lang, messages) {
const newData = deepmerge(i18n.getLocaleMessage(lang), messages)
i18n.setLocaleMessage(lang, newData)
}
它用 deepmerge 把新消息与已有消息做深度合并而非覆盖,这也是为什么多个插件可以向同一个语言包追加互不冲突的命名空间字符串。
二、翻译标准 UI:发布一个 npm 语言包
官方文档给出的贡献路径是“每个语言一个独立 npm 包”。完整步骤如下:
第 1 步:确定语言代码
运行 navigator.languages 或 navigator.language 获取目标地区的语言代码,例如法语为 'fr'。
第 2 步:确认包是否已存在
在 npm 上搜索名为 vue-cli-locale-<language code> 的包(例如 vue-cli-locale-fr)。如果该包已经存在,不要重复造轮子,直接通过 PR 为已有包贡献翻译;如果不存在,则新建一个同名包。
第 3 步:组织 locales 文件夹
把地区 JSON 文件放入包内的 locales 文件夹,文件以语言代码命名,例如:
vue-cli-locale-fr/locales/fr.json
第 4 步:设置 unpkg 字段
在包的 package.json 中把 unpkg 字段指向语言文件:
{
"name": "vue-cli-locale-fr",
"version": "1.0.0",
"unpkg": "./locales/fr.json"
}
该字段让 unpkg CDN 能直接解析到语言 JSON 文件,从而被 UI 的远程加载机制(见上节 autoInstallLocale)获取。
第 5 步:发布到 npm
将包发布后即可被社区使用。
参考英文基准语言文件
翻译时的“源语言”基准是仓库中的英文地区文件,位于 locales/en.json。该文件共 800 余行,采用嵌套命名空间组织键值,例如通用按钮文案位于 org.vue.common(close、cancel、back 等),各视图与组件文案位于 org.vue.views.*、org.vue.components.* 等路径下。翻译新语言时应保持与 en.json 相同的键结构,只替换叶子字符串值。
另外,从英文文档的说明来看,英文源语言文件会通过 Transifex 平台协作翻译与同步:对已有语言可以注册为译者参与翻译,对新语言可以注册后申请新增,之后源语言文件中新增或变更的 key 都可以被持续跟进翻译。
三、服务端如何加载 locales:源码级机制
标准 UI 和插件翻译最终都会汇入服务端的 locales 连接器。connectors/locales.js 的核心逻辑:
1. 启动时加载内置语言。 模块加载时执行 reset(getContext()),其中 reset() 会清空内存中的 locales 数组,然后以 @vue/cli-ui 包根目录为 root 调用 loadFolder,把内置的 locales 目录(含 en.json)读入:
function reset (context) {
locales = []
// Load builtin locales
const folder = path.resolve(__dirname, '../../')
loadFolder(folder, context)
}
2. 扫描 locales/*.json。 _loadFolder 用 globby 匹配 ./locales/*.json,以文件名(去扩展名)作为语言码,fs.readJsonSync 读出字符串对象后调用 add({ lang, strings }, context):
function _loadFolder (root, context) {
const paths = globby.sync(['./locales/*.json'], { cwd: root, absolute: true })
paths.forEach(file => {
const basename = path.basename(file)
const lang = basename.substr(0, basename.indexOf('.'))
const strings = fs.readJsonSync(file)
add({ lang, strings }, context)
})
}
3. 开发模式热更新。 loadFolder() 中有一个值得注意的细节:当环境变量 VUE_APP_CLI_UI_DEV 开启时,会用 chokidar 监听 locales 文件夹,文件变动即重新加载并输出 Locales reloaded 日志。这对 UI 自身的本地化开发体验很友好;非开发模式下则直接同步加载一次。
4. 合并与推送。 add() 若发现相同语言已存在,则用 deepmerge(existing.strings, locale.strings) 合并字符串后,通过 context.pubsub.publish(channels.LOCALE_ADDED, { localeAdded: locale }) 发布事件(locales.js)。该事件经 type-defs.js 中声明的 localeAdded: Locale 订阅字段和 resolvers.js 中的 pubsub.asyncIterator(channels.LOCALE_ADDED) 暴露为 GraphQL 订阅。
5. 客户端接收并合并。 前端的 LocaleLoader.vue 是一个不渲染任何内容的“隐形”组件,它做两件事:
apollo: {
locales: { query: LOCALES, fetchPolicy: 'no-cache', ... }, // 打开项目时全量拉取
$subscribe: {
localeAdded: { // 增量订阅
query: LOCALE_ADDED,
result ({ data }) { this.loadLocale(data.localeAdded) }
}
}
},
methods: {
loadLocale (locale) {
mergeLocale(locale.lang, locale.strings)
}
}
即:项目打开时通过 locales 查询全量加载一次,之后任何新的语言包(包括插件 locales)都通过 localeAdded 订阅增量合并进前端 vue-i18n 实例。
四、翻译你的插件:locales 文件夹自动加载
这是官方文档“翻译插件”一节的完整机制。
4.1 目录约定
在插件根目录放置一个 locales 文件夹,其中放入与 vue-i18n 兼容的地区文件,例如:
vue-cli-plugin/locales/en.json
vue-cli-plugin/locales/fr.json
这些文件会在项目打开时被自动加载到 UI 客户端,你无需编写任何注册代码。加载的触发点在 connectors/plugins.js:每次执行插件 API(即加载插件的 ui 文件)之后,都会尝试定位插件目录并调用 locales.loadFolder:
// Locales
try {
const folder = fs.existsSync(id) ? id : dependencies.getPath({ id, file: pluginApi.cwd })
locales.loadFolder(folder, context)
} catch (e) {}
这里的 folder 可能是项目内的相对目录,也可能是通过 dependencies.getPath 从 node_modules 解析出的插件真实安装路径——因此无论是 npm 安装的插件还是本地浏览的插件,其 locales 都会被扫描。由于 _loadFolder 以文件名为语言码、以 deepmerge 合并,多个插件的 en.json/fr.json 会被安全地叠加到同一语言包中而不会互相覆盖。
4.2 在 UI API 与组件中使用翻译键
locales 文件进入客户端后,UI API 描述中使用的字符串同样会经过 vue-i18n 处理。也就是说,describeConfig、describeTask 等 UI API 的字段值可以直接填 vue-i18n 路径(而不是纯文本),官方文档给出的示例:
api.describeConfig({
// vue-i18n 路径
description: 'com.my-name.my-plugin.config.foo'
})
在自定义 Vue 组件中则直接使用 vue-i18n 的 $t 辅助函数:
<VueButton>{{ $t('com.my-name.my-plugin.actions.bar') }}</VueButton>
仓库中标准 UI 自身的用法与之一致,例如 About.vue 中的 {{ $t('org.vue.views.about.title') }}、ConnectionStatus.vue 中的 $t('org.vue.components.connection-status.disconnected')——键的结构都能在 locales/en.json 中找到对应条目,这为插件作者提供了可直接模仿的键值组织范例。
危险(官方警告):请务必为翻译键的 id 设置正确的命名空间,因为它需要在所有插件之间保持唯一。推荐使用反向域名记号(reverse domain name notation),例如上文示例中的
com.my-name.my-plugin.*。若两个插件使用相同的键路径,后加载的插件字符串会覆盖先加载的(见add()中的deepmerge行为与mergeLocale的合并顺序),造成文案错乱。
4.3 locales JSON 的书写要点
- 文件必须是与 vue-i18n 消息格式兼容的纯 JSON 对象,键可任意嵌套,叶子值为待翻译字符串;
- 文件名必须是语言码本身(如
en.json、fr.json),_loadFolder以basename截取点号前的部分作为语言码,en-US.json这类写法产生的语言码是en-US,与浏览器语言码检测(fr、zh等短码优先)需自行保证匹配; - 若插件同时提供
en.json,它会在deepmerge中与服务端内置英文合并——插件键与内置键路径冲突时以合并结果为准,因此再次强调命名空间隔离。
五、进阶:用 ClientAddonApi 在客户端 Addon 中加载语言包
除了依赖服务端自动扫描 locales 目录,文档还提供了一个客户端侧的手动方案:如果你编写的是 client addon(挂载到 window.ClientAddonApi 的客户端模块),可以用 ClientAddonApi.addLocalization 自行加载语言文件。官方文档给出的示例:
// 加载本地文件 (使用 vue-i18n)
const locales = require.context('./locales', true, /[a-z0-9]+\.json$/i)
locales.keys().forEach(key => {
const locale = key.match(/([a-z0-9]+)\./i)[1]
ClientAddonApi.addLocalization(locale, locales(key))
})
原理逐行拆解:
require.context('./locales', true, /[a-z0-9]+\.json$/i)是 webpack 提供的上下文模块 API,会把./locales下所有匹配xx.json的文件收集为可按 key 调用的模块(client addon 由 UI 的 webpack 构建产物运行,因此可用);key形如./en.json,用正则([a-z0-9]+)\.提取出语言码en;ClientAddonApi.addLocalization(locale, locales(key))把该语言的字符串对象注册进全局 vue-i18n。
addLocalization 的实现就在 ClientAddonApi.js:
/**
* Merge new strings into the specified lang translations (using vue-i18n).
*
* @param {string} lang Locale to merge to (ex: 'en', 'fr'...)
* @param {object} strings A vue-i18n strings object containing the translations
*/
addLocalization (lang, strings) {
mergeLocale(lang, strings)
console.log(`[ClientAddonApi] Registered new strings for locale ${lang}`)
}
它直接复用 i18n.js 导出的 mergeLocale,与第 1 节所述的 deepmerge + setLocaleMessage 是同一条路径,因此与插件 locales、标准 UI 语言包天然兼容。仓库中 cli-ui-addon-webpack 这个官方 client addon 的入口正是文档示例的原型(其 main.js 中同样的 require.context + ClientAddonApi.addLocalization 三行式写法可直接参照)。
两种插件本地化方式对比
| 方式 | 触发方 | 适用场景 | 特点 |
|---|---|---|---|
插件根目录 locales/ 文件夹 |
服务端 plugins.js 在加载插件 API 后自动 loadFolder |
普通 Vue CLI 插件(带 ui 入口) |
零代码,项目打开即加载;经 GraphQL localeAdded 订阅推送 |
ClientAddonApi.addLocalization |
客户端 addon 自行执行 | client addon(webpack 构建的客户端模块) | 手动、即时生效于当前浏览器会话,配合 require.context 批量加载 |
六、小结与检查清单
回到文档主题,为 Vue CLI UI 做本地化可以归纳为两条路线:
- 标准 UI 翻译:以
vue-cli-locale-<lang>npm 包形式提供,locales/<lang>.json+unpkg字段指向语言文件,发布 npm 后供 UI 通过 unpkg 远程加载;语言码以navigator.languages为准,基准键结构对照 locales/en.json。 - 插件翻译:在插件根目录
locales/放置 vue-i18n 兼容文件,服务端自动扫描、经deepmerge合并与localeAdded订阅推送到前端;UI API 字段与组件内$t统一使用带命名空间(推荐反向域名记号)的键路径;client addon 场景可用ClientAddonApi.addLocalization手动注册。
上线前可对照以下清单自检:
- 语言文件命名是否为纯语言码(
fr.json),键结构是否与en.json或插件自身命名空间一致; - 插件翻译键是否加上了全局唯一的命名空间,避免跨插件冲突;
- 描述类字段(
describeConfig/describeTask等)中填写的是 vue-i18n 路径而非硬编码文本; - 若修改了标准 UI 翻译包,
package.json的unpkg字段是否指向./locales/<lang>.json; - 服务端日志是否出现
[UI] Locale xx updated with new strings(见 LocaleLoader.vue 中的loadLocale日志),以确认语言包确实被客户端合并成功。
以上机制均以当前仓库 @vue/cli-ui 源码为准:客户端 i18n.js、服务端 connectors/locales.js、connectors/plugins.js 与客户端 ClientAddonApi.js 四个文件构成完整的可追溯证据链。