做国际化（i18n）是前端开发中最「看起来简单、做起来要命」的事情之一。翻译文件散落各处，键名拼写错误要到运行时才发现，新增语言要手动逐个补全，源语言改了但翻译没跟上……如果你也深有同感，这篇文章就是写给你的。

为什么要做 i18n Ally Next？

i18n Ally 是 VS Code 生态中最受欢迎的国际化插件之一，由 @antfu 创建。它提供了内联注解、翻译管理、文案提取等一系列强大功能，极大地提升了 i18n 开发体验。

但随着时间推移，原项目的维护逐渐放缓。社区积累了大量 Issue 和 PR 未被处理，一些现代框架（如 Next-intl、Svelte 5）的支持也迟迟没有跟上。更关键的是——原项目没有文档站点，所有使用说明散落在 README 和 Wiki 中，新用户上手成本很高。

i18n Ally Next 正是在这样的背景下诞生的——我们 fork 了原项目，在保留所有经典功能的基础上，持续修复 Bug、新增特性、改善性能，并且从零搭建了完整的文档体系。

为什么文档这么重要？

原版 i18n Ally 功能强大，但有一个致命问题：你不知道它能做什么。

很多开发者安装后只用到了内联注解这一个功能，对审阅系统、自定义框架、正则匹配、路径匹配等高级功能一无所知。这不是用户的问题，是文档缺失的问题。

i18n Ally Next 的文档站点从以下几个维度重新组织了内容：

🧱 结构化的指南体系

• 快速开始 — 从安装到看到第一个内联注解，5 分钟搞定
• 支持的框架 — 完整列出 25+ 支持的框架及其自动检测机制
• 语言文件格式 — JSON、YAML、JSON5、PO、Properties、FTL……每种格式的用法和注意事项
• 命名空间 — 大型项目必备的翻译文件组织方式
• 文案提取 — 从硬编码字符串到 i18n 键的完整工作流
• 审阅系统 — 团队协作翻译的质量保障
• 机器翻译 — 8 种翻译引擎的配置与对比

🏗️ 框架最佳实践

不同框架的 i18n 方案差异很大。我们为每个主流框架编写了专属的最佳实践指南：

• Vue I18n — SFC <i18n> 块、Composition API、Nuxt I18n
• React & Next.js — react-i18next、Next-intl、Next-international
• Angular — ngx-translate、Transloco
• Svelte、Laravel 与 Rails — 各有专属配置示例
• 自定义框架 — 从零配置到完整运行的实战教程

📋 完整的配置参考

每一个配置项都有：类型、默认值、使用场景说明和代码示例。不再需要猜测某个配置是干什么的。

• settings.json 配置 — 100+ 配置项的完整参考
• 自定义框架配置 — YAML 配置文件的每个字段详解

新增功能详解

🤖 Editor LLM：零配置 AI 翻译

这是 i18n Ally Next 最具创新性的功能之一。它直接调用你编辑器内置的大语言模型进行翻译——无需 API Key，无需额外配置。

{ "i18n-ally-next.translate.engines": ["editor-llm"] }

它会自动检测你的编辑器环境：

• VS Code — 调用 GitHub Copilot
• Cursor — 调用 Cursor 内置模型
• Windsurf — 调用 Windsurf 内置模型

更强大的是，Editor LLM 支持批量翻译。当你选择翻译多个键时，它会将同一语言对的翻译请求合并为一次 API 调用，按 JSON 格式批量处理，大幅提升翻译速度并降低 token 消耗。

你也可以指定模型：

{ "i18n-ally-next.translate.editor-llm.model": "gpt-4o" }

🦙 Ollama：完全离线的本地翻译

对于有数据安全要求的团队，Ollama 引擎让你可以使用本地部署的大模型进行翻译，数据完全不出本机。

{
  "i18n-ally-next.translate.engines": ["ollama"],
  "i18n-ally-next.translate.ollama.apiRoot": "http://localhost:11434",
  "i18n-ally-next.translate.ollama.model": "qwen2.5:latest"
}

通过 OpenAI 兼容 API 调用，支持任何 Ollama 上可用的模型。翻译 prompt 经过专门优化，能正确保留 {0}、{name}、{{variable}} 等占位符。

🔌 8 种翻译引擎全覆盖

引擎	特点	适用场景
Google	免费、语言覆盖广	日常开发
Google CN	国内可直接访问	国内开发者
DeepL	翻译质量最佳	面向用户的正式翻译
OpenAI	灵活、可自定义 API 地址	需要高质量 + 自定义
Ollama	完全离线、数据安全	企业内网环境
Editor LLM	零配置、批量翻译	快速迭代
百度翻译	国内 API、中文优化	中文项目
LibreTranslate	开源自托管	完全自主可控

引擎可以配置多个作为 fallback：

{ "i18n-ally-next.translate.engines": ["editor-llm", "deepl", "google"] }

🕵️ 陈旧翻译检测

这是一个容易被忽视但极其重要的功能。当源语言的文案发生变更时，其他语言的翻译可能已经过时了——但你不会收到任何提醒。

i18n Ally Next 的陈旧翻译检测（Stale Translation Check）解决了这个问题：

1. 插件会记录每个键的源语言快照
2. 当你运行检测命令时，它会对比快照与当前值
3. 发现变更后，你可以选择：
   • 全部重新翻译 — 一键将所有过期翻译发送到翻译引擎
   • 逐个确认 — 逐条查看变更内容，决定是否重新翻译
   • 仅更新快照 — 确认当前翻译仍然有效，更新基准

