故障排查
按「现象 → 原因 → 处理」组织。日志入口：输出日志（Window > Output Log）、Dashboard 进度窗口的 Copy Log / Save Log...、以及 Saved/Logs/ 下的日志文件。
安装与编译
| 现象 | 原因 | 处理 |
|---|
编译报找不到 CliffLocalizationSuite 模块 | Build.cs 模块名拼写错误或未添加依赖 | 运行时用 CliffLocalizationSuite，编辑器用 CliffLocalizationSuiteEditor |
| Game / Shipping 打包失败，提示编辑器模块缺失 | 把 CliffLocalizationSuiteEditor 加进了 Runtime 依赖 | 它只在编辑器目标构建；运行时模块零编辑器依赖 |
| 启用插件后编辑器提示需要重启 | 新模块加载需要重启 | 点击 立即重启 |
| 首次启用编译很久 | 发布包为源码交付，需要本机首次编译 | 属正常现象；确保 C++ 工具链可用 |
Dashboard 与按钮
| 现象 | 原因 | 处理 |
|---|
| 工具栏没有 CLIFF 按钮 | Dashboard 在 Provider 切换前已构建工具栏 | 关闭并重新打开 Localization Dashboard；或在 Localization Service Provider 下拉框中选择 CLIFF Localization Suite |
日志缺少 provider registered and selected | 编辑器模块未加载 | 检查插件是否启用、模块是否为 CliffLocalizationSuiteEditor（Type: Editor） |
| 点击按钮提示「请在 Target 列表中选中一个具体 Target」 | 当前选中的是 TargetSet（集合） | 在 Target 列表中选中具体 Target 后使用其详情面板工具栏 |
| 目标语言列表为空（AI 翻译窗口） | Target 只配置了原生语言 | 在 Dashboard 中为该 Target 添加目标 Culture |
导入
| 现象 | 原因 | 处理 |
|---|
所选目录中没有找到 .cliff 文件。 | 目录里没有 .cliff（递归扫描） | 检查目录与文件扩展名 |
The CLIFF document is invalid; see the validation issues. | 文件未通过校验 | 按日志中的行号与类别修正；常见为缺 status / type、emotion 少方括号、花括号不平衡 |
Missing required CLIFF import settings in section '…' | 手工运行命令let 时配置缺键 | GatherText 配置需含 SourcePath / ManifestName / ArchiveName / NativeCulture |
| 导入后译文没生效 | 未编译 .locres 或未热刷新 | 走 GUI/官方管线（含 GenerateTextLocalizationResource 步骤）；确认日志中有编译产物路径 |
| 编辑器 UI（原生语言）文本变成空白 | 编译步骤排除了 NativeCulture | 当前版本已把 NativeCulture 纳入编译；如为旧配置文件，删除 Config/Localization/*_CliffImport.ini 后重新导入 |
| Translation Editor 大量「需要检查」 | 源语言与外语条目的「生效源」不一致 | 当前版本在导入源语言时自动同步外语条目的 Source；重新导入一次即可收敛 |
| 同一 key 出现两个不同译文 | 历史遗留的重复 manifest context | 删除 Config/Localization/ 下本插件生成的 ini 与相关 Target 数据后重新导入；插件现在会把元数据挂到既有 context 上 |
| 导入后条目数没有增加 | 条目已存在且 Source 完全一致 | 属预期行为（按 identity 去重，不产生重复条目） |
导出
| 现象 | 原因 | 处理 |
|---|
Native culture is required (configure it or provide a valid .locmeta). | Target 未设置原生语言，且目录里没有 .locmeta | 在 Dashboard 配置 Native Culture，或先跑一次官方 Compile |
No type rule for namespace '…'; exported as 'sentence'. | 映射表缺规则 | 在 Semantic Mapping → Namespace to Type 补规则 |
UE namespace '…' has no semantic clan mapping; exported as clan '…'. | 反向映射缺失，走了 kebab-slug 兜底 | 在 Clan to Namespace 补映射 |
Generated CLIFF document for culture '…' failed validation. | 导出结果未通过自校验 | 按日志中的 issue 行号排查（通常是名称合法性问题） |
导出目录里只有 *.cliffmap.json | DestinationPath 为空或未选择目录 | 重新选择输出目录；目录对话框默认取 Target 数据目录或 Default Export Directory |
只读 .locres 导出时源文本为空 | 二进制不含源文本且目录内没有 manifest | 用 manifest + archive 作为导出源（推荐），或补齐同目录 manifest |
AI 翻译
| 现象 | 原因 | 处理 |
|---|
AI 翻译缺少 DeepSeek API Key；请设置 DEEPSEEK_API_KEY 环境变量或插件设置。 | 未配置 Key | 设置环境变量 DEEPSEEK_API_KEY（推荐）或填写插件设置后重启编辑器 |
请至少选择一个需要 AI 翻译的 Culture。 | 未勾选语言 | 在 AI 翻译窗口中勾选至少一个语言 |
AI 翻译未产生任何译文，请检查 DeepSeek 响应日志。 | 整次任务 0 条成功 | 先用 CliffLocalizationSuite.AI.TestConnection 验证 Key/网络/模型；检查日志中打印的响应片段 |
| 部分条目没有译文 | 空译文、自翻译或占位符不符被拒绝写回 | 查看 warning（skipped / refused / mismatch）；确认源文本与目标语言是否匹配 |
某个 .cliff 没有更新 | AI 修复后仍不合法 | 日志会给出 still invalid after repair; not written.；手动修正该文件的 issue 后重跑 |
AI returned the source unchanged for '…'; self-translation refused. | 模型把源文原样返回且语种不符 | 检查 Translation Standard 与提示词；确认目标语言设置正确 |
| 大批量时编辑器卡顿 | HTTP 以同步方式刷新（FullFlush） | 调小 Batch Size、降低 Max Concurrent Cultures，分批执行 |
| Key 出现在配置文件中 | UDeveloperSettings 明文写入 Config/DefaultEditor.ini | 清空设置字段并改用环境变量；提交前检查该文件的 diff |
数据一致性
| 现象 | 原因 | 处理 |
|---|
手动改了 manifest / archive，重新导入后被覆盖 | 官方 FLocTextHelper 拥有这些文件 | 不要手改；改 .cliff 后重新导入 |
| 侧车丢了，Key 变了 | .cliff 与侧车未一起移动 | 把 <Manifest>.cliffmap.json 与 .cliff 一起提交、一起分发 |
.cliff 在 Git 里冲突 | 两个分支同时改同一文件 | 冲突通常发生在 target: 与 status: 行，按语义合并即可；id 与 group 不应冲突 |
| CI 中导入失败但本地成功 | 缺少环境变量或 Target 未配置 | CI 中设置 DEEPSEEK_API_KEY，并保证 Config/Localization/ 下的 Target 配置已提交 |
诊断命令
CliffLocalizationSuite.Hello # 模块加载自检
CliffLocalizationSuite.AI.TestConnection # DeepSeek Key / 网络 / 模型自检
CliffLocalizationSuite.Export <targetName> <outputDirectory>
CliffLocalizationSuite.Import <clifFilePath> <targetName>
CliffLocalizationSuite.AITranslate <targetName> <culture1,culture2,...>
TIP
提交 issue 时请附上：编辑器版本、插件版本、完整日志（进度窗口 Save Log...）、最小可复现的 .cliff 片段（可脱敏）。有了 Copy Log 的完整输出，绝大多数问题都能定位到具体条目与行号。
