i18n Inline Viewer
在代码中行内显示译文、Cmd+点击一键跳转语言包编辑的 VSCode 扩展。面向采用统一 i18n 规范（i18next + 语言目录 + index.ts 聚合）的项目设计，配置驱动、开箱即用。
功能
- 行内译文提示：
t('customer.title') 调用处直接显示当前显示语言的译文（如「客户列表」），不修改文件内容；支持追加显示（调用后显示）与替换显示（隐藏 key 调用、译文直显）两种方式，译文颜色可自定义
- Cmd+点击跳转编辑：macOS
Cmd+左键点击（Windows/Linux Ctrl+左键，或 F12）→ 直接打开对应语言 JSON 并自动选中译文文本，落键即可覆盖修改
- 侧边栏译文搜索：活动栏「译文搜索」视图，输入中文即时（300ms 防抖）直出代码使用处结果——原生搜索风格按文件折叠分组（折叠箭头 + 文件图标 + 文件名 + 路径 + 命中数；文件图标为当前图标主题的原生图标，如 Material / Seti），结果常驻、点击直达；
Cmd+Alt+F 从编辑器带入选中译文。补齐"全文搜中文只能搜到语言包"的缺口
- 当前文件译文面板：「译文搜索」视图下方的折叠面板，列出当前激活文件中的所有翻译调用（中文译文优先展示、key 与行号辅助显示，缺失/未定义有标记），点击即定位到对应代码位置；随文件切换、编辑与显示语言切换自动刷新
- 切换显示语言：状态栏 + 命令，在 cn / en / es-MX 等语言间切换（自动发现）
- 实时更新：代码新增
t('key')、语言包新增/修改词条，约 300ms 内自动刷新；新 key 尚未配译文时显示 ⚠ 未定义，一眼发现漏配
- 通用兼容：自动识别
langs/{lang}/… 目录布局或 langs/cn.json 单文件布局；无 index.ts 时按路径推断前缀；同时兼容嵌套 JSON 与扁平点号键
支持的目录结构
| 结构 |
示例 |
说明 |
| 语言目录 + index.ts 聚合（标准规范） |
langs/cn/index.ts + langs/cn/**/*.json |
精确解析 index.ts 的 import 与对象树，支持顶层别名（node → developmentModule/node.json）与嵌套前缀（purchase.common） |
| 语言目录无 index.ts |
langs/cn/customer.json |
按文件路径推断前缀：purchase/sample.json → purchase.sample.* |
| 单文件语言包 |
langs/cn.json |
整文件即全部词条 |
安装
团队分发（推荐）：拿到 i18n-inline-viewer-<版本号>.vsix 后：
code --install-extension i18n-inline-viewer-<版本号>.vsix
或在 VSCode 扩展面板右上角 ... → Install from VSIX...。
安装/更新后请完整重载窗口（Developer: Reload Window）再使用——只「重启扩展宿主」不足以刷新窗口的扩展配置清单（详见「常见问题」）。
本地开发调试：
npm install
npm run watch # 或 npm run build
用 VSCode 打开本项目，按 F5 选择 Run Extension (dev workspace)——会以一个已接入该规范的项目为被测试工作区启动扩展宿主（工作区路径可在 .vscode/launch.json 中调整）。首次请信任工作区（Workspace Trust）。
使用
| 操作 |
方式 |
| 切换显示语言 |
点击状态栏 i18n: cn，或 Cmd+Alt+L（Win/Linux Ctrl+Alt+L），或命令面板 i18n: 切换显示语言 |
| 切换译文显示方式 |
Cmd+Alt+M，或命令面板 i18n: 切换译文显示方式（追加显示 / 替换显示 / 关闭 / 更换译文颜色） |
| 更换译文颜色 |
Cmd+Alt+C，或命令面板 i18n: 更换译文颜色（预设色板 / 自定义 CSS 颜色，即时生效） |
| 开关行内提示 |
Cmd+Alt+H，或命令面板 i18n: 开关行内译文提示 |
| 跳转 / 快速修改 |
在 key 上 Cmd+左键点击（或 F12）→ 打开语言包并选中译文，直接输入覆盖；替换显示模式下直接点击译文即可跳转（追加模式同样支持） |
| 按译文查代码引用 |
活动栏「译文搜索」视图直接输入译文（结果即时、常驻保留）；或选中中文按 Cmd+Alt+F / 右键带入视图；视图内可一键「在内置搜索面板中打开」 |
| 当前文件译文 |
「译文搜索」视图下方的折叠面板：列出当前文件全部翻译，点击定位；点击面板标题可折叠/展开（状态保留） |
| 重建索引 |
命令面板 i18n: 重建语言包索引 |
关于「在全局搜索框直接搜中文出代码文件」
VSCode 的内置全局搜索是纯文本搜索（ripgrep），不向扩展开放：扩展既不能读取/改写搜索框内容，也不能向搜索结果注入条目（官方明确扩展无法访问 UI DOM，也没有搜索 provider 贡献点）。而代码里只有 t('purchase.request.no')，中文仅存在于语言包——所以「在搜索框输中文、结果直接变成代码文件」在任何插件中都无法实现（i18n-ally 同样做不到），这是平台限制。
本扩展提供最接近原生体验的替代流程：侧边栏「译文搜索」视图（活动栏放大镜图标）——输入中文即时直出代码文件结果并常驻保留：
- 视图直搜：点击活动栏图标，输入译文 → 结果列表实时更新（原生风格：按文件折叠分组，组头为 折叠箭头 + 文件图标 + 文件名 + 路径 + 命中数，文件图标取当前图标主题的原生图标），点击条目即打开使用处；译文中命中的查询词按原生搜索同款配色高亮；文件组可折叠（发起新搜索时重置为全部展开）
- 编辑器带入：选中中文按
Cmd+Alt+F（或右键菜单），或光标停在语言包译文上、剪贴板含中文，都会自动带入视图执行搜索
- 转原生搜索面板：结果区「在内置搜索面板中打开」按钮（多 key 自动正则 OR 合并；自动附带去前缀后缀，
t(`${localeKey}.a.b`) 模板拼写同样能命中；无结果或清空输入时该入口隐藏）
内置搜索面板只渲染文件原始文本，无法显示文件中不存在的译文（扩展不能向搜索结果注入内容）——所以「结果带中文」由本扩展的结果列表提供，而非原生面板。
新项目接入（同规范零配置）
- 安装
.vsix
- 若语言资源位于
src/locales/langs/{lang}/…（标准规范布局），无需任何配置；找不到时会自动搜索 src/locales、locales、public/locales 等常见位置
- 其他路径或约定，在项目
.vscode/settings.json 里显式声明：
{
"i18nHelper.localePaths": ["src/locales/langs"],
"i18nHelper.sourceLanguage": "cn",
"i18nHelper.callNames": ["t"],
"i18nHelper.include": ["src/**/*.{ts,tsx}"]
}
配置项
| 配置 |
默认值 |
说明 |
i18nHelper.localePaths |
["src/locales/langs"] |
语言资源根目录（相对 workspace 根），不存在时自动回退搜索常见位置 |
i18nHelper.localeIndexFile |
"index.ts" |
语言目录聚合入口；不存在时按路径推断前缀 |
i18nHelper.sourceLanguage |
"cn" |
源语言（缺失时的兜底语言，并决定 ⚠ 兜底标记） |
i18nHelper.displayLanguage |
"cn" |
行内提示展示语言，状态栏/命令可切换（写入用户级设置） |
i18nHelper.languages |
[] |
留空自动发现语言 |
i18nHelper.callNames |
["t"] |
识别的翻译函数名（可加 $t 等） |
i18nHelper.detectMemberCalls |
true |
是否识别 i18n.t(...) 等成员调用 |
i18nHelper.include |
["src/**/*.{ts,tsx}"] |
参与提示的源码 glob |
i18nHelper.exclude |
["**/e2e/**","**/node_modules/**","**/dist/**"] |
排除的 glob |
i18nHelper.inlayHints.enabled |
true |
行内译文开关 |
i18nHelper.inlayHints.mode |
"append" |
显示方式：append 追加显示 / replace 替换显示（隐藏 key 调用、译文直显） |
i18nHelper.inlayHints.color |
"" |
译文颜色（CSS 颜色值，如 #FF6B6B）；留空使用主题色。也可用命令 i18n: 更换译文颜色（Cmd+Alt+C）快捷选择 |
i18nHelper.inlayHints.maxLength |
60 |
提示最大字符数，超出截断 |
i18nHelper.inlayHints.showMissing |
true |
目标语言缺失时用源语言兜底并加标记 |
i18nHelper.inlayHints.showUnresolved |
true |
静态 key 全语言缺失时提示 ⚠ 未定义（仅对独立 t(...) 调用） |
i18nHelper.inlayHints.fallbackMarker |
" (cn)" |
兜底提示的附加标记 |
与 i18n-ally 共存
本扩展与 i18n-ally 的"行内显示译文"功能重叠。建议在项目 .vscode/settings.json 中关闭 i18n-ally 的行内注解，保留其 hover/编辑能力：
{
"i18n-ally.annotations": false
}
调试扩展宿主时也可用 --disable-extension lokalise.i18n-ally 临时禁用。
常见问题
更新扩展后，Cmd+Alt+M 切换显示方式报「没有注册配置 i18nHelper.inlayHints.mode，因此无法写入用户设置」？
这是「装了新版本、但只重启了扩展宿主、窗口未完整重载」的典型状态：扩展代码已是新版（命令能触发），但窗口主进程的配置清单仍是旧版（不认识本版新增的配置项），因此新设置无法写入。
解法：完整重载窗口 —— 命令面板 → Developer: Reload Window（或退出 VSCode 重新打开）即可恢复。0.2.1 起遇到该情况会直接给出提示 + **一键「重载窗口」**按钮，不再抛晦涩错误。
已知限制
- 动态 key 无法解析（
t(key)、t(`${item.type}.label`)），不显示提示
- 模板 key 仅折叠同文件
const X = 'literal' 常量（当前项目均无跨文件用法）
- 反查使用处：同文件
const localeKey 折叠的模板调用（t(`${localeKey}.a.b`)）可被精确定位；无法折叠的动态 key 在静态片段足够具体时以「⚠ 可能相关」列出；跨文件拼接的 key 无法覆盖
- 成员调用（
i18n.t）在全语言缺失时不提示 ⚠ 未定义，避免把恰好叫 .t 的其他对象方法误报
- 替换显示模式下悬停译文：显示该译文的 i18n key（形如
`customer.title`，纯净无后缀）与可点击手型指针，点击跳转行为不变
- 说明：曾基于 VSCode 原生链接（DocumentLink）实现「按住
Cmd 才显示手型」；但原生链接的悬停提示会被强制拼接 "(cmd + 单击)" 后缀且无法去除，与「提示只显示 key」冲突，现已改用自定义 Hover + cursor 注入（悬停即手型）
- 追加显示模式下悬停 i18n key 文本：按住
Cmd 显示原生下划线 + 手势（由定义跳转机制提供）
- 运行时切换语言/开关只写用户级设置，不改动任何业务仓库
开发
npm run typecheck # 类型检查
npm run test # vitest 单测（含对真实项目 index.ts 的断言，本机存在时执行）
npm run build # esbuild 打包到 dist/extension.js
npm run smoke # 打包产物冒烟（需先 build；stub vscode API 加载 bundle 并用真实语言包数据验证提示/跳转）
npx vsce package # 产出 .vsix
