知物由学 | 前端国际化工具链：用 i18n-cli 与 VS Code 打通 Vue 多语言配置

1. Vue 项目出海前，多语言配置为什么总在返工

前端国际化这件事，真正让人头疼的从来不是vue-i18n本身。装包、app.use(i18n)、写个messages对象，半小时就能跑起来。麻烦的是项目跑起来之后：文案散落在几十个.vue文件里，$t('xxx')的 key 命名全靠手敲，产品经理要一份待翻译清单你得手动整理，翻译回填之后又发现有几个 key 对不上，构建时页面直接白屏。

我见过一个典型的中型后台项目，国际化改造到一半，zh-CN.json里躺着 800 多条文案，其中 60 多条是重复定义的，20 多条是已经删掉引用但没清理的失效文案，还有十几处中文压根没提取出来，英文页面里直接显示中文。这些问题单靠人眼 review 根本查不完。

所以这篇要解决的不是「怎么用 vue-i18n」，而是怎么把国际化的提取、回填、校验做成一条可复制的工程化流水线。核心工具是i18n-cli命令行加 VS Code 插件，前者负责项目级的批量提取、检查、导入导出，后者负责开发时的实时预览和跳转。适合正在做 Vue 项目出海、或者已经被多语言维护成本拖住的团队。下面从目录结构开始，一步步把配置骨架、VS Code 设置和端到端验证命令都跑通。

2. 前置准备：目录约定与 TaoToken 接入

在动手写配置之前，先把两件事定下来：语言文件的目录结构，以及模型能力的接入方式。目录结构决定了工具能不能正确扫描和回填，接入方式决定了后面翻译参考和文案生成能不能自动化。

2.1 语言目录的约定

i18n-cli这类工具对目录有隐含要求，最稳妥的做法是按语言分目录、按模块分文件，而不是所有文案堆在一个zh-CN.json里。推荐结构如下：

src/ locales/ zh-CN/ common.json user.json order.json en-US/ common.json user.json order.json index.ts

index.ts负责聚合：

import { createI18n } from 'vue-i18n' import zhCommon from './zh-CN/common.json' import zhUser from './zh-CN/user.json' import enCommon from './en-US/common.json' import enUser from './en-US/user.json' const messages = { 'zh-CN': { common: zhCommon, user: zhUser }, 'en-US': { common: enCommon, user: enUser } } export const i18n = createI18n({ legacy: false, locale: 'zh-CN', fallbackLocale: 'en-US', messages })

按模块拆文件的好处是：提取时能按文件归属自动落到对应模块，回填时不会把整个语言包重写一遍，diff 也干净。

2.2 用 TaoToken 承接翻译与文案生成

提取出来的文案要变成多语言，中间那一步「翻译参考」如果全靠人工，文案一多就卡住提测。我的做法是把待翻译的 TSV 交给模型批量生成参考译文，再由产品经理微调。这里用 TaoToken 的 API 来承接，它兼容常见的对话接口格式，改一下baseURL就能接进现有脚本。

接入信息如下：

• 官网入口：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API 地址：https://taotoken.net/api
• 模型对话页：https://taotoken.net/api?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

注意：API Key 只放在本地.env.local或 CI 的密钥变量里，不要提交进仓库。.env.local记得加进.gitignore。

3. 可复制配置：i18n-cli 骨架与 VS Code settings

这一节是全文的核心，配置能直接抄。分三块：i18n-cli的配置文件、package.json脚本、VS Code 的settings.json。

3.1 i18n-cli 配置文件

在项目根目录建i18n.config.json：

{ "localesDir": "src/locales", "sourceLocale": "zh-CN", "targetLocales": ["en-US"], "fileExtensions": [".vue", ".ts", ".js"], "exclude": ["node_modules", "dist", "**/*.spec.ts"], "keyPrefix": "auto", "keyStrategy": "pinyin-md5", "moduleMapping": { "src/views/user/**": "user", "src/views/order/**": "order", "src/components/**": "common" }, "ignoreComment": "i18n-cli-disable-next-line", "exportFormat": "tsv", "exportDir": ".i18n-tmp" }

几个参数值得单独说：

keyStrategy选pinyin-md5是有原因的。纯拼音容易撞车，比如「提交」和「提交订单」都可能生成tijiao；纯哈希又完全不可读。拼音加 5 位 md5 后缀，既保留了语义线索，又保证了唯一性。

3.2 package.json 脚本

{ "scripts": { "i18n:extract": "i18n-cli extract --config i18n.config.json", "i18n:check": "i18n-cli check --config i18n.config.json", "i18n:export": "i18n-cli export --config i18n.config.json --locale en-US", "i18n:import": "i18n-cli import --config i18n.config.json --locale en-US --file .i18n-tmp/en-US.tsv", "i18n:build-check": "npm run i18n:check && vue-tsc --noEmit" } }

i18n:build-check是关键，把文案检查和类型检查串在一起，CI 里跑这一条就能拦住大部分国际化问题。

3.3 VS Code settings.json 片段

VS Code 插件负责开发时的体验，把下面这段加进项目级.vscode/settings.json：

