meta-i18n

VSCode 国际化处理插件：提取 js/ts/jsx/tsx/vue 文件中的中文并替换为 i18n 调用，生成多语言语料文件；覆盖「扫描 → 拆分 → 校对 → 质量检查 → 还原」的国际化全流程，并提供编辑器内嵌翻译预览。

功能特性

中文扫描替换：基于 AST（Babel + Vue SFC 编译器）精准识别源码中的中文，替换为 t() / $t() 等调用，自动生成临时语料文件
多语言文件管理：语言文件拆分、排序，多语言一键切换
语料校对闭环：导出语料为 CSV 表格（每种语言一列、全行去重，并为每种语言附带一列空校对列），导入校对后的表格按「校对-<语言>」列同时回写多种语言（支持 CSV / Excel）
质量检查：中文漏检检查（AST + 正则双通道对比，含 enum 风险提示）、缺失 key 检查（源码引用 vs 各语言定义）、删除无用 key、合并重复语料
反向还原：将源码中的 i18n 调用逆向还原为中文原文（扫描的逆操作）
溢出处理：为已转换的 Vue 元素自动补加溢出样式（内联 style 或 class）与 :title 悬浮提示，缓解翻译后文案变长溢出容器的问题
注释忽略标记：类 @ts-ignore 的 i18n-disable 系列标记，声明不被扫描的代码区域
内嵌翻译预览：在编辑器中为 i18n 调用行内展示对应语言的翻译文案，随切换语言实时更新

安装

插件市场搜索 meta-i18n 安装；或
使用 .vsix 离线安装：VSCode 中执行 Extensions: Install from VSIX... 选择 meta-i18n-x.x.x.vsix

要求 VSCode ^1.99.0。

快速开始

所有命令都收在编辑器右键菜单的「国际化（meta-i18n）」子菜单下，仅对 js/ts/jsx/tsx/vue/json 文件生效。推荐按下面的顺序完整走一遍：

配置：右键任意源码文件 →「设置」，生成并编辑工作区根目录下的 meta-i18n.config.js（字段含义详见配置）
扫描：单文件用「扫描中文」，整个目录用「批量扫描中文」；源码里的中文会被替换成 t('key') 调用，同时在 tempPaths 目录下生成临时语料文件
拆分：确认扫描结果无误后，执行「拆分语言文件」，把临时语料与已有正式语料合并后的结果按语言写入 langPaths 目录下的正式语言文件（每种语言一个 <语言>.json）
校对：「导出语料表格」导出 CSV 交给翻译/校对，回填「校对-<语言>」列后用「导入校对语料表格」写回对应语言
质量检查：按需执行「检查中文漏检」「检查缺失key」「删除无用key」「合并重复语料」
预览与切换：「切换语言」选择要预览的语言，编辑器会在 i18n 调用后面内嵌展示对应语言的译文；语料文件被外部改动后可用「刷新数据」手动同步
收尾/回退：「处理溢出样式」为翻译后可能变长的文案补加省略号样式；如需回退，「还原国际化至中文」把源码逆向还原为中文原文

会改写源码或语料的命令（批量扫描、拆分、还原、溢出处理、合并重复语料、删除无用 key、导入校对表格）都会先在「输出」面板打印明细报告，涉及不可逆改写的还会弹窗二次确认后才真正落盘。执行前建议先提交代码，出问题时可以用 git diff / git checkout 精确回滚。

命令详解

扫描与提取

扫描中文

入口：右键当前源码文件 →「扫描中文」
行为：解析当前文件（.vue 会分别处理 <template> 与 <script>），把中文替换为 t('key') 调用（Vue 模板中为插值 / 指令绑定形式），并按 importPath 配置自动注入 i18n 导入语句——仅在确实发生了替换时才注入，重复扫描不会重复注入
产物：源码被改写并经 Prettier 格式化；在 tempPaths 目录下生成一个新的临时语料 JSON 文件，默认语言（defaultLang）写入中文原文，tempLangs 中的其余语言写入空字符串占位
key 命名规则：形如 <目录名>.<文件名>.<时间戳><随机位>-<递增序号>，同一段中文在同一个文件内复用同一个 key
注意：enum 成员中的中文无法被替换为函数调用（会产出非法代码，且枚举值不会跟随语言切换），插件不会静默跳过，而是收集为「enum 中文风险」警告弹窗提示，需要人工重构

批量扫描中文

