AI 翻译

ai-i18n 提供两种补译方式：

方式	适用场景
OpenAI Provider	希望在 Vite 开发或构建时自动补齐缺失译文。
Agent + MCP	希望由 AI 编码工具在明确指令下检查、补译和审校。

本页介绍 OpenAI-compatible Provider。未配置 Provider 时，ai-i18n 仍会提取文案和生成语言包；缺失译文会显示源码文案。

安装

npm

yarn

pnpm

bun

deno

npm add @ai-i18n/openai@alpha

Alpha 阶段

预发布期间请显式安装 @alpha。npm 的 latest 标签不代表当前推荐的 alpha 版本。

最小配置

Provider 在 Vite 的 Node.js 进程中运行。将密钥保留在服务端配置中，不要使用 VITE_ 前缀，也不要在浏览器业务代码中导入 Provider。

// vite.config.ts
import { openAI } from '@ai-i18n/openai';
import { aiI18n } from '@ai-i18n/vite';
import { defineConfig, loadEnv } from 'vite';

function required(value: string | undefined, name: string): string {
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'AI_');

  return {
    plugins: [
      aiI18n({
        sourceLang: 'zh-CN',
        locales: [
          { value: 'zh-CN', label: '中文' },
          { value: 'en-US', label: 'English' },
        ],
        provider: {
          translator: openAI({
            baseURL: required(env.AI_BASE_URL, 'AI_BASE_URL'),
            model: required(env.AI_MODEL, 'AI_MODEL'),
            apiKey: env.AI_API_KEY,
            systemPrompt: `
你负责翻译面向开发者的 Web 产品界面。
- 使用自然、简洁的目标语言，按钮优先使用动词。
- 保留 ai-i18n、Vite、Vue、React、代码、URL、变量名和占位符。
- 结合 comment 判断文案语境。
            `.trim(),
          }),
        },
      }),
    ],
  };
});

.env.local 示例：

AI_BASE_URL=https://example.com/v1
AI_MODEL=model-name
AI_API_KEY=replace-me

本地无认证模型可以省略 AI_API_KEY。

审查模型日志

日志默认关闭。设置 provider.logging: true 后，OpenAI Provider 在 Vite 项目根目录的 logs/ 生成普通文本日志。日志用 batchId 串联模型输入、模型输出、校验、Vite 状态应用与持久化结果；并发批次不会串号。

provider.logging 也可直接设置为相对 Vite root 或绝对路径的目录字符串。

如何开关、逐块阅读、定位失败、交给 AI Agent 分析，以及 Git 忽略和安全边界，见 LLM 日志与排障。

编写翻译提示词

提示词只需说明产品语境、语气和固定术语。推荐使用短规则：

说明产品面向谁，例如开发者工具、消费应用或后台系统；
规定按钮、错误提示和帮助文案的语言风格；
列出必须保持不变的品牌名、代码、URL 和占位符；
列出团队已确认的术语；
要求优先参考 comment 消除歧义。

不要在提示词中放入 API 密钥、内部地址或会频繁变化的业务信息。文案本身的具体语境应写在 t(source, { comment }) 中。

验证结果与失败处理

Provider 只补齐缺失译文。翻译失败时，页面继续显示源码文案，不会阻塞本地开发。提交前运行一次完整 Build，并检查关键页面和固定术语。

需要让 CI 在翻译请求失败或仍有缺失译文时停止构建，可以设置 provider.strict: true。批次大小、并发、日志和刷新策略见 AiI18nProviderOptions。重试与超时由具体 Translator 或 Provider SDK 配置；OpenAI-compatible Provider 的字段见 OpenAIOptions。

Provider 的模型、baseURL、温度或提示词变化时，插件默认继续复用历史自动译文，不会尝试分析 Translator 内部配置。需要让新配置刷新一次时，使用 provider.cache: 'fresh'；本进程生成的新结果仍会立即缓存，因此 Dev/HMR 不会重复请求。该选项只影响 Provider，不影响 MCP 或 AI Agent。完整配置见 Translation Memory。

使用其他模型服务

只要服务兼容 OpenAI API，就可以修改 baseURL 和 model 使用它。若需要接入其他 SDK，请实现 Translator。该 API 说明了输入、输出和错误处理约束。

人工确认译文、处理同一句话的不同语境，以及提交规则见补译与审校。

AI 翻译#

#安装

#最小配置

#审查模型日志

#编写翻译提示词

#验证结果与失败处理

#使用其他模型服务