i18n-ally 插件需手动配置路径、语言标签和文件格式才能启用全部功能；默认仅扫描 src/locales 和 public/locales，须在设置中指定 i18n-ally.localesPaths 并重载；子语言标签如 en-US 需显式加入 i18n-ally.languages；动态 key 不被静态分析支持，应避免变量拼接或补全所有可能 key；JSON 文件须规范（纯 JSON、双引号、无注释等）；插件不校验命名规范与运行时错误。
i18n-ally 插件不会自动生效，必须手动配对路径、语言标签和文件格式，否则所有功能（预览、跳转、补全、缺失检测）都处于“静默失能”状态。
为什么 i18n-ally 找不到 locales 文件夹
插件默认只扫描 src/locales 和 public/locales 这两个路径，其余位置一律忽略——不是插件故障，是它根本没被告诉去哪找。
- 在 VSCode 设置里搜索
i18n-ally.localesPaths，设为数组形式，例如：["src/i18n", "assets/lang"] - 路径必须是**相对于工作区根目录**的，不能带
./前缀，也不能写绝对路径（如/Users/xxx/project/src/locales） - 改完后必须右键命令面板运行
i18n Ally: Reload Locales，重启 VSCode 不保证刷新缓存 - 如果用嵌套 JSON（如
{"form": {"submit": "提交"}}），需开启i18n-ally.flattenNamespace，否则键名显示为form.submit而非submit
en-US、zh-Hans 等子语言标签不显示
i18n-ally 默认只识别 en、zh 这类基础语言码，遇到带连字符的变体（如 en-US）会直接过滤掉，导致右侧语言栏空白、键名不着色。
- 修改设置项
i18n-ally.languages，显式列出完整标签：["en", "en-US", "zh", "zh-Hans", "ja"] - 同时确认
i18n-ally.sourceLanguage设为其中某一个（如"en-US"），否则源语言键可能被误标为“未翻译” - 注意：插件不校验运行时兼容性。Vue I18n v9 支持
zh-Hans，v8 只认zh，得你自己对齐框架版本
t() 里用了变量拼接却标红 “missing”
像 t(`button.${type}`) 或 t(keys[i]) 这类动态 key，i18n-ally 静态分析无法推断变量值，直接报缺失——这不是 bug，是能力边界。
- 优先改写为字面量对象访问：
t(buttons[type])，前提是buttons是静态对象（如const buttons = { primary: '确定', secondary: '取消' }） - 对必须动态的场景，在对应 locale 文件中手动补全所有可能 key，哪怕先填占位符（如
"loading": "loading"） - 可临时关闭
i18n-ally.warnIfMissing避免干扰，但别关i18n-ally.showMissingKey，它是发现真实漏翻的关键手段 - 若用
useI18n()组合式 API，检查是否漏了useScope: 'global'，否则插件找不到上下文
JSON 文件里键名不补全、预览异常
常见于用 .ts 文件代替 .json 存翻译内容，或 JSON 结构不符合插件预期（如顶层不是对象、含注释、单引号、尾逗号）。
- 坚持用纯
.json格式，避免.ts导出对象——插件对 JSON 的读写支持最完整 - 确保 JSON 文件顶层是合法对象，无 BOM、无注释、无尾逗号、所有字符串用双引号
- 如果项目用自定义 hook（如
useT()），需在配置中通过i18n-ally.functions告知插件翻译入口函数名
真正容易被忽略的是：插件不会帮你校验 key 命名规范、复数语法、占位符一致性，也不会拦截运行时因 key 拼错导致的空文案；这些只能靠团队约定 + CI 检查兜底。