入口：右键任意源码文件 →「批量扫描中文」，在弹出的目录选择框中选择要扫描的文件夹
行为：对文件夹内全部 .vue/.js/.ts/.jsx/.tsx 文件逐个执行与「扫描中文」相同的逻辑，命中 ignoreFiles / ignoreFolders 的文件会被跳过；单个文件失败不会中断整体扫描
产物：与单文件扫描一致（源码改写 + 临时语料文件）；结束后在「输出」面板生成「meta-i18n 批量扫描」报告，逐文件汇总转换成功 / 无需处理 / 警告 / 失败明细，并弹窗提示总数；仅当存在失败或警告时才会自动展开输出面板
注意：如果失败发生在源文件写入之后，源文件可能已经被部分改写，建议用 git diff 确认后再决定是否回滚该文件

语言文件管理

拆分语言文件

入口：右键任意源码文件 →「拆分语言文件」
行为：把当前加载的多语言语料汇总（先合并 tempPaths 下的全部临时语料，再合并 langPaths 下已有的正式语料，同名 key 以正式语料为准）按语言拆分，覆盖写入 langPaths 目录下每种语言对应的 <语言>.json 文件
匹配规则：只有语言标识能匹配 tempLangs 的语言才会被写入（匹配规则详见配置），避免把非语言标识的内容误写为语言文件
排序：此前不存在的语言文件写入时会自动按键名排序；已存在的文件保留合并后的键顺序，需要时可用「排序」命令手动整理
注意：langPaths 未配置时命令会静默结束，不产生任何文件

排序

入口：右键某个 .json 文件 →「排序」
行为：对该 JSON 文件按键名重新排序并写回
限制：仅允许排序「正式语言文件」——即位于 langPaths 目录下、且文件名能匹配 tempLangs 的 .json 文件；不满足条件会提示错误并中止

切换语言

入口：右键任意源码文件 →「切换语言」，从 tempLangs 列表中选择目标语言
行为：切换编辑器内嵌翻译预览所展示的语言，不影响源码本身，也不改动语料文件

刷新数据

入口：右键任意源码文件 →「刷新数据」
行为：重新读取配置文件与 tempPaths / langPaths 下的全部语料文件，刷新内存缓存，并重新渲染当前编辑器的内嵌翻译预览
适用场景：在 VSCode 外部（如命令行、其他编辑器）改动了语料文件后，用它让插件立即感知最新内容

提示：所有命令在执行前都会重新读取一次 meta-i18n.config.js（不使用内存中的旧配置缓存），因此修改配置文件后无需重启窗口即可对下一次命令生效；保存配置文件本身也会自动触发一次完整重载。

语料校对

导出语料表格

入口：右键任意源码文件 →「导出语料表格」，选择导出「正式语料」（langPaths）还是「临时语料」（tempPaths）
行为：把语料按「扁平化 key → 文案」展开为二维表，每种语言一列（默认语言排首列，其余按字母序），所有语言列值完全相同的行整行去重；语言列之后会为每种语言追加一列空的「校对-<语言>」列，供导入时填写校对值
产物：弹出保存对话框，默认文件名 i18n-corpus-formal.csv（正式语料）或 i18n-corpus-temp.csv（临时语料）；写入时带 BOM 头，可直接用 Excel 打开而不乱码

导入校对语料表格

入口：右键任意源码文件 →「导入校对语料表格」，先选择导入目标是「正式语料」还是「临时语料」，再选择校对后的表格文件（支持 .csv / .xlsx / .xls / .xlsm / .xlsb / .ods）
表格格式要求：
- 表头需包含导出时的语言列，用于按「所有语言列值完全一致」反向匹配语料 key
- 表头中以「校对-」开头的列被视为校对列，如「校对-en」「校对-zh」，支持一次校对多种语言；校对列的语言必须同时存在于语言列中，否则该列会被忽略并提示
- 数据行中，某校对列为空、或与该语言列的原值完全一致，则该语言该行不做修改；只有填写了不同内容的单元格才会触发写回
行为：内容相同的多个 key 会全部命中并一起更新；写回时会对校对值做 vue-i18n 消息格式转义（如 @ → {'@'}），且仅当语料文件中该 key 的当前值与表格里的原值一致时才覆盖，避免误改已经被其他人改过的内容
产物：完成后弹窗汇总「匹配 X 行，更新 Y 处（分语言统计），跳过 Z 行，未匹配 W 行」，并刷新语料缓存与编辑器内嵌预览

质量检查

检查中文漏检

