企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite
• 控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite

注意：Key 不要硬编码进config.toml后提交到仓库。用环境变量注入，CI 里用 secrets，本地用.env并加进.gitignore。

如果你后续要做长期编码或 Agent 工作流，可以了解 Coding Plan；只是验证模型连通性，用模型对话页面就够。翻译批量任务属于接入类场景，重点看 API Keys 和接入文档。

3. 可复制配置：config.toml 骨架与 MCP 接入

下面给一份可以直接改的config.toml骨架。不同 MCP 客户端的字段名略有差异，但结构一致：一个[mcp_servers.xxx]段落对应一个 MCP Server，command+args启动，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/?tools=thescrappa/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_KEY=sk-你的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 校验，确保没有缺失 Key：

npx @scoutello/i18n-magic check-missing --config ./i18n.config.json echo $? # 0 表示无缺失，非 0 表示有 Key 未翻译

把这条命令放进 GitHub Actions：

name: i18n Check on: pull_request: branches: [main] jobs: i18n: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 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_TOKEN=xxx，或者改用客户端支持的 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，提交 PR，CI 自动跑check-missing，缺翻译就红；合并前用sync补齐目标语言，再提交一次。整个过程不需要手动复制 JSON，也不需要逐个调用翻译接口。

如果你还在用“复制一份 JSON、改改字段、手动替换”的老办法，建议先从scan+check-missing这两条命令开始，哪怕不接自动翻译，也能把“漏 Key”这类问题挡在合并之前。等流程顺了，再挂上 MCP Google Translate 做批量翻译，最后用 TaoToken 统一 Key 管理，把模型对话、编码 Agent、翻译调用收敛到一个通道里。

需要动手的话，从 API Keys 页面拿 Key，对照接入文档配好config.toml，然后跑一遍上面的scan和sync。翻译是容易的，工作流才是难的，而 MCP 正在让这个“难的部分”变得可复制。