CLIFF Localization Suiteمستندات

第一次 AI 翻译

AI 翻译是插件内置的三段式管线：导出 CLIFF → DeepSeek 翻译 → 导入 CLIFF。AI 只负责生成译文文本，写回仍然由官方 FLocTextHelper 与 .locres 生成器完成；已经有人工译文（reviewed / final）的条目永不被覆盖。

前置条件

  1. 已完成一次 CLIFF 导出与导入，确认管线可用
  2. 准备 DeepSeek API Key（在 https://platform.deepseek.com 创建，形如 sk-…）

一、打开插件设置面板

插件的全部配置都是 UDeveloperSettings，挂在官方 Project Settings 窗口的 Plugins 区域下。三个入口，任选其一：

  1. 编辑 > 项目设置 → 左侧列表向下滚动到 Plugins → 展开 CLIFF Localization Suite
  2. 编辑 > 插件 → 在已启用列表中找到 CLIFF Localization Suite → 点击该行的 设置（齿轮）图标
  3. 工具栏 设置 按钮 → 项目设置 → 同上

展开后左侧共四个分类：Identity、Semantic Mapping、Workflow、AI Translation。AI 翻译只用到最后一个。

项目设置窗口：Plugins 分组下展开 CLIFF Localization Suite，右侧为 AI Translation 分类的配置项（DeepSeek API Key 密码框、Base URL、Model、Thinking Level 与批量/重试参数）

二、填写 DeepSeek 配置

点开 AI Translation 分类。最小配置只有三项：

设置项字段填什么
DeepSeek API KeyDeepSeekApiKey你的 sk-…；密码框，输入时显示为圆点
DeepSeek Base URLDeepSeekBaseUrl默认 https://api.deepseek.com，用官方服务时不用改
DeepSeek ModelDeepSeekModel默认 deepseek-flash；换模型时填 DeepSeek 的模型名

其余参数（Thinking Level、Batch Size、Max Retries、Max Concurrent Cultures、Translation Standard、System Prompt 等）可以先保持默认，含义与调参建议见 AI 翻译配置，字段全表见 设置参考。

IMPORTANT

改动项目设置里的字段后立即生效，不需要重启编辑器；只有环境变量需要重启（见下）。设置面板本身不提供「测试连接」按钮，连接验证请用第三步的控制台命令。

用环境变量代替（推荐）

环境变量优先于设置字段。设置了环境变量时，设置面板里的 Key 会被忽略——这样可以避免明文入库：

# Windows：设置当前用户级持久环境变量（重开终端后生效）
setx DEEPSEEK_API_KEY "sk-你的密钥"

# PowerShell 当前会话临时生效（只影响这个窗口启动的进程）
$env:DEEPSEEK_API_KEY = "sk-你的密钥"

设置后重启编辑器。setx 写入的是用户级变量，之后新开的进程都能读到。

WARNING

在设置面板里填写的 Key 会以明文写入 Config/DefaultEditor.ini（UE UDeveloperSettings 的行为），该文件通常会被提交到版本库。提交前请清空该字段，改用环境变量。

三、验证连接

在编辑器任意控制台（窗口 > 输出日志 的 Cmd 输入框，或底部的控制台命令行）执行：

CliffLocalizationSuite.AI.TestConnection

它读取 Key → 发一条极小请求 → 输出成功/失败、HTTP 状态、模型名与耗时。Key 缺失时的提示为：

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

看到 Failed 且带 HTTP 状态码时，对照 故障排查 逐项核对 Key、Base URL 与网络代理。

开始翻译

  1. 在 本地化 Dashboard 中选中一个 Target

  2. 点击工具栏 AI 翻译

  3. 在弹出的 AI 自动翻译 窗口中选择目标语言（可多选，只列出该 Target 的非原生 Culture）

    “AI 自动翻译”模态窗口：Culture 复选框列表与“开始翻译 / 取消”按钮

  4. 点击 开始翻译 —— 官方同款进度窗口依次执行四个任务：

    Export Translations      导出到 Saved/CliffAITranslate/<Target>/
AI 翻译                  DeepSeek 分批翻译缺失 target 的条目并写回 .cliff
Import Translations      走官方 CliffImport 步骤写 manifest / archive，并编译 .locmeta / .locres
Generate Reports         官方字数报告，刷新 Dashboard 统计

    AI 翻译进度窗口：四个任务依次执行，日志实时滚动

  5. 完成后日志给出统计（候选 / 成功 / 跳过 / 失败 / 批次 / 修复次数），Dashboard 字数随即刷新

NOTE

翻译的工作目录是 Saved/CliffAITranslate/<Target>/，每次执行前会被清空重建。管线结束时会把翻译后的 .cliff 拷回 Target 的数据目录（Content/Localization/<Target>/），即使后续导入步骤因源码管理等原因失败，译文文件也不会丢。

哪些条目会被翻译

条目状态是否进入请求
status: initial（无 target）✅ 翻译
无 target 字段✅ 翻译
status: translated 且 target == source、源文本语种不属于目标语言（自翻译）✅ 重译（Retranslate Self Translations 开启时，默认开启）
status: translated / reviewed / final 且已有正常译文⛔ 跳过，绝不覆盖
reviewed / final（人工已审/锁定）⛔ 永不触碰

原生 Culture 不参与翻译；同一次任务里可以勾选多个目标语言，多个语言并发请求（每语言一条独立对话，并发上限 Max Concurrent Cultures，默认 4）。

命令行等价用法

CliffLocalizationSuite.AITranslate <targetName> <culture1,culture2,...>

例如：

CliffLocalizationSuite.AITranslate Game ja,ko,zh-Hans

AI 翻译、Key 读取、批量与重试策略与 GUI 完全一致；Key 不会出现在命令行里，只从环境变量或插件设置读取。

结果检查

  1. 日志：进度窗口底部日志逐文件输出翻译结果；Copy Log 可整段复制，Save Log... 可存盘归档
  2. CLIFF 中间产物：Content/Localization/<Target>/<Culture>/<Clan>.cliff 中 target 已填充、status 变为 translated，可以直接人工评审或交给外部工具
  3. Translation Editor：打开 窗口 > 本地化 > 翻译编辑器，确认译文到位且没有「需要检查」误报
  4. PIE：进入 PIE 确认 UI 文本已切换

TIP

只想先试水？在 AI 翻译窗口里只勾选一个语言，并把 Batch Size 设小（如 5）、Max Retries 设 1，用少量条目验证提示词与术语是否符合预期，再放开全量。

注意这些字段在 项目设置 里，不在 AI 翻译窗口内 —— 想调参请回到第一步的设置面板。

下一步建议阅读：AI 翻译配置（提示词与翻译标准）与 写回防护与修复（自翻译、空译文、占位符与 CLIFF 修复闭环）。