入口：右键任意源码文件 →「检查中文漏检」，选择要检查的文件夹
行为：对文件夹内源码文件做「只检测不落盘」的双通道扫描——AST 通道与「扫描中文」共用同一套解析逻辑，正则通道则先做字符级去注释（跳过字符串字面量，识别 //、/* */、，并排除 URL 协议中的 //）再全文匹配中文，两份结果交叉对比
产物：在「输出」面板生成「meta-i18n 中文漏检」报告，分为三类：
- AST 检出：确定需要处理的中文，可直接用「批量扫描中文」处理
- enum 风险：enum 成员中的中文，无法自动国际化，需人工重构
- 正则补充：AST 未识别但正则匹配到的中文（可能是 AST 遍历盲区，也可能是 console.log 等本就不需要处理的文案），需人工甄别
说明：命中 i18n-disable 系列注释忽略标记的区域，两条通道都会跳过，不会被误报为漏检

检查缺失key

入口：右键任意源码文件 →「检查缺失key」
行为：先刷新语料缓存，再全量扫描源码收集所有被引用的 key（按 quoteKeys 配置的函数名匹配），逐语言比对语料文件中已定义的 key
产物：在「输出」面板生成「meta-i18n 缺失 key」报告，区分：
- 完全缺失：所有语言均未定义，运行时必然显示 key 原文
- 部分缺失：仅部分语言未定义，切换到对应语言时才会显示 key 原文
- 同时给出各语言的完整性统计（已定义数 / 缺失数）
注意：动态拼接的 key（如 t('a.' + x)）无法静态分析，可能被漏判或误判，需结合业务二次确认

删除无用key

入口：右键任意源码文件 →「删除无用key」
行为：全量扫描源码收集已使用的 key，逐个比对 langPaths 下的正式语言文件，找出未被引用的 key；若未扫描到任何使用记录会直接中止，避免误删全部语料
确认：弹窗展示待删除的 key 总数与涉及文件数，需点击「确认删除」才会真正执行（不可恢复）
产物：删除无用 key 并清理因此变空的父级对象，写回语言文件，同时刷新缓存与编辑器预览；删除明细会输出到开发者控制台，便于事后审计

合并重复语料

入口：右键任意源码文件 →「合并重复语料」
行为：按「所有语言文案完全一致」对正式语料分组，为每组生成一个由内容哈希派生的公共 key（形如 common.<哈希>，重复执行结果一致），扫描源码中所有旧 key 的引用位置并改写为公共 key，随后删除旧 key
确认：先在「输出」面板输出完整合并方案（含每个旧 key 的引用位置明细），再弹窗二次确认「确认合并」后才执行；common.* 下的 key 不会参与后续合并
顺序保障：先改写源码、后删除语料 key，即使中途中断，旧 key 仍保留在语料中，可依据报告手工回滚

还原与溢出处理

还原国际化至中文

入口：右键任意源码文件 →「还原国际化至中文」，通过 QuickPick 选择范围：「还原当前文件」或「批量还原（选择文件夹）」
行为：以正式语料（langPaths）中 defaultLang 语言的文案为依据，把源码中的 t('key') / t('key', [args]) 调用逆向还原为中文原文，脚本、JSX、Vue 模板三侧口径一致，并清理不再被使用的 i18n import
产物：先在「输出」面板输出还原报告（逐文件列出还原 / 跳过明细），再弹窗二次确认「确认还原」后才写回源码并 Prettier 格式化
说明：
- 只改写源码，不改动语料文件；还原后这些 key 变为无用，可再用「删除无用key」清理
- 动态拼接的 key（如 t('a.' + x)）无法静态还原，会列入跳过并在报告中说明原因

处理溢出样式

入口：右键任意源码文件 →「处理溢出样式」，选择范围：「处理当前文件」或「批量处理（选择文件夹）」
前置条件：需要配置文件中 overflow.enabled 为 true；若未启用，会弹出模态窗口提供三选一：
- 本次使用默认样式：仅本次命令生效（使用内置默认样式），不写回配置文件
- 打开配置文件：直接跳转到「设置」命令，方便永久开启
- 关闭弹窗：取消本次操作
行为：面向已经转换完成的存量 Vue 文件，为 <template> 中包含 i18n 调用的元素补加溢出样式（overflow.mode 决定写内联 style 还是追加 class）与 :title 悬浮提示（由 overflow.addTitle 控制）
幂等性：已经存在 title / 目标类名 / 目标样式声明的元素会被跳过，可安全多次执行
产物：先在「输出」面板输出处理报告（逐文件列出处理数量与样式来源），再弹窗二次确认「确认处理」后才写回源码并 Prettier 格式化

