企业官网建设流程全解析

很多人把 i18n-ally 当成一个“可视化编辑多语言文件”的工具，装上之后扫一扫进度、补一补缺失翻译就完事了。但真正让这个插件产生质变的，是它右下角那个并不起眼的自动翻译能力——配合翻译服务的 API Key，它能把“手动翻译几百条文案”这种脏活直接变成“写代码时顺手点一下按钮”。这篇文章就来说清楚整条链路：怎么装插件、怎么理解它的文件识别机制、怎么从百度翻译开放平台拿到 key、在 VSCode 的 settings.json 里该配哪些字段，以及我实际使用中踩过哪些坑。

如果你正在维护一个前后端分离项目，或者手上有个多语言版本要同步更新，这篇文章能把你的 i18n 维护成本直接打下来一截。我默认你已经装了 VSCode 并且对 JSON 文件不陌生，接下来我们从 i18n-ally 到底是怎么工作的开始聊。

1. 从手动改 JSON 到一键翻译：i18n-ally 到底改变了什么工作流

1.1 国际化文件维护的原始痛点

写国际化的朋友应该都经历过这种场景：产品要新增一个功能模块，涉及二十几个文案，你需要在 zh-CN.json、en-US.json、ja-JP.json 这些文件里一个一个找位置、手动翻译、敲上对应的 key。光改文件本身不可怕，可怕的是各种隐性成本。

第一个成本是上下文断裂。你在组件里写死一个中文字符串，要把它搬到语言文件里，需要来回切换文件、确认当前 key 在嵌套结构中的路径。第二个成本是翻译质量不稳定。团队内如果大家各自翻译，同一个术语在不同页面可能有三种译法，比如“确认”有时翻成 Confirm、有时翻成 OK。第三个成本是漏项。某个新文案只加了中文文件，英文和日文没同步，等测试发现问题的时候，你已经不确定哪些地方漏了。

i18n-ally 最直接的价值，就是把“打开语言文件、手动找位置、手敲 key”这一段流程压缩成一次快捷键操作。你在源码里选中一个字符串，按一下，它自动把字符串提取到语言文件中、生成 key，并让所有语言文件都保持同步。自动翻译是它的下一层能力：提取之后直接用你配置的翻译服务把其他语言文件填充完毕。

1.2 按钮式翻译的底层原理：i18n-ally 如何识别语言文件

i18n-ally 之所以能做到“自动识别”，核心在于它对项目类型和文件路径有一套很聪明的探测逻辑。它会优先看 package.json 里的框架信息，Vue、React、Angular 都有对应的预设。然后它会扫描你的语言文件目录，找到形如src/lang/zh-CN.json、src/locales/en.json这类结构，读取文件内容并建立一份“key 到文案”的索引。

这个索引机制决定了它对文件命名非常敏感。我见过不少人配置不生效，原因就是语言文件名是zh_cn.json或者cn.json，而目录里又没有明确的locale标识，插件根本把它当成了普通 JSON 文件。换句话说，i18n-ally 不是靠单个文件名的语义去猜的，它是靠“目录 + 文件名 + 更多配置”共同确定的。

更关键的一点是，它把“主语言”和“翻译语言”分开了。你可以在设置里指定某个语言文件是主语言（通常是中文），其他语言文件都以此为基础进行翻译。自动翻译按钮触发的时候，插件会先读取主语言文件里所有待翻译的文案，调用翻译服务批量转换，然后写回对应的语言文件。这个流程看起来简单，但它背后的 key 对齐策略、嵌套结构合并策略，比大多数人想象的要复杂得多。

理解了这些，你也就明白了为什么配置百度翻译 key 只是最后一步——如果文件识别不对，就算 key 配好了，插件也不会对你现有的语言文件产生任何兴趣。

2. 准备百度翻译开放平台的密钥：注册、创建应用与额度核查

2.1 注册账号与创建应用的标准流程

进入百度翻译开放平台官网，先注册并登录。登录之后进入控制台，在“产品服务”里找到翻译服务，创建一个应用。创建应用的时候需要填应用名称、应用类型、所属分类，这些按实际情况填就行，不需要过多纠结。

创建完成后，你会拿到两个关键参数：APP ID和密钥（Secret Key）。这两个值是 i18n-ally 迈向自动翻译的“钥匙”。百度翻译 API 的调用方式是标准的 HTTP 签名请求，i18n-ally 已经在插件内部实现了完整的签名逻辑，所以你不需要自己写任何请求代码，只需要把这些值填到 VSCode 设置里。