这意味着你的翻译永远不会「悄悄过期」。

🔍 全项目扫描与批量提取

单文件的硬编码检测很有用，但真正的 i18n 迁移需要全项目级别的能力。

「扫描并提取全部」命令可以：

1. 扫描项目中所有支持的文件（可通过 glob 配置范围）
2. 检测每个文件中的硬编码字符串
3. 显示扫描结果摘要（N 个文件，M 个硬编码字符串）
4. 确认后自动批量提取，为每个字符串生成键名并写入 locale 文件

{
  "i18n-ally-next.extract.scanningInclude": ["src/**/*.{ts,tsx,vue}"],
  "i18n-ally-next.extract.scanningIgnore": ["src/generated/**"],
  "i18n-ally-next.extract.keygenStrategy": "slug",
  "i18n-ally-next.extract.keygenStyle": "camelCase"
}

📝 审阅系统（v2的功能）

翻译不是一个人的事。i18n Ally Next 内置了审阅系统（Review System），支持：

• 逐条审阅翻译结果，标记为「通过」或「需修改」
• 留下评论，与团队成员异步协作
• 审阅数据以 JSON 存储在项目中，可纳入版本控制
• 翻译结果可先保存为候选翻译（translate.saveAsCandidates），审阅通过后再正式写入

这意味着翻译质量不再是黑盒——每一条翻译都有迹可循。

自定义框架：支持任意 i18n 方案

这是 i18n Ally Next 最灵活的功能之一。无论你使用什么 i18n 库，甚至是团队自研的方案，都可以通过一个 YAML 配置文件让插件完美支持。

为什么需要自定义框架？

内置框架覆盖了 25+ 主流方案，但现实中总有例外：

• 公司内部封装的 i18n 工具函数
• 使用了非标准的翻译函数名（如 __(), lang(), msg()）
• 新兴框架尚未被内置支持
• 需要同时匹配多种调用模式

如何配置？

在项目根目录创建 .vscode/i18n-ally-next-custom-framework.yml：

# 指定生效的文件类型
languageIds:
  - typescript
  - typescriptreact
  - vue

# 正则匹配翻译函数调用，{key} 是占位符
usageMatchRegex:
  - "\\Wt\\(\\s*['\"`]({key})['\"`]"
  - "\\W\\$t\\(\\s*['\"`]({key})['\"`]"
  - "\\Wi18n\\.t\\(\\s*['\"`]({key})['\"`]"

# 提取重构模板，$1 代表键名
refactorTemplates:
  - "t('$1')"
  - "{t('$1')}"

# 命名空间支持
namespace: true
namespaceDelimiter: ":"

# 作用域范围检测（如 React useTranslation hook）
scopeRangeRegex: "useTranslation\\(['\"](.+?)['\"]\\)"

# 是否禁用所有内置框架
monopoly: false

作用域范围是什么？

scopeRangeRegex 是一个非常实用的功能。以 React 为例：

const { t } = useTranslation("settings")

t("title")        // → 自动解析为 "settings.title"
t("theme.dark")   // → 自动解析为 "settings.theme.dark"

插件会根据正则匹配的结果自动划分作用域范围——从匹配位置到下一个匹配位置（或文件末尾）。在作用域内的所有 t() 调用都会自动加上命名空间前缀。

热重载

修改 YAML 配置文件后无需重启 VS Code，插件会自动检测文件变更并重新加载。这让调试正则表达式变得非常方便——改完立刻看效果。

快速上手

安装

在 VS Code 扩展面板搜索 i18n Ally Next，或从以下渠道安装：

• VS Code 插件市场
• Open VSX Registry

最小配置

对于大多数项目，你只需要两步：

1. 指定语言文件路径

// .vscode/settings.json
{
  "i18n-ally-next.localesPaths": ["src/locales"],
  "i18n-ally-next.sourceLanguage": "zh-CN"
}

2. 打开项目，开始使用

插件会自动检测你的 i18n 框架（Vue I18n、react-i18next 等），无需额外配置。

打开任意包含翻译键的文件，你会看到：

• 🏷️ 翻译键旁边出现内联注解，直接显示翻译值
• 🌐 悬停键名可查看所有语言的翻译
• ✏️ 点击即可编辑翻译
• 📊 侧边栏显示翻译进度和缺失项

从 i18n Ally 迁移

如果你正在使用原版 i18n Ally，迁移非常简单：

1. 卸载 i18n Ally
2. 安装 i18n Ally Next
3. 将 settings.json 中的 i18n-ally. 前缀替换为 i18n-ally-next.

所有配置项保持兼容，无需其他改动。

写在最后

国际化不应该是痛苦的。i18n Ally Next 的目标是让 i18n 成为开发流程中自然而然的一部分——写代码时看到翻译，提交前检查缺失，源文案变更时自动提醒，协作时有据可查。

我们不只是在做一个插件，更是在构建一套完整的 i18n 开发工具链：从文档到配置，从检测到提取，从翻译到审阅，每一个环节都有对应的解决方案。

如果你觉得这个项目有用，欢迎：

• ⭐ 在 GitHub 上给我们一个 Star
• 🐛 提交 Issue 反馈问题
• 💬 分享给你的团队和朋友
• 📖 阅读完整文档开始使用

---

本文同步发布于 i18n Ally Next 官方文档。