设置

入口：右键任意源码文件 →「设置」
行为：打开工作区根目录下的 meta-i18n.config.js；若文件不存在，会按当前生效的完整配置（含默认值）自动生成一份 export default { ... } 模板再打开，并调用编辑器的格式化命令整理排版

配置

配置文件为工作区根目录下的 meta-i18n.config.js（通过「设置」命令自动创建），保存后自动重新加载；每个命令执行前都会重新读取一次该文件，无需重启窗口即可生效。未配置或字段非法时回退到默认值；工作区不受信任时跳过执行 JS 配置文件，直接使用默认配置并提示一次。

export default {
  quoteKeys: ['$t', 'i18n.t', 't'], // i18n 调用函数集合，用于识别源码中的 key 引用
  tempLangs: ['zh', 'en'], // 语言集合
  defaultLang: 'zh', // 默认语言，未配置时取 tempLangs 第一个元素
  langPaths: '**/src/i18n/locale/**', // 正式语言文件路径（glob）
  tempPaths: '**/src/i18n/temp/**', // 扫描生成的临时语料文件路径（glob）
  ignoreFiles: [], // 忽略的文件（glob）
  ignoreFolders: [], // 忽略的文件夹（glob）
  specialChars: ['&nbsp;', '&lt;', '&gt;', '&amp;', '&quot;'], // 需要特殊处理的 HTML 实体字符
  importPath: "import i18n from '@/i18n'", // 扫描时注入的 i18n 导入语句
  overflow: {
    // 国际化转换后的溢出处理
    enabled: false, // 是否启用（扫描时自动加样式 + 「处理溢出样式」命令均受此开关控制）
    mode: 'style', // 注入方式：'style' 写内联样式 | 'class' 追加类名（样式由项目全局提供）
    style: 'overflow:hidden;text-overflow:ellipsis;white-space:nowrap;', // mode 为 'style' 时写入的内联样式
    className: 'i18n-overflow', // mode 为 'class' 时追加的类名
    addTitle: true, // 是否同时绑定 :title，悬浮展示完整文案
  },
}

字段说明：

字段	类型	说明
`quoteKeys`	`string[]`	识别源码中 i18n 调用的函数名集合，扫描注入、缺失 key 检查、删除无用 key、合并重复语料、还原、溢出处理都依赖它定位调用点
`tempLangs`	`string[]`	语言集合，决定「切换语言」的可选项，也是正式语言文件的白名单（见下方匹配规则）
`defaultLang`	`string`	默认语言，扫描时中文原文写入该语言，还原时也以该语言的文案为依据；未配置时取 `tempLangs[0]`
`langPaths`	`string`（glob）	正式语言文件所在目录
`tempPaths`	`string`（glob）	扫描生成的临时语料文件所在目录
`ignoreFiles` / `ignoreFolders`	`string[]`（glob）	扫描、批量扫描、漏检检查、缺失 key 检查、合并重复语料、还原、溢出处理都会跳过命中的路径（按完整路径做子串匹配，两个字段共用同一口径）
`specialChars`	`string[]`	需要特殊处理的 HTML 实体字符
`importPath`	`string`	扫描时注入的 i18n 导入语句原文
`overflow`	`object`	溢出处理配置，各子字段含义见上方示例注释

正式语言文件匹配规则：只有位于 langPaths 目录下、且文件名（不含扩展名）能匹配 tempLangs 中某一项的 .json 文件，才会被视为正式语言文件，参与拆分、排序、缺失 key 检查、删除无用 key、合并重复语料、还原等操作。匹配采用「大小写不敏感的精确匹配，或主语言子标签前缀匹配」——例如配置 tempLangs: ['zh', 'en'] 时，zh.json、zh-cn.json、en.json、en-us.json 都会被识别，而 unused-i18n-keys.json 这类非语言文件会被排除。

配置文件中若出现插件无法识别的字段名（如把 ignoreFolders 误写成 ignore），会弹窗提示具体字段名并忽略该字段；相同的错误字段集合在同一会话内只提示一次，避免写错字段名后配置被静默忽略、却误以为已生效。

注释忽略标记

不想被扫描替换的代码（如示例文案、日志文本、待重构的 enum），可用注释标记声明忽略区域，作用类似 @ts-ignore：