有一点要提醒：保存密钥的地方很多，但别直接随手发到聊天群里。密钥代表你账户下的翻译调用额度，如果泄露，别人可以用它来刷你的免费额度，甚至产生费用。后面我会专门讲多人协作时如何安全共享这个 key。

2.2 免费额度与 QPS 限制：够不够用、怎么避免被拒

百度翻译开放平台提供“标准版”的免费额度，具体额度随时可能调整，但一般对于中小型项目是够用的。这里真正需要关注的是QPS 限制。翻译接口是按“每秒请求数”来限流的，如果你一次性提交上千条文案，插件会瞬间发起大量请求，很可能触发限流，返回类似 54003 的错误。

第一次用 i18n-ally 批量翻译的时候，我就遇到过一次限流。当时一个项目有 800 多条待翻译文案，我点了“翻译所有”，插件噼里啪啦地跑了一会，最后我看到有一批文案没有翻译成功，错误提示里明确写着“QPS 超限”。后来我改用小批量翻译，分批处理，情况就好了很多。

所以我的建议是：第一次对接时，先在单个文件里挑几条文案手动翻译，验证 key 能不能用；确认没问题之后，再放开手脚批量翻译。熟悉了插件内部的请求节奏之后，你就能比较自如地控制批量操作的大小，避免把额度浪费在无谓的重试上。

2.3 密钥安全与多人协作时的分发方式

个人开发时，密钥放在自己机器上没有任何问题。但团队协作时，你不可能让每个成员都去注册一个百度翻译账号。比较稳妥的做法是：用一个团队共用的账号创建应用，然后把 APP ID 和密钥写在一个只有后端同事能访问的内部文档里，前端同事在本地 .vscode/settings.json 中引用环境变量，避免把密钥直接提交到 Git 仓库。

需要注意，VSCode 的 settings.json 是支持引用环境变量的。比如你在本机.env文件里配置了BAIDU_TRANSLATE_APPID和BAIDU_TRANSLATE_KEY，然后在 settings.json 里写${env:BAIDU_TRANSLATE_APPID}，这样就不会把明文密钥写进任意的共享配置里。虽然 i18n-ally 的配置项不一定直接支持 env 变量，但你可以通过 VSCode 的“环境变量替换”机制做好大部分保护工作。

如果项目组里有人不需要翻译功能，只是看看进度、补一下缺失翻译，那其实可以不给他们分发 key，让他们用只读模式打开插件即可。这样可以最大限度地减少密钥暴露面。

3. 核心配置：settings.json 中每一项的真实含义

3.1 文件路径声明：为什么很多人配了不生效

i18n-ally 的配置入口在 VSCode 设置里，分“用户级”和“工作区级”。用户级配置文件里写"i18n-ally.localesPaths"可以让你所有项目都能识别语言目录，工作区级写在.vscode/settings.json可以针对当前项目单独声明。两者的作用是叠加的，但工作区级的优先级更高。

我见过最常见的配置失败原因，就是只写了localesPaths却没写sourceLanguage。插件默认会把它认定为英文，如果你的主语言是中文，它会把 zh-CN 当成次要语言，导致“翻译所有”的时候总是试着把英文翻译成中文，而不是从中文翻译成英文。你需要明确告诉插件：主语言是 zh-CN，剩下的都是需要翻译出来的语言。

另一个常见问题是目录结构。假如你的语言文件分散在src/views/a/lang和src/views/b/lang两个目录里，localesPaths需要同时把两个路径都加进去，而不能只写父目录然后指望它递归“识别”。插件对多语言目录的支持是有的，但你得把路径都列全。

3.2 翻译服务配置项：不要把 APP ID 和 Key 填反

设置项里与百度翻译直接相关的主要有这几个：i18n-ally.translate.baidu.appId、i18n-ally.translate.baidu.secret，以及i18n-ally.translate.service。如果你的翻译服务选择的是百度，service就填写对应的百度标识。

有一个细节特别容易踩坑：有些教程会把百度密钥直接写进secret字段，把 APP ID 写进appId字段，这本身没问题。麻烦的是，有些老版本插件或者修改过的配置模板里，appId和secret的键名是倒过来的，或者多了空格。填反了之后，翻译请求照样发出去，但百度返回错误码，提示“认证失败”。

我建议每个人填完之后，都先手动执行一次单条翻译来验证。如果看到“Invalid app id”之类的提示，基本就是字段填错或者值没对齐。

3.3 一套可以直接抄的推荐配置模板

