Locale Glimpse
在代码中直接看见译文。支持 React i18next、NestJS i18n、Vue I18n 和 Go go-i18n/v2,提供翻译预览、定位和编辑辅助(Vue 和 Go 暂不支持新增、提取和重命名)。
安装与使用
要求 VS Code 1.144.0 或更高版本。从扩展面板执行 Install from VSIX… 安装本地安装包。扩展 ID 为 coderlzw.locale-glimpse。
开发调试时,执行 pnpm install --frozen-lockfile,按 F5 启动扩展开发窗口,再打开目标项目。
默认扫描 **/i18n/locales/*/*.{json,ts}、Go 的 **/active.*.{json,toml,yaml,yml} 和 **/{locales,locale,lang,i18n}/*.{json,ts,yaml,yml}。React/Nest 资源按父目录识别语言,按文件名识别命名空间,例如 src/i18n/locales/zh-CN/common.ts。用 i18n.include 配置其他布局,例如 public/locales/zh-CN/common.json 对应 public/locales/*/*.json。
{
"i18n.language": "zh-CN",
"i18n.fallbackLanguage": "en-US",
"i18n.defaultNamespace": "common",
"i18n.include": ["src/i18n/locales/*/*.{json,ts}"]
}
功能
- 行内预览支持原位替换(
replace)、在键后显示(after)和仅悬停(hover)。替换模式下,选区进入时会显示原始键。可配置光标进入键时显示原键,或让光标所在行始终显示原键。行内预览合并空白并显示完整译文。
- 查找译文时,按候选命名空间依次尝试目标语言、基础语言(例如
zh-CN 对应的 zh)和配置的回退语言。支持静态插值、复数、序数和 context。动态 count 的复数预览会提示分支待确定。悬停可对照各语言的实际译文。
- 编辑器辅助包括 F12 跳转定义、字符串键补全、Problems 缺失译文提示,以及打开语言包和复制键的快捷操作。状态栏可切换译文语言,命令面板可手动刷新索引。语言包和其依赖的未保存修改可反映到预览中。
- 检查翻译一致性会按应用和命名空间检查资源冲突、重复键、缺少命名空间或键、插值变量不一致,以及缺少复数分支。有问题时在编辑器打开文本报告。资源读取错误见
Locale Glimpse 输出面板。
- 新增、提取和重命名需要信任工作区。新增写入选定的现有语言包,提取把选中的静态字符串(含引号)改为
t(...),并要求当前位置已有可识别的 t 绑定。重命名更新当前应用的对应语言包和可静态解析的引用。确认预览后,修改应用到编辑缓冲区。预览后若文件版本变动,命令会拒绝应用。
- 扩展界面跟随 VS Code,支持简体中文和英文,其他界面语言回退英文。预览译文通过
i18n.language 单独选择。
Vue(Vue I18n)
按 Vue I18n 官方用法识别绑定,无需填写 functionNames 或 instanceNames。支持 .vue 的 <script setup>、普通 <script>、JS/TS/JSX/TSX 和模板表达式。
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
const { t: translate } = useI18n({
useScope: 'local',
messages: {
en: { hello: 'Hello {name}', cars: 'no cars | one car | {count} cars' },
'zh-CN': { hello: '你好 {name}', cars: '没有车 | 一辆车 | {count} 辆车' }
}
})
</script>
<template>
<p>{{ translate('hello', { name: 'Vue' }) }}</p>
<p>{{ translate('cars', 2) }}</p>
</template>
| 场景 |
处理方式 |
| Composition API |
useI18n、导入/解构别名、composer .t()、静态函数封装、导入的 i18n.global.t() |
| Options / Legacy API |
this.$t()、模板 $t()、组件 i18n 选项、旧版 new VueI18n() 和 $tc() |
| 模板 |
插值、绑定属性、v-t 字符串或对象、i18n-t / I18nT 的 keypath、静态 slot 参数、plural、locale 和明确作用域 |
| 资源 |
内联 messages、静态导入的 JSON/TS/YAML、静态对象展开、SFC <i18n> 的 JSON/YAML、locale / global / 相对 src |
| 作用域 |
全局与组件局部分开,遵循 useScope、fallbackRoot、globalInjection;i18n.apps 隔离多个应用 |
| 消息 |
命名/列表/字面量插值、\| 复数分支、@: 链接及内置修饰符、数组路径;. / : 不按 i18next namespace 拆分 |
| 回退 |
fallbackLocale 字符串、数组、决策映射、隐式语言层级及 !;未配置时采用插件回退语言 |
| 编辑器 |
行内预览、多语言悬停、作用域内键补全、精确 F12、缺失键诊断、作用域内一致性检查、未保存修改刷新 |
通常只需设置显示语言;从 createI18n / useI18n 可追踪的消息与自定义块会自动读取。单独的语言文件可通过 i18n.include 加入,文件名用语言标签,例如 src/locales/en.json、src/locales/zh-CN.yaml:
{
"i18n.language": "zh-CN",
"i18n.fallbackLanguage": "en",
"i18n.include": ["src/locales/*.{json,ts,yaml,yml}"]
}
分析不会执行项目代码、消息函数、自定义复数规则或加载器。动态键、运行时导入、条件加载、动态 slot、无法确认的父组件作用域、多个歧义实例及自定义解析器不会被猜测成确定译文;动态复数显示分支待确定提示。tm() 返回的消息经 rt() 使用时,仅处理可追踪的静态消息。te()、日期 d()、数字 n()、普通同名函数、注释、样式、v-pre 和被循环/slot 变量遮蔽的绑定不作为翻译键。
目前不支持模板预处理语言、外部 <script src>、任意 Nuxt/Vite 别名配置求值或远程资源加载;模块别名支持根目录 tsconfig.json / jsconfig.json 的静态 paths。源码索引最多读取 1000 个文件、单文件 1 MiB、总计 20 MiB;超限或读取失败时保守保留不确定引用。Vue 的新增、提取和重命名命令暂不开放,消息仍由项目维护。源码中的可运行示例位于 examples/vue。
Go(go-i18n/v2)
自动识别来自 github.com/nicksnyder/go-i18n/v2/i18n 的调用及其项目内封装,无需配置函数名或实例名。支持 Localize、MustLocalize、LocalizeWithTag、LocalizeMessage / MustLocalizeMessage。翻译键取可静态确定的 MessageID 或 DefaultMessage.ID,后者有优先权。支持双引号和反引号字符串。
import "github.com/nicksnyder/go-i18n/v2/i18n"
text := localizer.MustLocalize(&i18n.LocalizeConfig{
MessageID: "user.welcome",
TemplateData: map[string]any{"Name": "张三"},
})
# locales/active.zh-CN.toml
["user.welcome"]
other = "你好 {{.Name}}"
资源支持 JSON、TOML、YAML(.yaml / .yml),语言取文件名最后一段,例如 active.zh-CN.toml、en.json。已有 <language>/<namespace>.json 布局优先按 React/Nest 解析,在语言目录中放置 Go JSON 时请使用 active.en.json 这类带前缀文件名。Go 消息 ID 为完整字符串,. 和 : 不拆分命名空间。相同语言可以分散在多个文件中;同应用同语言的重复 ID 会报告冲突。元数据(hash、description 等)和复数分支不会作为补全项。
默认扫描 active.* 文件。如果文件名为 en.json、zh-CN.yaml 等,请配置扫描范围:
{
"i18n.language": "zh-CN",
"i18n.fallbackLanguage": "en",
"i18n.include": ["locales/*.{json,toml,yaml,yml}"]
}
支持行内预览、多语言悬停、消息 ID 补全、跳转、缺失消息诊断、资源未保存修改刷新和消息一致性检查。静态 PluralCount 决定复数分支;内联 TemplateData 字符串键 map 的静态值用于 {{.Name}} 插值。找不到资源时可预览内联 DefaultMessage,使用配置的回退语言选择其复数分支。
项目内的 Go 源码和 go.mod 用于解析包路径、常量和函数来源,不调用 Go 编译器,也不执行项目代码。例如下面的写法可直接识别,不要求把业务代码改成内联 LocalizeConfig:
import "gin-enterprise/internal/i18n"
message := i18n.T(ctx, i18n.UserCreated)
| 场景 |
识别方式 |
| 导入别名、包实际名称、dot import |
按模块路径和包声明解析,局部同名变量优先 |
| 当前文件/同包其他文件/项目内导入包的常量 |
静态解析字符串、常量别名和字符串拼接;循环或重复定义保持未知 |
自定义 T(ctx, id, ...)、改名封装、多层转发 |
沿函数参数和调用追踪至 go-i18n,支持可变参数及静态函数别名 |
| 配置变量、指针别名、字段赋值、默认消息变量、配置工厂 |
读取调用现场可确定的静态字段;外部修改或分支结果不一致时保持未知 |
| 已知接收者类型的方法及方法值 |
根据本地类型和方法声明追踪,接口动态分派不猜测 |
| Gin 返回的 handler、回调、局部函数字面量 |
分析其中的翻译调用;捕获的可变值保守视为未知 |
| 模板参数、嵌套 map、复数参数 |
代入能确定的静态值,未知值保留占位符 |
| 未保存常量/封装文件、创建/删除/模块配置变更 |
使跨文件引用缓存失效并重新索引;关闭未保存文件后恢复磁盘版本 |
常量引用上会显示译文,选择补全时可将该引用替换成字符串 ID;跨文件封装内部拼接得到的 ID 仅提供预览,不提供可能导致重复前缀的补全修改。
这是一套有界静态分析,不是完整 Go 编译器。动态 ID、反射、无法确定的接口调用、运行时选择的函数、条件分支之间不一致的配置及无法读取的外部模块保持未知。构建标签产生的同名声明不擅自选取其中之一。只读取工作区内的模块,不执行 go list、不下载依赖,也不处理工作区外的 replace / go.work 目标。源码索引排除 vendor、构建目录及测试文件,限制为 1,000 个 Go 文件、64 个模块、每文件 1 MiB、总共 20 MiB;当前打开的测试文件仍可作本地分析。达到限制或读取失败时输出索引不完整提示,停用项目符号推断,仍可识别当前文件中的直接调用。
不执行完整 Go template:控制语句和未知参数保留原文。语言选择使用插件的目标语言、基础语言与回退语言,不模拟运行时 Bundle 的完整语言匹配。Go 的新增、提取和重命名暂不支持,请使用官方 goi18n extract/merge 工作流。源码中的 Go 示例位于 examples/go-i18n/main.go;用法参考 go-i18n 官方文档。
命令面板搜索 Locale Glimpse,设置中搜索 i18n。
支持范围
识别 hook 别名、解构别名、静态 t/translate 调用、Trans、纯属性或静态下标 selector。普通裸 t() 需要实际导入、hook 绑定或显式配置函数名。
TS 语言包支持静态导出对象、as const、satisfies、文件内常量,以及应用目录内的相对 TS/JSON 对象导入。仅静态读取,不执行项目代码;拒绝循环、越界路径、动态调用、副作用导入。跨文件图限制为 16 层、64 个依赖。
不支持路径别名、re-export、YAML、动态键及运行时格式化。共享资源仅提供预览/跳转,编辑命令不直接修改共享定义。重命名限同 namespace、同父路径;歧义复数/context 和不明确的回退 selector 会拒绝修改。点属性 selector 的新名称需为合法标识符。
多应用示例
{
"i18n.apps": [
{"sourceRoot":"apps/web","include":["apps/web/src/i18n/*/*.ts"],"defaultNamespace":"common"},
{"sourceRoot":"apps/api","include":["apps/api/src/i18n/*/*.json"],"defaultNamespace":"common"}
]
}
应用路径和扫描规则均相对各工作区文件夹。源码和资源按最长 sourceRoot 前缀归属应用,查询和语言回退限于同一应用及工作区文件夹。配置应用扫描规则后,扫描范围由应用的 include 和显式设置的全局扫描规则共同决定。
默认配置
以下默认值已注释,可合并到 settings.json。
{
// 启用译文预览与悬停详情。
// "i18n.enabled": true,
// 预览使用的语言目录名称。
// "i18n.language": "zh-CN",
// 译文缺失时的回退语言。
// "i18n.fallbackLanguage": "en",
// 未指定命名空间时使用的资源文件名,不含 .json 或 .ts 扩展名。
// "i18n.defaultNamespace": "translation",
// 翻译文件 glob;React/Nest 支持 <language>/<namespace>.json 或 .ts;Go 支持 <前缀.><language>.json/.toml/.yaml/.yml。
// "i18n.include": [
// "**/i18n/locales/*/*.{json,ts}",
// "**/active.*.{json,toml,yaml,yml}"
// ],
// 翻译预览显示方式。
// "i18n.displayMode": "replace",
// 保留翻译键的引号。
// "i18n.showQuotes": true,
// 替换模式下光标进入 key 时恢复源码。非空选区始终恢复源码以便编辑。
// "i18n.revealOnSelection": true,
// 显示缺失翻译提示,关闭后仍保留原 key。
// "i18n.showMissing": true,
// 未找到翻译时的提示文本。留空时跟随 VS Code 界面语言。
// "i18n.missingText": "",
// 空白译文的提示文本。留空时跟随 VS Code 界面语言。
// "i18n.emptyText": "",
// 显示翻译键和译文提示的悬停详情。
// "i18n.hover.enabled": true,
// 在状态栏显示语言切换入口。
// "i18n.statusBar.enabled": true,
// 显示译文提示边框。
// "i18n.appearance.showBorder": true,
// 译文提示圆角半径,单位 px。
// "i18n.appearance.borderRadius": 4,
// 译文提示左右内边距,单位 px。
// "i18n.appearance.padding": 4,
// 译文字体颜色,支持 VS Code 主题颜色 token 或 #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
// "i18n.appearance.color": "debugTokenExpression.string",
// 译文背景颜色,支持 VS Code 主题颜色 token 或 #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
// "i18n.appearance.backgroundColor": "textCodeBlock.background",
// 译文边框颜色,支持 VS Code 主题颜色 token 或 #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
// "i18n.appearance.borderColor": "editorWidget.border",
// 在 Problems 面板显示打开文件中的缺失翻译警告。
// "i18n.diagnostics.enabled": true,
// 悬停对照各语言译文,缺失项不使用回退译文。
// "i18n.hover.showAllLanguages": true,
// replace 模式下,光标所在行始终显示原始 key,其他行显示译文。
// "i18n.revealCurrentLine": false,
// 仅用于自定义封装,例如 translate;React hook 绑定、i18next 导入和 Nest i18nValidationMessage 自动识别,无需填写。
// "i18n.recognition.functionNames": [],
// 实例白名单(支持 this.<name>);i18n/i18next 为默认值,i18n 路径默认导入、I18nService/I18nContext 类型参数及导入的 I18nContext.current() 自动识别。
// "i18n.recognition.instanceNames": [
// "i18n",
// "i18next"
// ],
// 译文透明度,0.1~1。
// "i18n.appearance.opacity": 1,
// 译文字号,0 跟随编辑器,其他值限制为 8~40 px。
// "i18n.appearance.fontSize": 0,
// 按 sourceRoot 最长前缀隔离应用。资源须位于所属应用目录,路径相对工作区。
// "i18n.apps": [],
// 缺失翻译标签文字与边框颜色,支持主题 token 或十六进制颜色。
// "i18n.missing.color": "editorWarning.foreground",
// 缺失翻译标签背景颜色,支持主题 token 或十六进制颜色。
// "i18n.missing.backgroundColor": "editorWarning.background",
// 语言包文件大小上限,KB。
// "i18n.performance.maxFileSizeKB": 1024,
// 刷新防抖时间,毫秒。
// "i18n.performance.debounceMs": 250,
// 未命中主命名空间时依次查找的备用命名空间。
// "i18n.fallbackNamespaces": [],
}
开发与验证
pnpm run compile:类型检查、Lint、构建。
pnpm run test:unit:核心、API 冒烟、编辑和本地化检查。
pnpm run test:host:真实 VS Code 宿主验证。
pnpm run package:vsix:生成本地安装包。
采用 MIT 许可证。安装包内含 TypeScript、YAML、TOML 解析器及其运行依赖的第三方许可与声明。