跳转到主要内容

代理指南：使用 champollion

champollion 是一个 CLI 工具，可以通过一条命令翻译你的应用的语言环境文件。本指南适用于 AI 代理（或与 AI 代理合作的开发者），帮助你快速从零开始获得翻译后的语言环境文件。

:::tip 已经熟悉了？ 如果你只需要命令，请跳转到 CLI 参考。如果你想构建和基准测试翻译方法，请参阅 Arena 代理指南。 :::

环境设置​

# No global install needed — npx runs it directly
npx champollion sync

要求：

  • Node.js 18+
  • 你的翻译提供商的 API 密钥

API 密钥设置 — champollion 需要至少一个密钥，具体取决于你使用的方法：

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."        # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..."    # for google-translate method

# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Champollion 自动读取 .env。在 openrouter.ai/keys 获取 OpenRouter 密钥。

首次同步​

Champollion 自动检测你的语言环境文件、其格式（JSON、TOML、YAML、PO）和目标语言：

npx champollion sync

发生的过程：

  1. 加载 champollion.config.json（或自动检测设置）
  2. 扫描你的源语言环境文件，展平嵌套键
  3. 与 .champollion.lock 比较（先前翻译值的 SHA-256 哈希）
  4. 检查 .champollion/tm.json 中的缓存翻译（翻译记忆库）
  5. 通过配置的方法翻译已更改、缺失或过期的键
  6. 对每个翻译运行质量门（5 项检查）
  7. 将通过的翻译写入目标语言环境文件
  8. 更新锁定文件和 TM 缓存

在更改一个键后的典型重新运行中，第 4 步从缓存提供 142 个键，第 5 步翻译 1 个键。这就是为什么后续同步速度快且成本低。

配置​

在项目根目录创建 champollion.config.json：

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

关键字段：

字段用途默认值
inputLocale源语言en
pairs源→目标映射及方法配置（必需）
localesDir语言环境文件所在位置（自动检测）
modelllm/llm-coached 方法的 LLM 模型google/gemini-2.5-flash
batchSize每个 API 调用的键数80（LLM）、128（Google）
jsonConcurrencyJSON 键的并行语言环境翻译200
contentConcurrency内容翻译的并行 API 调用48

完整参考：配置

翻译方法​

方法何时使用成本需要 API 密钥
llm通用，适合资源充足的语言按令牌计费（取决于模型）OPENROUTER_API_KEY
llm-coached当你有目标语言的语法规则/词典时按令牌 + 指导上下文OPENROUTER_API_KEY
google-translate高资源语言，其中 GT 效果良好$20/百万字符GOOGLE_TRANSLATE_API_KEY
api托管在 HTTP 端点后的自定义管道服务器决定无（端点处理身份验证）
plugin本地安装的预打包方法各不相同各不相同

详情：翻译方法

指导数据​

对于 llm-coached 对，指导数据用显式语言知识引导 LLM。创建一个指导文件：

coaching/fr.json
{
  "grammar_rules": [
    "Use formal register (vous) for all UI text",
    "Adjectives agree in gender and number with the noun"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms."
}

在你的对配置中引用它：

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

质量门验证字典术语是否实际出现在输出中 — 违规被记录为 [TERM] 警告。

详情：指导数据

质量门​

每个翻译在写入磁盘前都要通过五项自动检查：

检查捕获内容示例
空白/空值模型返回空值""
源回显模型返回未更改的英文输入"Welcome" 用于日语
幻觉循环重复的三字组"Qo' Qo' Qo' Qo'"
长度膨胀输出长度是源的 4 倍以上10 字符源 → 50 字符输出
脚本合规性语言环境的脚本错误阿拉伯语言环境的拉丁文本

失败被记录为 [GATE] 前缀。没有静默回退 — 如果翻译失败，它会被报告，而不是被悄悄接受。

详情：质量门

翻译记忆库​

Champollion 在 .champollion/tm.json 中缓存翻译，键为源文本 + 语言环境 + 方法。在后续同步中，未更改的键从缓存提供 — 无 API 调用，无成本。

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

要在一次运行中绕过缓存：npx champollion sync --no-tm

详情：翻译记忆库

生成的文件​

Champollion 在你的项目中创建多个文件。了解它们是什么，这样你就不会意外删除或提交错误的文件：

文件用途Git？
.champollion.lock翻译源值的 SHA-256 哈希（变更检测）是 — 提交此文件
.champollion-content.lock相同，但用于 Markdown/MDX 内容文件是 — 提交此文件
.champollion/tm.json翻译记忆库缓存是 — 提交此文件（为团队节省 API 成本）
.champollion/coaching/指导数据目录是 — 这是你的语言知识
champollion.config.json项目配置是 — 提交此文件

常见模式​

翻译一个语言对：

npx champollion sync --pair en-fr

翻译所有配置的对：

npx champollion sync

Champollion 并行翻译所有语言环境。使用 TM 缓存，只有更改的键会调用 API。

内容模式（Docusaurus、Hugo 等的 Markdown/MDX）：

npx champollion sync --content

翻译文档、博客文章和内容文件以及语言环境 JSON。使用并行并发（默认：48 个并发 API 调用）。使用 --content-concurrency 调整。

干运行（预览而不写入）：

npx champollion sync --dry-run

强制重新翻译特定键：

npx champollion sync --force-keys "hero.title,nav.about"

强制重新翻译所有内容文件：

npx champollion sync --force-content

检查翻译状态：

npx champollion status

显示每个对的覆盖率、质量层级和插件信息。

审计未翻译的回退：

npx champollion audit

列出所有需要翻译的 [EN] 回退值。

故障排除​

问题解决方案
OPENROUTER_API_KEY not set导出密钥或将其添加到项目根目录的 .env
No locale files found在配置中设置 localesDir，或确保你的语言环境文件匹配标准命名（en.json、fr.json）
[GATE] Script compliance failed你的目标语言环境获得了拉丁文本而不是预期的脚本 — 尝试不同的模型或添加指导数据
[GATE] Source echo模型返回了未更改的英文 — 指导数据或不同的模型通常可以解决此问题
所有翻译都已缓存使用 --no-tm 运行以绕过缓存，或 --force-keys 用于特定键
锁定文件冲突.champollion.lock 使用 SHA-256 哈希 — 合并冲突可以安全地通过保留任一版本来解决，然后重新运行同步

接下来​