下面是我目前在一个后台管理项目中实际使用的配置，你可以直接参考。注意.env部分根据需要调整路径：

{ "i18n-ally.localesPaths": [ "src/locales" ], "i18n-ally.sourceLanguage": "zh-CN", "i18n-ally.displayLanguage": "zh-CN", "i18n-ally.keystyle": "nested", "i18n-ally.defaultsLocale": "zh-CN", "i18n-ally.translate.service": "baidu", "i18n-ally.translate.baidu.appId": "你的APP ID", "i18n-ally.translate.baidu.secret": "你的密钥", "i18n-ally.translate.baidu.limit": 0, "i18n-ally.dirs.include": ["src/**/*.{vue,jsx,tsx,ts,js}"], "i18n-ally.enabledParsers": ["json", "yaml"], "i18n-ally.namespace": false }

逐项解释一下：keystyle是 key 的组织方式，nested 表示嵌套结构，对应 JSON 里的对象层级；displayLanguage决定插件界面用什么语言显示，不影响翻译行为；dirs.include是源码扫描范围，配合快捷键提取字符串使用；enabledParsers表示按 JSON 与 YAML 两种文件格式处理。

需要特别说明的是i18n-ally.translate.baidu.limit这个项，它不限制翻译条数，更多是控制一次请求的文本长度。百度翻译标准版对单次请求文本长度有限制，如果一条文案太长，你需要拆分。不过从我实际使用来看，普通 UI 文案很少会触发这个限制，所以这个配置项保持默认即可。

4. 自动翻译实操链路：从提取字符串到全语言文件生成

4.1 源码里选中字符串，一键提取并翻译

配置完成之后，实际操作非常简单。在 Vue 或 React 组件中，选中一个写死的中文，比如“保存成功”，按 i18n-ally 的提取快捷键（默认是Alt+Shift+I，也可以在右键菜单里选 i18n-ally: Extract text），插件会弹出一个输入框让你确认 key，确认之后它会：

1. 把字符串从源码移除，替换成$t('xxx.xxx')或t('xxx.xxx')这种函数调用；
2. 在 zh-CN.json 的对应位置写入这个 key 和中文原值；
3. 在 en-US.json、ja-JP.json 等文件里写入这个 key，值暂时为空或占位符。

到这里，自动翻译就可以介入了。第 3 步之后，插件界面里会标示出这些“待翻译”条目。你可以打开 i18n-ally 的可视化面板，看到一个“全部翻译”按钮，点下去，插件就会读取所有已提取但未翻译的文案，调百度翻译接口，把英文、日文等版本填好。

如果你只想翻译某一条，也可以在面板里单独选中那条，右键选择翻译当前键。这种方式好处是可控，适合那些包含术语、需要你多检查两遍的文案。

4.2 翻译失败时的高频报错与完整排查链路

我总结过自己遇到的几类翻译失败，基本都集中在以下场景里：

排查的时候不要一股脑只看报错文本。我建议先做一次“最小验证”：单独翻译一条短文案，比如“你好”。这一步会排除掉 80% 的配置问题。如果短文案可以翻译，长文案却失败，那基本就是 QPS 限流或者文本长度问题。如果短文案也失败，优先检查 APP ID 和密钥的字段顺序、大小写，以及百度平台有没有“开启”对应的服务。

有一次我排查了很久，最后发现是 VSCode 打开的是工作区设置，但团队成员给的是“用户设置”里的配置，两边配置没有同步，导致插件读到的是旧值。这里也提醒大家，工作区配置修改之后，最好重启一下 VSCode 或者重载窗口，让插件重新读取配置。

4.3 术语一致性：机器翻译结果需要二次把关

百度翻译能解决大部分常规文案，但涉及产品专有名词的时候，机器翻译经常不够理想。比如你们的产品内部叫“客户工作台”，如果直接翻译成 Customer Workbench，可能没问题；但如果正式英文文档里已经统一成了 Client Portal，那翻译结果就需要人工覆盖。

我的习惯是：自动翻译完成之后，留一个“人工审查清单”。这个清单可以维护在一个共享文档里，记录所有出现过偏差的术语，以及应该使用的标准翻译。比如：

• “创建”——Create
• “删除”——Delete
• “复制成功”——Copied successfully
• “客户工作台”——Client Portal

当团队里有人发现某条文案翻译不准确时，直接改语言文件，同时把正确写法补进术语清单。这样坚持两三个迭代之后，机器翻译结果的准确性会高很多，因为待翻译文本中大量重复出现的高频词已经被你记录过了，不会反复踩同一个坑。

