AI 翻译配置

所有 AI 相关设置都在 编辑 > 项目设置 > 插件 > CLIFF Localization Suite > AI Translation。本文说明每个参数的作用与调参建议；字段的完整清单见设置参考。

凭据与端点

设置项	默认值	说明
`DeepSeek API Key`	空	留空时读取环境变量 `DEEPSEEK_API_KEY`
`DeepSeek Base URL`	`https://api.deepseek.com`	官方地址；填了 `/v1` 也会被正确拼接
`DeepSeek Model`	`deepseek-flash`	模型名

Key 解析顺序：环境变量 DEEPSEEK_API_KEY → 插件设置字段。不提供自定义环境变量名。

WARNING

UDeveloperSettings 会把字段明文写进 Config/DefaultEditor.ini。提交仓库前请清空 DeepSeek API Key，改用环境变量。插件保证 Key 不会出现在日志、不会写进 GatherText 配置、也不会出现在任何进程命令行参数中。

思考强度

Thinking Level 控制 DeepSeek 的推理开销：

取值	请求行为
`关闭`（默认）	`thinking.type = disabled`，并使用官方翻译推荐的 `temperature = 1.3`
`低`	`thinking.type = enabled` + `reasoning_effort = low`
`高`	`thinking.type = enabled` + `reasoning_effort = high`（DeepSeek 官方默认）
`最高`	`thinking.type = enabled` + `reasoning_effort = max`（质量优先，耗时更长）

建议：游戏 UI 文本用「关闭」即可（更快更便宜）；出现大量长句、双关或术语密集的文本时再试「高」。

提示词与翻译标准

System Prompt

留空 → 使用内置默认提示词（英文撰写，强调混合语种识别、占位符严格保留、不翻译类名/变量名/路径、只返回 JSON）
填写 → 完全替换默认提示词
设置面板没有「恢复默认提示词」按钮；改坏了就把该字段清空，即回到内置默认提示词

内置默认提示词要求模型只返回这个形状：

{"translations": [{"id": "...", "translation": "..."}]}

Translation Standard

Translation Standard 有两个作用：

导出 CLIFF 时写入 header 的 standard: 字段，让翻译文件自带风格要求
发送请求时追加到 System Prompt 末尾（形如 === Translation Standard === 段落）

示例：游戏 UI 使用简体中文，保留英文专有名词与品牌名，不使用方言，按钮文本不超过 8 个汉字。

TIP

把「术语表、人称、标点风格、禁止项」放进 Translation Standard 而不是塞进 System Prompt：前者会随 .cliff 一起流转，外部翻译或其它工具也看得到；后者只对本机的 AI 请求生效。

请求体结构

插件的传输实现是 DeepSeek 的 OpenAI 兼容 POST {BaseUrl}/chat/completions：

{
  "model": "deepseek-flash",
  "messages": [
    { "role": "system", "content": "<System Prompt + Translation Standard>" },
    { "role": "user",   "content": "[{\"id\":\"1\",\"source\":\"Play\",\"context\":\"Main menu button\"}]" }
  ],
  "thinking": { "type": "disabled" },
  "temperature": 1.3,
  "stream": false,
  "max_tokens": 8192,
  "response_format": { "type": "json_object" }
}

细节	值	原因
`max_tokens`	固定 `8192`	长 JSON 译文集被截断会导致整批解析失败
`response_format`	`json_object`	强制 JSON 输出
`stream`	`false`	命令let 内用统一事件循环收集结果
`thinking` / `temperature`	见上表	思考关闭时才用 `temperature = 1.3`
`context` 字段	受 `Include Context` 控制	关闭后只发 `id` 与 `source`，更省 token

批量协议：一次请求携带一批条目（Batch Size，默认 20），每条带 id（canonical ID）、source，可选 context；user content 里还会写明 Source language / Target language 与「混合语种撰写」规则，并要求模型返回输入中的全部 id。响应解析顺序：本身是 JSON 数组 → 对象内的 translations / results / data / items 数组 → 退回到首个 [ 与最后一个 ] 之间的子串。空数组是合法结果。

失败回退：单批重试（最多 Max Retries 次，间隔递增 0.5s / 1.0s / …）→ 该批仍失败则跳过并记 warning → 整轮结束后自动再跑一轮（最多 Max Retries 轮），只处理仍未拿到译文的条目。

批量、并发与超时

设置项	默认	调参建议
`Batch Size`	20	条目短小可调到 30–50；长句或术语密集时调小到 10，减少 JSON 截断风险
`Max Concurrent Cultures`	4	并发批次数的上限（实现上按批分块并发发送，然后统一等待）；API 限流时降到 2
`Request Timeout`	60 秒	开启思考或批量较大时提高到 120
`Max Retries`	3	网络不稳时保持 3；CI 中可降到 1 快速失败
`Include Context`	开	关闭可显著省 token，但会牺牲 register/语气判断质量

修复与重译

设置项	默认	说明
`Auto Repair CLIFF`	开	AI 产出的 CLIFF 校验失败时，把原文 + issue 列表交回模型修复
`Max Repair Attempts`	2	单文件最大修复轮数；超过则标记该文件失败且不导入
`Retranslate Self Translations`	开	把 `target == source` 且语种不符的条目视为伪翻译并重译；`reviewed` / `final` 永不触碰

细节见写回防护与修复。

测试连接

设置面板里没有连接测试按钮，验证只有一个入口 —— 控制台命令：

CliffLocalizationSuite.AI.TestConnection

输出内容：成功/失败、HTTP 状态、模型名与耗时。缺少 Key 时提示：

AI 翻译缺少 DeepSeek API Key；请设置 DEEPSEEK_API_KEY 环境变量或插件设置。

翻译统计

每次执行结束，命令let 输出一行汇总（GUI 与 CLI 相同）：

AI translation succeeded: <候选> candidates, <已翻译> translated, <失败> failed, <修复> repairs.

统计字段含义：CandidateCount（进入请求的候选条目）、TranslatedCount、SkippedCount（已有译文被跳过）、FailedCount、RepairCount、BatchCount、FailedFiles。

成本控制建议

只补缺失：插件默认不覆盖已有译文，重复执行不会重复付费
先小批试水：单语言 + Batch Size = 5 + Max Retries = 1，确认提示词与术语后再跑全量
关掉 Context：条目本身足够自解释时，省下的 token 很可观
用「关闭」思考：UI 短文本几乎没有推理收益
把术语写进 Translation Standard：比让模型自由发挥更省重译成本