CLIFF Localization SuiteDocs

原键侧车

导出时，除了 .cliff 文件本身，插件还会写出一个 <Manifest 基础名>.cliffmap.json——原键侧车，记录「CLIFF 规范 ID ↔ 原始 UE Namespace / Key」的对应关系。

为什么需要它

CLIFF 的 name 只允许小写 kebab-case（[a-z][a-z0-9-]*），而 UE 的 Key 是开发者任意字符串：

UE Namespace = UObjectCategory
UE Key       = MyGame|层|字形微调|阴影染色

含中文、|、大写与 / 的 Key 不可能直接作为 CLIFF 的条目 ID。CLIFF 规范本身也明确「引擎键不在 CLIFF 内，由转换器负责映射，可 out-of-band 存映射」——侧车就是这条 out-of-band 通道。

没有侧车也能导入（用映射表 + <group-path>.<entry-id> 生成 Key），但原始 Key 会改变，从而破坏往返无损与既有 archive 的对应关系。因此：

IMPORTANT

请把 .cliff 与同名 .cliffmap.json 一起移动、一起提交、一起分发。

结构

{
  "version": 1,
  "namespace": "p-cliff-l10n-suite",
  "entries": [
    {
      "id": "p-cliff-l10n-suite.cliff-localization-suite-property-names.cliff-localization-suite-settings.entry-f78120e8",
      "namespace": "UObjectDisplayNames",
      "key": "CliffLocalizationSuiteSettings:bAutoRepairCliff",
      "clan": "cliff-localization-suite-property-names",
      "culture": "zh-Hans"
    }
  ]
}
字段类型说明
versionint侧车结构版本，当前为 1
namespacestringCLIFF header 的 namespace（导出时使用的 CLIFF Namespace 设置）
entriesarray条目映射表
entries[].idstringCLIFF 规范 ID：<namespace>.<clan>.<group-path>.<entry-id>
entries[].namespacestring原始 UE Namespace
entries[].keystring原始 UE Key
entries[].clanstring条目级 clan（语义家族）
entries[].culturestring该条目所属的目标语言

编码：UTF-8 无 BOM，缩进美化（PrettyJsonPrintPolicy）。

发现顺序

导入（GUI、CLI、AI 管线）会自动寻找侧车：

  1. 与被导入 .cliff 同目录的 <文件名>.cliffmap.json （例：zh-Hans/cliff-game.cliff → zh-Hans/cliff-game.cliffmap.json）
  2. 上一级目录中的 <Manifest 基础名>.cliffmap.json （例：zh-Hans/cliff-game.cliff → Game.cliffmap.json）
  3. 都没有 → 用 Clan to Namespace 映射 + <group-path>.<entry-id> 生成 Key，并记录告警： Sidecar '<path>' could not be loaded; falling back to algorithmic Namespace/Key mapping.

TIP

侧车查找基于文件路径而非内容哈希，因此把导出目录整体移动到别处不影响还原。

还原规则

导入每条 entry 时：

canonical = document.GetCanonicalId(group, entry)     # namespace.clan.group.entry
if (sidecar 命中 canonical) {
    UE Namespace = sidecar.namespace
    UE Key       = sidecar.key
} else {
    UE Namespace = 语义映射(clan) 或 CLIFF namespace
    UE Key       = "<group-path>.<entry-id>"
}

要点：

  • 侧车中的 id 必须与当前文档的 canonical ID 完全一致才生效（大小写敏感）
  • 侧车文件可以累积多个 culture、多次导出的条目：同一个文件里不同 culture 的记录互不干扰
  • 侧车损坏或 JSON 解析失败时不会中断导入，只增加一个 warning 并回退到算法映射

何时写出

条件行为
bWriteSidecar = true（默认）且 OutputDirectory 非空写出 <OutputDirectory>/<Manifest 基础名>.cliffmap.json
OutputDirectory 为空（只取文档结构、不落盘）不写侧车
通过 AI 管线导出侧车写到 Saved/CliffAITranslate/<Target>/，并随翻译产物一起拷回 Target 数据目录

相关阅读