5. 进阶玩法：多人协作、扫描遗漏与翻译质量闭环

5.1 让 i18n-ally 参与团队协作：进度面板与缺失检测

i18n-ally 的侧边栏面板不只是翻译入口，它还是一个实时的国际化进度大盘。它能展示每种语言文件的完成百分比、缺失 key 的数量、以及哪些文件中存在多余 key。在多人协作中，这个面板非常有用：你不用去 git diff 里翻代码，一眼就能看出英文版本落后了多少。

我们团队现在约定，每次提测之前，负责人会截图 i18n-ally 的概览面板，确保所有语言文件完成度都到 100%。如果某个语言文件长时间停留在 90% 以下，后台会收到通知，相关同事需要处理对应文件里的未翻译文案。这个“完成度检查”已经写进了团队的发布检查清单里，比人工一个个文件打开去翻高效得多。

另一个功能是“提取全部引用”。你可以直接在项目根目录运行 i18n-ally 的扫描命令，让插件自动找出所有源码中写死了字符串但没有走国际化函数的位置。配上dirs.include限制扫描范围，它能在几分钟内把整个项目的国际化遗漏点捞上来。虽然是补丁式的做法，但对于历史代码存量大的项目来说，这是最快速的“体检”方式。

5.2 机器翻译结果入库前的校验机制

自动翻译很方便，但我会建议在流程上加一道“入库前校验”。具体做法是：当翻译软件写回语言文件之后，先不要直接提交到 Git，而是在编辑器里检查几类明显问题。第一类是漏翻的 key，值还是空字符串；第二类是翻译结果与上下文明显不符，比如把“运行”翻译成了“执行”，虽然语义差不多，但产品里用的可能是 Run 而不是 Execute；第三类是 HTML 标签或占位符被翻译器错误修改，比如{name}被翻译成别的格式，或者</div>被改写，这类问题在自动翻译里偶尔会出现，人工检查一眼就能发现。

更稳妥的做法是给项目安装一个基础的国际化 linter，配合 i18n-ally 一起做检查。linter 负责静态语法层面的校验（比如是否存在重复 key、是否缺少引号），i18n-ally 负责语义层面的翻译与补全。两者配合起来，语言文件的健康程度会好很多。

5.3 我把哪些文案排除在自动翻译之外

机器翻译解决“有没有”的问题，但“信达雅”还是得靠人。以下三类文案，我会明确把它们从自动翻译范围里踢出去，宁可手动处理：

第一类是语气词和口语化文案。比如“哎呀，这网不太行”，这种句子机器翻译出来会有一种微妙的“翻译腔”，看着让人出戏，不如人工写一个本地化的表达。

第二类是带变量和复数形式的文案。很多框架的复数形式不是简单拼接，而是需要根据数字动态变化。机器翻译不会帮你在 en-US 里正确配置 plural 规则，所以这类文案最好在语言文件里手动调整结构，而不是依赖自动翻译。

第三类是长段落或帮助文档正文。i18n-ally 针对的是那种一句话、一个短语的 UI 文案。如果你把一个完整的帮助文档丢给它，单次请求长度很容易超限，翻译结果也可能因为上下文过长而质量下降。长文本更适合专门的文档翻译流程，而不是塞进 UI 语言文件里。

我把这三类内容单独放到一个manual.json里，或者在语言文件里加了// i18n-translate: manual标记，让自动翻译不触碰这些条目。这样既保留了自动翻译的高效率，又守住了输出质量的下限。

6. 我的实际体会：让自动翻译真正帮你省力的两个判断

自动翻译适合的场景，是你已经有一套稳定的文件结构，同时文案的格式比较统一。它最擅长的是“批量填充”和“格式化补全”，而不是“创造一条翻译风格规范”。我刚接入百度 key 那两天，最大的感受是省心——过去半小时手敲十来个 key 的英文翻译，现在从源码提取到自动翻译完成，几分钟就能把整个模块的文案同步到所有语言文件里。

但我也得诚实说，自动翻译并不能消灭人工参与。它消灭的是“重复劳动”，但把人的精力留给了更有价值的“术语决策”和“风格统一”。如果你的项目还在频繁改 key 结构、语言文件位置三天两头调整，先用好它的手动提取功能就足够了，不急着上自动翻译。一边用一边观察，等文件结构稳定了，翻译质量有迭代机制了，再把自动翻译全面铺开——那时候你才能体会到，它真正帮你省下的不只是时间，还有每次发布前检查多语言文件的那种烦躁感。