i18n-ally插件需手动配置localesPaths、languages等设置才能正常工作，否则预览、补全、缺失检测等功能失效；路径须为工作区根目录相对路径，子语言标签需显式声明，动态key不被识别，JSON格式须规范。
很多开发者初次接触 i18n-ally 时，可能会遇到一个困惑：明明插件装好了，怎么翻译预览、代码补全这些功能全都“罢工”了？其实，问题往往不在于插件本身，而在于一个关键的认知——i18n-ally 并不会自动扫描你的项目结构。你必须明确地告诉它：“翻译文件在这里，请按这个规则来识别。” 如果路径没对上，所有高级功能自然就失效了。
VSCode 找不到 locales 文件夹
插件内置了一套默认的路径猜测逻辑，通常会去查找 src/locales、public/locales 这类常见目录。但现实情况是，项目结构千差万别，你的翻译文件很可能躺在 src/i18n 或 assets/lang 里。这时候，插件就会“视而不见”。
- 解决办法很直接：在 VSCode 设置里搜索
i18n-ally.localesPaths，将其值修改为一个数组，比如["src/i18n", "assets/lang"]，把所有可能的翻译目录都列进去。 - 这里有个细节容易踩坑：路径必须是相对于工作区根目录的。别写成
./src/i18n，更别用绝对路径，否则配置了也白搭。 - 修改配置后，记得在命令面板（Ctrl+Shift+P）里运行
i18n Ally: Reload Locales来强制刷新。单纯重启 VSCode，有时候并不奏效。 - 如果你的 JSON 文件使用了嵌套结构（例如
{"common": {"submit": "提交"}}），别忘了开启i18n-ally.flattenNamespace设置。否则，你在侧边栏看到的键名会是冗长的common.submit，而不是简洁的submit。
i18n-ally 不识别 en-US、zh-Hans 等子语言标签
另一个常见问题是语言栏一片空白，或者翻译键始终不亮色。这通常是因为插件默认只识别基础的语言代码，像 en、zh。一旦遇到带地区或变体后缀的标签，比如 en-US 或 zh-Hans，它就直接当成无效配置处理了。
- 你需要手动配置
i18n-ally.languages这个设置项，把所有用到的完整语言标签都显式声明出来，例如：["en", "en-US", "zh", "zh-Hans", "ja"]。 - 同时，检查一下
i18n-ally.sourceLanguage是否设置正确。它应该指向你定义源语言（通常是英文）的那个标签，比如"en-US"。如果这里没设对，插件可能会把你所有的源语言键都错误地标记为“未翻译”。 - 需要警惕的是，插件只负责文件识别，不负责运行时校验。举个例子，Vue I18n v9 可以很好地支持
zh-Hans，但 v8 版本可能只认zh。所以，你配置的语言标签必须和项目实际使用的 i18n 框架版本相匹配，否则上线后可能会遇到回退失败的问题。
t() 里用了变量拼接，但插件标红 missing
看到代码里动态生成的翻译键被标红，提示缺失，先别急着怀疑插件。像 t(`button.${type}`) 或 t(keys[i]) 这种写法，其最终的 key 是在运行时才确定的，i18n-ally 作为一个静态分析工具，确实无法预知所有可能性。这属于它的能力边界，并非 bug。
- 首先，考虑能否重构代码，将动态拼接改为对静态对象的访问。例如，先定义一个对象
buttons = { primary: 'button.primary', secondary: 'button.secondary' }，然后调用t(buttons[type])。这样，插件就能分析到所有可能的键了。 - 对于必须使用动态 key 的场景，最务实的做法是：在对应的 locale 翻译文件中，手动把所有可能用到的键都预先定义好，哪怕先填上一个占位符文本（比如
"loading": "loading"）。 - 如果觉得错误提示太干扰，可以暂时关闭
i18n-ally.warnIfMissing设置。但请注意，i18n-ally.showMissingKey这个功能最好保持开启，它依然是发现那些真正被遗漏的翻译项的关键手段。 - 另外，如果你在使用 Vue 3 的组合式 API
useI18n()，检查一下是否漏掉了useScope: 'global'这个参数。如果作用域不对，插件也可能无法定位到全局的翻译键。
JSON 文件里键名显示异常或补全失效
有时候，翻译文件明明在那里，但插件显示的内容却乱七八糟，或者代码补全根本不触发。这多半和文件格式或结构不符合插件预期有关。
- 最稳妥的方案是坚持使用纯
.json文件来存储翻译内容。尽量避免使用.ts文件导出对象，因为插件对标准 JSON 的读写支持是最完整、最稳定的。 - 确保你的 JSON 文件是合法的：顶层必须是一个对象，文件开头没有 BOM 头，内部没有注释（JSON 标准不支持），没有尾随逗号，并且所有字符串都用双引号包裹。
- 你可以在项目级的
.vscode/settings.json文件中，明确指定插件使用的解析器："i18n-ally.enabledParsers": ["json"]。 - 如果你的翻译文件按命名空间进行了拆分（例如
locales/zh-CN/user.json,locales/zh-CN/product.json），那么需要开启i18n-ally.namespace功能，并正确配置i18n-ally.pathMatcher。这个模式字符串决定了插件如何组织文件和命名空间，常见的值有"{locale}.json"（单文件）或"{locale}/{ns}.json"（多文件）。
最后，有两个点特别容易被忽略：第一，插件不会自动感知你新增的语言文件。即使路径和命名完全正确，在添加新文件后，通常也需要手动执行一次“重载 locales”命令。第二，务必确保你在插件中配置的子语言标签（如 zh-Hans），与你项目中使用的 i18n 框架（如 Vue I18n、React i18next）实际支持的语言代码完全一致。任何不匹配都可能导致运行时回退机制静默失败，而你却在开发工具里看到一切正常的假象。