标记	作用
`i18n-disable`	从标记所在行开始忽略，直到遇到 `i18n-enable`；未闭合时忽略至文件末尾（可用于整文件忽略）
`i18n-enable`	结束忽略区域（含标记所在行）
`i18n-disable-line`	仅忽略标记所在行
`i18n-disable-next-line`	仅忽略标记的下一行

标记必须写在注释中才生效，支持 //、/* */（js/ts/jsx/tsx）与 （vue template）三种形态；字符串字面量中的同名字样不会被误判。

// i18n-disable
const keepRaw = '这里的中文保持原样'
// i18n-enable
const needScan = '这里的中文会被替换为 t() 调用'

const tip = '仅忽略当前行' // i18n-disable-line
// i18n-disable-next-line
const nextLineKeep = '仅忽略下一行'

<template>
  <!-- i18n-disable -->
  <p>这一段中文不会被扫描</p>
  <!-- i18n-enable -->
  <!-- i18n-disable-next-line -->
  <input placeholder="该属性保持原样" />
  <p>这一段中文会被替换为插值调用</p>
</template>

标记按行生效：跨多行的结构（多行属性、跨行模板字符串等）请使用 i18n-disable / i18n-enable 区域标记
忽略区域内的中文同样不会被「检查中文漏检」命令上报
标记注释会保留在产物中，重复扫描结果稳定

编辑器内嵌翻译预览

仅对 .ts/.js/.tsx/.jsx/.vue 文件生效
打开这类文件时，插件会扫描其中的 i18n 调用（按 quoteKeys 匹配），在调用中的 key 后面以半透明文字内嵌展示当前语言对应的译文，效果类似 CodeLens
展示的语言由「切换语言」命令决定，未选择时回退到 defaultLang；切换后无需刷新页面即可看到更新
语料中存储的是 vue-i18n 消息格式（如 {'@'}），预览展示时会自动解转义为字面文本
保存文件、切换活动编辑器窗口都会自动触发重新渲染（内部做了 300ms 防抖，频繁编辑不会闪烁）；若语料文件是在 VSCode 外部被改动的，可执行「刷新数据」命令手动同步

常见问题

enum 成员中的中文没有被替换？ enum 成员是常量表达式，替换为函数调用会产出非法代码，且其值不会跟随语言切换，插件不会静默跳过而是给出「enum 中文风险」警告，需要人工重构（如改为普通对象或函数返回值）。
动态拼接的 key（如 t('a.' + x)）没有被还原 / 合并 / 统计？ 这类 key 无法静态分析，「还原国际化至中文」「合并重复语料」「检查缺失key」都会将其列入跳过或提示人工确认。
修改了 meta-i18n.config.js 但没有生效？ 命令执行前都会重新读取配置文件，通常保存后立即生效（保存动作本身也会触发一次完整重载）。如果一直不生效，检查配置文件是否有语法错误（会弹窗提示加载失败，并回退到上一次有效配置或默认配置），或工作区是否处于「不受信任」状态（此时会跳过执行 JS 配置文件，直接使用默认配置）。
改写源码的命令执行到一半出错怎么办？ 批量扫描、还原、溢出处理、合并重复语料都会先在「输出」面板打印明细报告再弹窗确认，且合并重复语料采用「先改源码后删 key」的顺序，中断时旧 key 仍保留；无论哪种情况，都建议执行前先提交代码，出问题时用 git diff / git checkout 精确回滚。
Prettier 格式化没有生效或报错？ 插件在进程内加载工作区本地的 Prettier 模块（按工作区缓存），找不到本地 Prettier 时会跳过格式化并警告，不会回退到全局 Prettier；若中途安装 / 升级了 Prettier，需要重启扩展宿主（重新加载窗口）才能生效。格式化只改写磁盘文件，如果该文件正在编辑器中且有未保存的修改，会通过 WorkspaceEdit 同步缓冲区内容，可以用 Ctrl+Z 撤销，不会丢失未保存的改动。

本地开发

pnpm install          # 安装依赖（要求 pnpm >= 10.26）
pnpm run compile      # 类型检查 + lint + esbuild 构建
pnpm run watch        # 监听模式（esbuild + tsc）
pnpm run test:unit    # 运行单元测试
pnpm run test         # 运行 VSCode 集成测试
pnpm run vsix         # 打包生成 .vsix

按 F5 可启动扩展开发宿主进行调试。

Enjoy!

meta-plugin-i18n

meta-plugin