{ "i18n-ally.localesPaths": ["src/locales"], "i18n-ally.sourceLanguage": "zh-CN", "i18n-ally.displayLanguage": "zh-CN", "i18n-ally.keystyle": "nested", "i18n-ally.enabledParsers": ["json", "ts"], "i18n-ally.pathMatcher": "{locale}/{namespaces}.json", "i18n-ally.namespace": true, "i18n-ally.extract.autoDetect": true, "i18n-ally.editor.preferEditor": true, "i18n-ally.annotationInPlace": true, "i18n-ally.annotationMaxLength": 40 }

annotationInPlace打开后，代码里的$t('user.name')会直接在行内显示对应中文，可读性问题当场解决。pathMatcher要和前面的目录结构对齐，否则插件找不到语言文件。

3.4 忽略提取的写法

有些中文不该被提取，比如日志、正则、测试数据。用注释标记：

// i18n-cli-disable-next-line const logTag = '用户模块' /* i18n-cli-disable */ const mockData = { name: '张三', city: '北京' } /* i18n-cli-enable */ const title = $t('order.detail.title')

这套标记借鉴了 ESLint 的忽略思路，团队上手成本几乎为零。

4. 端到端验证：从提取到构建校验

配置写完，跑一遍完整流程验证。假设项目里有个UserProfile.vue，里面有几处硬编码中文。

4.1 提取文案

npm run i18n:extract

执行后终端会输出类似：

[extract] scanned 42 files [extract] found 17 zh-CN strings [extract] written to src/locales/zh-CN/user.json [extract] rewritten 9 vue files

打开src/locales/zh-CN/user.json，能看到新增的 key：

{ "user": { "profile": { "title": "个人资料", "submit": "提交", "cancel": "取消" } } }

对应的.vue文件里，原来的个人资料已经被替换成$t('user.profile.title')。

4.2 导出待翻译清单

npm run i18n:export

生成的.i18n-tmp/en-US.tsv长这样：

key zh-CN en-US user.profile.title 个人资料 user.profile.submit 提交 user.profile.cancel 取消

en-US列是空的，等着回填。这一步之后，可以把 TSV 交给模型生成参考译文。用 TaoToken 的对话接口跑一个批量脚本：

import fs from 'node:fs' const API_URL = 'https://taotoken.net/api/v1/chat/completions' const API_KEY = process.env.TAOTOKEN_API_KEY async function translateBatch(items: { key: string; text: string }[]) { const prompt = items .map((i) => `${i.key}\t${i.text}`) .join('\n') const res = await fetch(API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${API_KEY}` }, body: JSON.stringify({ model: 'claude-sonnet-4-5', messages: [ { role: 'system', content: '你是前端国际化翻译助手，输出格式为 key\\t译文，每行一条，不要额外解释。' }, { role: 'user', content: prompt } ] }) }) const data = await res.json() return data.choices[0].message.content }

拿到参考译文后填回 TSV，再执行导入：

npm run i18n:import

4.3 构建校验

npm run i18n:build-check

这一步会做四类检查：未提取的中文、重复文案、失效文案、错误引用。如果全部通过，终端输出：

[check] no missing zh-CN strings [check] no duplicate values [check] no unused keys [check] no invalid references vue-tsc: 0 errors

到这里，一条从提取到校验的流水线就跑通了。CI 里把i18n:build-check挂上，每次 PR 自动拦问题。

5. 本篇常见错排查

配置跑不通，八成是下面几个原因。

插件找不到语言文件。检查i18n-ally.localesPaths是否指向src/locales，以及pathMatcher是否和实际目录层级一致。如果语言文件是src/locales/zh-CN/user.json，pathMatcher就该是{locale}/{namespaces}.json，多一层少一层都会失效。

提取后 key 重复。通常是keyStrategy配成了纯拼音，或者moduleMapping没配导致所有文案都落到common。改成pinyin-md5并补全模块映射即可。

导入后页面还是中文。大概率是sourceLocale和实际语言包对不上，或者index.ts里没有把新模块注册进messages。检查聚合文件是否引入了新增的 JSON。

构建时报 key 不存在。这是「错误引用」的典型表现，说明代码里用了某个 key 但语言包里没有。跑npm run i18n:check会列出具体文件和行号，按提示补 key 或改引用。

忽略注释不生效。确认注释写法和ignoreComment配置完全一致，包括大小写和连字符。i18n-cli-disable-next-line只作用于下一行，块级忽略要用disable/enable成对出现。

翻译回填后格式错乱。TSV 对制表符敏感，用表格工具编辑时别把制表符替换成空格。建议直接用脚本读写，避免手动编辑引入不可见字符。

6. 把工具链接进你的开发流

工具链跑通只是第一步，真正省时间的是把它嵌进日常流程。几个实践建议：

提交代码前用lint-staged挂上增量提取，只处理改动文件，避免全量扫描拖慢提交。CI 里把i18n:build-check作为必过项，文案问题在合并前就暴露。翻译参考用模型批量生成，产品经理只做微调，提测节奏能提前不少。

如果你还在选模型和接入方式，可以先到模型对话页试一下翻译效果，确认输出格式稳定后再写进脚本。API Key 在控制台创建，接入细节看文档，长期做编码和 Agent 场景的可以了解下 Coding Plan 的额度方案。把这几步串起来，Vue 项目的多语言维护就不再是每次迭代都要返工的负担了。