AI Agent 接入

ai-i18n 为 Cursor、Codex、Claude Code 和 Antigravity 提供 Agent Skill 与 MCP 服务器。 AI 编码工具可在明确指令下扫描、补齐和校对译文，无需先运行完整构建。 Agent 插件仅支持 Codex，不支持 Cursor、Claude Code 或 Antigravity；其他工具使用独立 Skill 与 MCP。

如果你希望在开发或构建期间自动补齐缺失译文，请改用 AI 翻译配置 OpenAI-compatible Provider。

适用场景

Agent 模式适合以下场景：

批量补齐缺失译文；
在代码审查或迭代时按需校对；
希望由 AI 工具在受控范围内写入项目 translations/ 和 overrides/ 分桶。

使用方式

在目标 Vite 应用完成 ai-i18n 接入后，Codex 用户可安装插件，一次加载以下 Skill、MCP 和任务结束检查；其他工具单独安装 Skill：

integrate-ai-i18n：检查接入、配置和生成文件。
use-ai-i18n-mcp：扫描文案、补译和人工校对。

然后直接向 Agent 发送任务，例如：

使用 use-ai-i18n-mcp 补齐当前 Vite 应用缺失的英文翻译。不要覆盖已有译文；需要人工确认时，请先列出建议措辞。

Agent 会区分自动译文与人工校对结果，并在修改前列出建议措辞。

如果应用的 Vite 启动命令使用 --configLoader runner 等加载器选项，请让 Agent 沿用该设置。扫描会执行应用的开发插件；插件生成声明文件、编辑器文件更新或无关文件内容变化不会单独阻止文案清单刷新。实际依赖无法读取、扫描期间源码或配置变化时仍会报错；新增或删除候选文件时，等待文件变化结束后重试。无关坏链接可能使扫描无法复用缓存，但不应阻止提取可达源码。独立扫描助手会在结果输出后退出，避免代码定位等开发插件的后台监听使任务一直等待。

安装 Codex 插件

使用支持插件命令的 Codex CLI，在终端执行：

codex plugin marketplace add bosens-China/ai-i18n --ref plugin-marketplace
codex plugin add ai-i18n@ai-i18n

这会从仓库的插件市场分支安装完整插件，无需克隆源码或运行打包命令。按 Codex 提示启用插件并信任任务结束检查，然后开始新任务，确认两份 Skill 与 MCP 可用。若以前单独安装过相同 Skill 或注册过同名 MCP，请保留一份有效配置，避免重复加载。插件不会升级业务应用里的 npm 依赖。

在 Monorepo 中，请从目标应用目录启动 Codex；如果需要从仓库根目录启动，先设置 AI_I18N_APP_ROOT 为目标应用的绝对路径。需要非默认 Vite 配置或运行模式时，可同时设置 AI_I18N_CONFIG、AI_I18N_MODE。应用指定配置加载器时，通过 AI_I18N_CONFIG_LOADER 沿用 bundle、runner 或 native；不设置时保留 Vite 默认值。插件不会自动选择子应用。

任务正常结束时，插件检查当前应用的缺译，并最多让 Agent 自动继续一次。 Agent 只按当前任务授权补译；检查失败会报告，不会被当成零缺译。未启用结束检查时，仍可主动要求 Agent 使用 Skill 扫描和补译。

更新插件

codex plugin marketplace upgrade ai-i18n
codex plugin add ai-i18n@ai-i18n

更新后开始新任务；如 Codex 提示结束检查有变化，重新确认信任。 Skill 和脚本随插件更新，业务应用的 npm 依赖需要单独管理。

与 AI 翻译 Provider 的区别

方式	运行时机	适用场景
AI 翻译（Provider）	Vite 开发服务器/构建	开发或 CI 期间自动补齐
AI Agent + MCP	与编码工具交互时	受控批量补译、校对和审查

两种方式的译文都写入项目 translations/ 和 overrides/ 分桶。它们遵循相同的 Git 提交规则。

如果应用启用了个人 SQLite 翻译记忆，Agent 还可以通过 MCP 显式查询某条文案的候选译文。候选只用于参考，不会自动写入项目；需要使用时再让 Agent 选择并正常补译。候选显示来源项目和自动/人工类型，支持继续加载。同一文案存在不同译法时，请结合上下文决定。也可以在审查工作台填入候选并确认保存；查询不检查来源项目是否仍在电脑上。如果翻译目录设在应用目录之外，请同时告诉 Agent 目标 Vite 应用的目录，以便它找到该应用安装的 SQLite 包。

独立使用 Skill 与 MCP

Cursor、Claude Code 和 Antigravity 不需要 Codex 插件，也可以独立使用 ai-i18n。 Codex 用户如果不需要任务结束检查，也可以采用相同方式，只安装 Skill 并按需注册 MCP。

安装 Skill

在项目根目录运行：

npx skills add bosens-China/ai-i18n --skill use-ai-i18n-mcp integrate-ai-i18n -y

安装前请按版本选择与升级确认服务包发布状态。

普通补译只需要 Skill。请使用项目现有的包管理器，将 @ai-i18n/mcp@^1.0.0 安装为目标 Vite 应用的开发依赖。Agent 会在进程内复用 MCP 的读写能力，无需在编码工具中注册服务器。

如果需要人工覆盖、清空译文，或在构建前审查并选择性清理孤立译文，再按下文注册 MCP 服务器。普通 Build 默认清理孤立自动译文；先审查时请设置 cleanup.orphanMessages: false。

注册 MCP 服务器

MCP 使用本地 STDIO 连接。不同 Agent 使用相同的启动命令：

npx -y @ai-i18n/mcp@^1.0.0

请按所用 Agent 选择一种配置方式。已有同名服务器时保留一份有效配置，避免重复启动。

Codex

codex mcp add ai-i18n -- npx -y @ai-i18n/mcp@^1.0.0

也可以在 ~/.codex/config.toml 或项目的 .codex/config.toml 中加入：

[mcp_servers.ai_i18n]
command = "npx"
args = ["-y", "@ai-i18n/mcp@^1.0.0"]

Cursor

在项目的 .cursor/mcp.json 或全局 ~/.cursor/mcp.json 中加入：

{
  "mcpServers": {
    "ai-i18n": {
      "command": "npx",
      "args": ["-y", "@ai-i18n/mcp@^1.0.0"]
    }
  }
}

Claude Code

claude mcp add --transport stdio --scope local ai-i18n -- npx -y @ai-i18n/mcp@^1.0.0

Antigravity

在项目的 .agents/mcp_config.json 中加入以下内容。若希望所有项目共用，可改为全局 ~/.gemini/config/mcp_config.json：

{
  "mcpServers": {
    "ai-i18n": {
      "command": "npx",
      "args": ["-y", "@ai-i18n/mcp@^1.0.0"]
    }
  }
}

在 Antigravity IDE 中，也可以从 Agent 面板的 MCP Servers → Manage MCP Servers → View raw config 打开同一份配置。ai-i18n 尚未收录在 Antigravity MCP Store，需要添加自定义服务器。

配置完成后，重新启动 Agent 或当前任务，再发送前文示例中的补译指令。

生成文件与提交规则见生成文件与 Git，人工译文优先级见补齐和确认译文。

AI Agent 接入#

#适用场景

#使用方式

#安装 Codex 插件

#更新插件

#与 AI 翻译 Provider 的区别

#独立使用 Skill 与 MCP

#安装 Skill

#注册 MCP 服务器

#Codex

#Cursor

#Claude Code

#Antigravity