Dashboard 工作流

CLIFF 的日常用法只有两个动作：导出（UE → .cliff）与导入（.cliff → UE）。两者都作为官方 GatherText 管线的一个步骤执行，因此进度窗口、日志格式与官方「Import Text / Export Text」完全一致。

准备

在 工具 > 本地化 Dashboard 中选中一个 Localization Target
确认该 Target 已配置 Native Culture 与至少一种目标 Culture
确认工具栏右侧出现 CLIFF 导入 / CLIFF 导出 / AI 翻译

NOTE

这三个按钮由插件注册的官方 LocalizationService Provider 注入。选中 TargetSet（集合）而不是具体 Target 时，按钮同样出现，但行为不同：导出/导入会批量处理集合内的全部 Target（每个 Target 一个子目录），AI 翻译则弹出 Culture 选择窗口后逐个 Target 执行。

导出：UE → CLIFF

适用场景：把现有译文取出成可读文件，交给翻译、评审或外部工具。

点击 CLIFF 导出
在目录对话框中选择输出目录
官方同款进度窗口出现，任务为 Export Translations；完成后通知气泡显示输出目录

输出目录布局（每个语言一个子目录，文件按 Target 命名）：

<输出目录>/
├── <Manifest>.cliffmap.json        # 原键侧车（一次导出共用）
├── zh-Hans/
│   └── cliff-<target>.cliff
├── ja/
│   └── cliff-<target>.cliff
└── …

IMPORTANT

.cliffmap.json 是往返无损的关键。UE 的 Key 常常就是源语言文本本身（可含中文、|、大写与 /），无法直接作为 CLIFF 的 name；导出时插件生成稳定 ID，并把「原 UE Namespace / Key ↔ CLIFF canonical ID」写入侧车。导入时自动寻找同名侧车并恢复原键，因此请把侧车与 .cliff 一起移动、一起提交。

TIP

侧车的查找顺序：先找与被导入文件同目录的 <文件名>.cliffmap.json，再找上一级目录的 <Manifest>.cliffmap.json。找不到侧车时会用 Clan to Namespace 映射 + <group-path>.<entry-id> 生成 Key，并记录告警。

导入：CLIFF → UE

适用场景：拿到（或由 AI 生成、或人工编辑）的 .cliff 回写进项目。

点击 CLIFF 导入
选择包含 .cliff 的目录（插件会递归扫描该目录下的全部 *.cliff 并按路径排序）
进度窗口依次执行两个官方任务：Import Translations → Generate Reports
完成后通知气泡显示导入文件数量；Dashboard 的字数与状态随即刷新

导入实际发生的事（单个 GatherText 配置内两个步骤）：

GatherTextStep0: CommandletClass=CliffImport
    SourcePath      = <Content>/Localization/<Target>
    ManifestName    = <Target>.manifest
    ArchiveName     = <Target>.archive
    NativeCulture   = zh-Hans
    CulturesToGenerate = zh-Hans / en / ja / ...
    CliffFilePath / CliffDirectory + CliffImportCulture
        ↓ 写 manifest（源文本）与 archive（译文）
GatherTextStep1: CommandletClass=GenerateTextLocalizationResource
    DestinationPath = <Content>/Localization/<Target>
    ResourceName    = <Target>.locres
        ↓ 重新编译 .locmeta / .locres（含 NativeCulture）
        ↓ FTextLocalizationManager 热刷新 + 广播 LocalizationDelegates

IMPORTANT

导入先按原生语言排序，并在导入源语言时自动把外语 archive 条目的「生效源」同步为新源文本（译文不动）。这让导入顺序不再重要：无论你只导入源语言、只导入外语，还是混在一起一次导入，单次运行即可收敛，Translation Editor 不会出现无谓的「需要检查」。

导入后检查

检查点	位置	期望
条目与译文	窗口 > 本地化 > 翻译编辑器	新条目出现，外语译文已填充，「需要检查」为 0
字数与进度	Localization Dashboard 的 Target 详情	字数与完成度随报告刷新
热刷新	编辑器 UI / PIE	无需重启编辑器即可看到新文本
编译产物	`Content/Localization/<Target>/<Culture>/<Target>.locres`	各 culture（含 NativeCulture）均已重建

等价命令

相同管线也可以无头执行（例如在 CI 中）：

CliffLocalizationSuite.Export <targetName> <outputDirectory>
CliffLocalizationSuite.Import <clifFilePath> <targetName>

完整参数见命令与命令let。

常见操作建议

不要手工编辑 manifest / archive：它们由官方 FLocTextHelper 维护，手改会在下一次导入时被覆盖。
.cliff 与侧车一起纳入版本控制：.cliff 是纯文本、UTF-8 无 BOM、LF，diff 友好，适合评审。
导出目录建议放在仓库外（如 Saved/CliffExport/）或专门的翻译仓库，避免误提交临时数据。
批量目录导入：一个目录内的多个 .cliff 会在同一个官方任务里导入，日志逐文件输出结果。