配置

Champollion 零配置工作——它会自动检测项目中的语言文件、格式和目标语言。如需更多控制，请在项目根目录创建 champollion.config.json，或运行：

npx champollion init

完整配置参考

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note typegen 尚未实现 typegen 配置块已被配置加载器识别并保留，但 TypeScript 类型生成尚未实现。这是计划功能的占位符。设置这些值无效。 :::

字段

字段	类型	默认值	描述
`version`	`number`	`3`	配置架构版本。始终为 `3`。
`inputLocale`	`string`	`"en"`	源语言代码（BCP 47）。
`localesDir`	`string`	`"./locales"`	语言文件路径。Champollion 扫描此目录。
`contentDir`	`string`	`null`	Hugo 内容目录。启用 Markdown 正文翻译。
`translatableFields`	`string[]`	`null`	覆盖内容翻译的默认可翻译前置元数据字段。`null` 使用内置默认值（`title`、`description`、`summary`）。
`format`	`string`	`"auto"`	文件格式：`json`、`toml`、`yaml` 或 `auto`（从扩展名检测）。
`model`	`string`	`"google/gemini-3.5-flash"`	LLM 方法的默认模型。接受完整的 OpenRouter slug（`provider/model`）或 `shared/model-aliases.json` 中的短别名（例如 `gemini-flash`）。直接提供商使用裸名称（例如 `gpt-4o`）。
`temperature`	`number`	`0.3`	LLM 温度（0.0–2.0）。较低 = 更具确定性。
`defaultMethod`	`string`	`"llm"`	默认翻译方法：`llm`、`llm-coached`、`google-translate`、`deepl`、`microsoft-translator`、`libretranslate`、`openai`、`anthropic`、`gemini`、`api`。被 `--method` CLI 标志覆盖。
`batchSize`	`number`	`80`	每个翻译批次的键数。更高 = 更少的 API 调用，但更大的提示。
`coachingFile`	`string`	`null`	自由文本指导提示文件的路径（相对于项目根目录）。内容在启动时读取并作为 `Coaching guidance:` 块注入系统提示。
`promptContext`	`string`	`null`	注入系统提示的应用程序上下文字符串（例如"电子商务产品描述"）。帮助模型针对您的领域定制翻译。
`jsonConcurrency`	`number`	`200`	JSON 键同步的最大并行语言翻译数。被 `--json-concurrency` CLI 标志覆盖。
`contentConcurrency`	`number`	`48`	内容（Markdown/MDX）翻译的最大并行 API 调用数。被 `--content-concurrency` CLI 标志覆盖。
`fallbackPrefix`	`string`	`"[EN] "`	`audit` 和 `verify` 使用的标记前缀，用于检测来自先前运行的旧版未翻译值。Champollion 不写入此前缀——它仅读取以进行检测。
`apiKeyEnvVar`	`string`	`"OPENROUTER_API_KEY"`	API 密钥的环境变量名称。覆盖自定义环境变量名称。
`baseUrl`	`string`	`""`	SEO 工件生成的基础 URL（hreflang、站点地图、JSON-LD）。
`pairs`	`object`	`{}`	按对的方法、模型和质量覆盖。参见对配置。
`languages`	`object`	`{}`	按语言覆盖。参见语言配置。
`lint.srcDir`	`string`	`null`	lint 扫描的源目录。`null` = 从框架自动检测。
`lint.ignore`	`string[]`	`["node_modules", ...]`	从 lint 中排除的 glob 模式。
`lint.minLength`	`number`	`2`	标记为硬编码的最小字符串长度。
`seo.urlPattern`	`string`	`"/:locale/:path"`	hreflang 标签生成的 URL 模式模板。
`seo.pages`	`string[]`	`null`	SEO 的显式页面列表。`null` = 从语言键自动检测。
`typegen.output`	`string`	`null`	生成的 TypeScript 类型的输出路径。`null` = 禁用。
`typegen.autoGenerate`	`boolean`	`false`	每次同步后自动重新生成类型。

对配置

每个源→目标对可以独立配置：

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

对字段

字段	类型	描述
`method`	`string`	翻译方法：`llm`、`llm-coached`、`google-translate`、`deepl`、`microsoft-translator`、`libretranslate`、`openai`、`anthropic`、`gemini`、`api`
`methodPlugin`	`string`	已安装插件的名称（来自 `.champollion/methods/`）
`model`	`string`	覆盖此对的默认模型
`temperature`	`number`	覆盖此对的默认温度
`batchSize`	`number`	覆盖此对的默认批次大小
`register`	`string`	寄存器/语调覆盖（预设键或自由文本）
`endpoint`	`string`	远程 API 端点 URL。当 `method` 为 `api` 时必需。
`coachingFile`	`string`	此对的指导提示文件路径
`promptContext`	`string`	此对的应用程序上下文
`qualityTier`	`string`	显示层级：`standard`、`high`、`research`、`verified`

语言配置

语言接受三种格式：

