知物由学 | 前端国际化工具链：用 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.tsindex.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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api模型对话页https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-chatAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc注意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 }几个参数值得单独说参数作用建议值keyStrategykey 命名策略pinyin-md5拼音加短哈希可读且不冲突moduleMapping路径到模块的映射按业务目录配避免全塞 commonignoreComment忽略提取的注释标记与 ESLint 风格保持一致exportFormat导出格式tsv方便表格工具打开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:import4.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.jsonpathMatcher就该是{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 项目的多语言维护就不再是每次迭代都要返工的负担了。