1. 为什么 i18n 批量翻译总是卡在“最后一公里”做过前端国际化的同学大概率都有类似体验产品要出海PM 丢过来一份文案表200 个中文 Key要翻成英、日、韩、法、德五种语言。第一反应是“调个翻译接口不就完了”结果真正动手才发现翻译本身可能只占 10% 的时间剩下 90% 全耗在文件管理、变量保护、Key 同步和静默失败排查上。我试过最典型的一个坑{name}这种插值变量被翻译引擎当成普通文本英文里变成{nombre}运行时插值直接断裂页面显示一片空白但控制台不报错。还有settings.title这种 typo因为缺少 Key 不会抛运行时异常直到非英语用户在 production 环境反馈才发现往往已经过去几周。这篇要解决的就是这个场景前端项目多语言文件批量翻译。核心思路是用 MCP Google Translate 把“扫描 → 去重 → 批量翻译 → 生成 locale 文件 → 校验”串成一条可复制的自动化流水线同时用 TaoToken 统一 Key 和 API 通道避免在多个翻译服务之间来回切换配置。适合正在做 i18n、被多语言文件同步折磨的前端和全栈开发者跟着做能跑通一次完整的批量翻译验证。2. TaoToken 前置统一 Key 与 API 通道在配置 MCP 之前先把“通道”这件事理清楚。MCP Google Translate 这类工具本质上还是要调用翻译模型或翻译 API如果每个工具都单独配一套 Key配置文件会迅速失控。TaoToken 在这里扮演的角色是统一入口一个 Key 覆盖模型对话、编码 Agent、翻译调用等场景MCP 配置里只需要引用同一个环境变量。你需要先拿到两样东西一个可用的 API Key在控制台的 API Keys 页面创建确认接入文档里的 base URL 和鉴权方式MCP 的config.toml里会用到。具体入口注册与总览https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite注意Key 不要硬编码进config.toml后提交到仓库。用环境变量注入CI 里用 secrets本地用.env并加进.gitignore。如果你后续要做长期编码或 Agent 工作流可以了解 Coding Plan只是验证模型连通性用模型对话页面就够。翻译批量任务属于接入类场景重点看 API Keys 和接入文档。3. 可复制配置config.toml 骨架与 MCP 接入下面给一份可以直接改的config.toml骨架。不同 MCP 客户端的字段名略有差异但结构一致一个[mcp_servers.xxx]段落对应一个 MCP Servercommandargs启动env注入 Key。# ~/.config/mcp/config.toml # 统一从环境变量读取避免明文写 Key [mcp_servers.i18n_magic] command npx args [-y, scoutello/i18n-magic, mcp] env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} } [mcp_servers.google_translate] command npx args [ -y, mcp-remote, https://mcp.apify.com/?toolsthescrappa/google-translate-scraper, --header, Authorization: Bearer ${APIFY_TOKEN} ] env { APIFY_TOKEN ${APIFY_TOKEN} } # 如果走 TaoToken 统一通道做翻译模型调用 [mcp_servers.taotoken_translate] command npx args [-y, modelcontextprotocol/server-fetch] env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL https://taotoken.net/api }几个关键点说明i18n_magic负责扫描代码、提取 Key、生成 locale 文件google_translate负责真正的批量翻译taotoken_translate是可选层当你想用统一通道调用翻译模型时挂上。${VAR}这种写法依赖客户端支持环境变量展开如果不支持就在启动脚本里export后再启动客户端。对应的.env不要提交TAOTOKEN_API_KEYsk-你的key APIFY_TOKEN你的apify_token项目侧的 i18n 配置建议单独放一个文件方便 CI 复用{ sourceLocale: zh-CN, targetLocales: [en, ja, ko, fr, de], localesDir: ./src/locales, extract: { include: [src/**/*.{ts,tsx,vue}], ignore: [**/*.test.*, **/node_modules/**] }, protectPatterns: [\\{[a-zA-Z0-9_]\\}, \\$t\\([^)]\\)] }protectPatterns是变量保护的底线{name}、$t(...)这类占位符在翻译前后必须完全一致任何翻译引擎都不能改动它们。4. 验证请求跑通一次批量 i18n 翻译配置完成后先做一次最小验证确认 MCP 通道是通的再上批量。第一步扫描待翻译字符串npx scoutello/i18n-magic scan --config ./i18n.config.json预期输出会列出所有硬编码文案和缺失的 Key类似[scan] found 213 strings in 47 files [scan] missing keys: 213 [scan] duplicate candidates: 18第二步执行批量翻译到五种目标语言npx scoutello/i18n-magic sync \ --config ./i18n.config.json \ --targets en,ja,ko,fr,de \ --engine mcp-google-translate这一步会调用 MCP Google Translate把去重后的文案批量提交。实测下来200 个 Key、5 种语言翻译请求本身在几分钟内完成主要耗时在首次扫描和文件写入。第三步检查生成的 locale 文件结构ls src/locales # en.json ja.json ko.json fr.json de.json zh-CN.json打开en.json抽查变量保护{ welcome: Welcome, {name}, settings: { title: Settings } }确认{name}没有被翻译成{nombre}或{名前}。如果发现变量被改动回到protectPatterns补充规则重新跑 sync。第四步CI 校验确保没有缺失 Keynpx scoutello/i18n-magic check-missing --config ./i18n.config.json echo $? # 0 表示无缺失非 0 表示有 Key 未翻译把这条命令放进 GitHub Actionsname: i18n Check on: pull_request: branches: [main] jobs: i18n: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx scoutello/i18n-magic check-missing --config ./i18n.config.json env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }}这样每次 PR 都会自动检查多语言文件是否同步把“静默失败”挡在合并之前。5. 本篇常见错排查报错一MCP server google_translate failed to start先确认npx能正常拉包再检查APIFY_TOKEN是否注入成功。常见原因是config.toml里写了${APIFY_TOKEN}但客户端不支持展开实际传了字面量。解决方式是在启动客户端前export APIFY_TOKENxxx或者改用客户端支持的 env 字段直接赋值。报错二翻译结果里变量被破坏比如{count} items变成{数量} items。这是protectPatterns没覆盖到。检查你的插值语法Vue 的{{ }}、React 的{ }、i18next 的{{name}}都要分别加规则。加完后重新 sync不要手动改生成的文件否则下次同步会被覆盖。报错三check-missing退出码一直是 1说明有 Key 在源语言存在但目标语言缺失。先跑scan看是哪些 Key再跑sync补齐。如果某个 Key 是故意不翻译的比如品牌名在配置里加ignoreKeys白名单避免 CI 一直红。报错四翻译请求超时或限流批量任务一次提交太多条目容易触发限流。把sync的批次调小比如--batch-size 50或者加--retry 3。如果走 TaoToken 统一通道确认 base URL 是https://taotoken.net/api不要带多余路径。报错五生成的 locale 文件顺序每次都不一样这会导致 git diff 噪音很大。在配置里开启sortKeys: true让 Key 按字母序输出diff 就干净了。6. 把翻译接进你的日常工作流跑通一次之后真正有价值的是把它变成习惯。我的做法是新增文案时先在源语言文件里写 Key提交 PRCI 自动跑check-missing缺翻译就红合并前用sync补齐目标语言再提交一次。整个过程不需要手动复制 JSON也不需要逐个调用翻译接口。如果你还在用“复制一份 JSON、改改字段、手动替换”的老办法建议先从scancheck-missing这两条命令开始哪怕不接自动翻译也能把“漏 Key”这类问题挡在合并之前。等流程顺了再挂上 MCP Google Translate 做批量翻译最后用 TaoToken 统一 Key 管理把模型对话、编码 Agent、翻译调用收敛到一个通道里。需要动手的话从 API Keys 页面拿 Key对照接入文档配好config.toml然后跑一遍上面的scan和sync。翻译是容易的工作流才是难的而 MCP 正在让这个“难的部分”变得可复制。