代码数组（最简单）

{
  "languages": ["fr", "de", "ja"]
}

每种语言从内置寄存器表获取其默认寄存器。没有默认值的语言获得 "Professional register."。

带有寄存器字符串的对象

该值可以是语言卡中的预设键，或自定义寄存器文本：

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Champollion 检查字符串是否与语言卡中的预设键匹配。如果匹配，则使用该卡中的完整寄存器提示。如果不匹配，则按原样使用该字符串。有关可用预设，请参见支持的语言。

带有完整配置的对象

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

您可以在同一块中混合简写和完整对象。

语言字段

字段	类型	描述
`register`	`string`	风格/语调说明。可以是预设键（例如 `casual-tu`、`formal-hapsyo`）或自定义文本。参见语言卡。
`name`	`string`	人类可读的语言名称（用于状态显示）
`model`	`string`	覆盖默认模型
`temperature`	`number`	覆盖默认温度
`batchSize`	`number`	覆盖默认批次大小
`coachingFile`	`string`	此语言的指导提示文件路径
`promptContext`	`string`	此语言的应用程序上下文
`maxRetries`	`number`	失败批次的最大重试预算（默认：3）
`script`	`string`	ISO 15924 脚本代码。在质量门中触发脚本验证。

:::info 继承链设置按此顺序解析（首先获胜）：

对级别 → 语言级别 → 全局配置 → 默认值

例如，如果 pairs["en:fr"] 设置 model，它会覆盖语言级别和全局 model 值。 :::

非英文源

如果您的源语言不是英文：

# CLI flag (one-time)
npx champollion sync --source fr

champollion.config.json (permanent)
{
  "inputLocale": "fr"
}

锁定文件

Champollion 创建 .champollion.lock 来跟踪已翻译源值的 SHA-256 哈希。提交此文件，以便所有开发人员共享相同的翻译基线。

当源值更改时，哈希不再匹配，champollion 会在下次同步时重新翻译该键。

`.champollionignore`

在项目根目录创建 .champollionignore 以从 lint 扫描中排除文件。使用 glob 模式，如 .gitignore：

.champollionignore
src/components/legacy/**
src/utils/constants.js
**/*.test.js

`.champollion/` 目录

Champollion 在项目根目录中创建 .champollion/ 目录用于内部状态。您通常应该将其添加到 .gitignore——这是本地优化，不是项目源：

.champollion/

文件	用途	提交？
`tm.json`	翻译记忆缓存——存储按源文本 + 语言 + 方法键入的先前翻译	否（本地缓存）
`xliff/*.xliff`	XLIFF 导出文件供专业翻译人员审查	否（临时）
`methods/`	已安装方法插件清单	是（共享配置）
`backups/`	预包装备份（由 `wrap --undo` 创建）	否（安全网）

有关 tm.json 的详细信息以及它如何节省 API 成本，请参见翻译记忆。

程序化 API

对于构建脚本和自定义集成，直接从包导入：

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

可用导出

导出	功能
`TranslationMethod`	所有方法的基类
`LLMMethod`	LLM 方法的基类（OpenRouter）
`DirectLLMMethod`	直接 LLM 提供商的基类（OpenAI、Anthropic、Gemini）
`OpenAIMethod`、`AnthropicMethod`、`GeminiMethod`	直接 LLM 提供商类
`DeepLMethod`、`MicrosoftTranslatorMethod`、`LibreTranslateMethod`	传统 MT 类
`GoogleTranslateMethod`	Google Cloud Translation
`LLMCoachedMethod`	指导 LLM（OpenRouter + 指导数据）
`APIMethod`	远程 API 客户端
`runSync`、`runContentSync`	完整同步管道
`resolveConfig`、`resolvePairs`	配置解析
`validateTranslations`	质量门
`loadCoachingData`、`findDictionaryMatches`	指导实用程序

自定义提供商扩展

扩展 DirectLLMMethod 以在约 40 行中添加新的 LLM 提供商：

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

您可以免费获得翻译、指导、重试循环、模型验证、质量层级和设置帮助。只有 HTTP 请求形状是特定于提供商的。对于使用原始 fetch() 的非 LLM 适配器，请使用来自 lib/methods/fetch-with-retry.js 的共享 fetchWithRetry() 助手，而不是编写自己的重试循环。

另请参阅

CLI 参考 — 所有命令和标志
翻译方法 — 选择和混合方法
翻译记忆 — 缓存和成本节省
与专业翻译人员合作 — XLIFF 工作流
插件规范 — 方法插件清单格式
架构 — 各部分如何连接
支持的语言 — 内置语言支持
同步如何工作 — 翻译管道

完整配置参考​

字段​

对配置​

对字段​

语言配置​

代码数组（最简单）​

带有寄存器字符串的对象​

带有完整配置的对象​

语言字段​

非英文源​

锁定文件​

.champollionignore​

.champollion/ 目录​

程序化 API​

可用导出​

自定义提供商扩展​

另请参阅​