命令与命令let

CLIFF 的两类入口：控制台命令（编辑器内 / 无头）与 GatherText 步骤（由官方 UGatherTextCommandlet 按 ini 调度）。

控制台命令

全部注册在编辑器模块启动时（ECVF_Default），随模块卸载注销。

命令	参数	说明
`CliffLocalizationSuite.Hello`	无	模块加载自检，日志输出 `parser, importer and exporter are active (M5 integration).`
`CliffLocalizationSuite.Import`	`<cliffPath> <targetName>`	通过官方 GatherText 管线导入单个 `.cliff` 文件
`CliffLocalizationSuite.Export`	`<targetName> <outputDirectory>`	通过官方 GatherText 管线导出该 Target
`CliffLocalizationSuite.AITranslate`	`<targetName> <culture1,culture2,...>`	导出 CLIFF → DeepSeek 翻译 → 导入 CLIFF
`CliffLocalizationSuite.AI.TestConnection`	无	校验 DeepSeek Key、网络与模型

示例：

CliffLocalizationSuite.Hello
CliffLocalizationSuite.Export Game G:/Translations/cliff
CliffLocalizationSuite.Import G:/Translations/cliff/zh-Hans/cliff-game.cliff Game
CliffLocalizationSuite.AITranslate Game ja,ko
CliffLocalizationSuite.AI.TestConnection

行为要点：

Target 名称通过官方 ILocalizationModule::GetLocalizationTargetByName(name, false) 查找；找不到会记录 warning
参数不足时打印用法 warning，不执行任何操作
API Key 不接受命令行参数，只从环境变量或插件设置读取
AITranslate 的源语言参数恒为空（使用 Target 的 NativeCulture）

GatherText 步骤

三个命令let 都是 UGatherTextCommandletBase 子类，通过 ini 的 CommandletClass 被官方调度（引擎会把类名补上 Commandlet 后缀，即 CliffImport → UCliffImportCommandlet）。

类	`CommandletClass` 值	声明阶段
`UCliffImportCommandlet`	`CliffImport`	Import
`UCliffExportCommandlet`	`CliffExport`	Export
`UCliffAITranslateCommandlet`	`CliffAITranslate`	Import

所有步骤都必须由官方执行器以 -Config="<ini>" -Section="GatherTextStep{N}" 形式调用；缺少任一参数时命令let 报 No config or section specified. 并返回 -1。

公共键（`CommonSettings`）

键	说明
`SourcePath`	Target 的本地化数据目录（`Content/Localization/<Target>`）
`ManifestName`	如 `Game.manifest`
`ArchiveName`	如 `Game.archive`
`NativeCulture`	原生语言，如 `zh-Hans`
`CulturesToGenerate`	可重复出现；导出/导入/AI 均按此列表处理
`DestinationPath`	输出目录（导出/AI 步骤使用）

CliffImport 步骤键

键	必需	说明
`CliffFilePath`	✅*	单个 `.cliff` 绝对路径，可重复出现
`CliffDirectory`	✅*	目录批量导入的根目录
`CliffImportCulture`	⛔	与 `CliffDirectory` 搭配；缺省时使用 `CulturesToGenerate`

* 二选一。目录模式下按 <CliffDirectory>/<culture>/ 前缀筛选 *.cliff 并排序，日志会输出扫描结果：

Scanned CLIFF directory '<dir>': <N> .cliff file(s), selected <M> for cultures <list>.

CliffExport 步骤键

键	必需	说明
`DestinationPath`	✅	导出根目录
`CliffNamespace`	✅	写入 CLIFF header 的 `namespace`
`SourceLanguage`	⛔	覆盖 header 的 `source-language`（默认取 NativeCulture）

CliffAITranslate 步骤键

键	必需	说明
`SourcePath`	✅	待翻译的 CLIFF 根目录
`DestinationPath`	✅	写回目录（可与 `SourcePath` 相同）
`CulturesToGenerate`	✅	本次要翻译的 culture，可重复出现；为空即报错

NOTE

AI 步骤不直接触碰 manifest / archive：它只改 .cliff，随后由 CliffImport 步骤写入官方数据。

生成的配置文件

GUI 与 CLI 都会在 <Project>/Config/Localization/ 下生成官方格式的 GatherText 配置：

文件	触发动作	步骤
`<Target>_CliffImport.ini`	CLIFF 导入	`GatherTextStep0` = `CliffImport`；`GatherTextStep1` = `GenerateTextLocalizationResource`
`<Target>_CliffExport.ini`	CLIFF 导出	`GatherTextStep0` = `CliffExport`（无编译步骤）
`<Target>_CliffAITranslateExport.ini`	AI 翻译（第 1 步）	`CliffExport`，输出到 `Saved/CliffAITranslate/<Target>/`
`<Target>_CliffAITranslate.ini`	AI 翻译（第 2 步）	`CliffAITranslate`
`<Target>_CliffAITranslateImport.ini`	AI 翻译（第 3 步）	`CliffImport`（`CliffDirectory` 形式）+ `GenerateTextLocalizationResource`

示例（导入，节选自实际生成的文件）：

[CommonSettings]
SourcePath=G:/UE/Projects/MyGame/Content/Localization/Game
ManifestName=Game.manifest
ArchiveName=Game.archive
NativeCulture=zh-Hans
CulturesToGenerate=en
CulturesToGenerate=ja

[GatherTextStep0]
CommandletClass=CliffImport
SourcePath=G:/UE/Projects/MyGame/Content/Localization/Game
ManifestName=Game.manifest
ArchiveName=Game.archive
NativeCulture=zh-Hans
CulturesToGenerate=en
CulturesToGenerate=ja
CliffFilePath=G:/Translations/cliff/en/cliff-game.cliff
CliffFilePath=G:/Translations/cliff/ja/cliff-game.cliff

[GatherTextStep1]
CommandletClass=GenerateTextLocalizationResource
SourcePath=G:/UE/Projects/MyGame/Content/Localization/Game
ManifestName=Game.manifest
ArchiveName=Game.archive
NativeCulture=zh-Hans
CulturesToGenerate=zh-Hans
CulturesToGenerate=en
CulturesToGenerate=ja
DestinationPath=G:/UE/Projects/MyGame/Content/Localization/Game
ResourceName=Game.locres

注意两点：导入步骤的 CulturesToGenerate 不含 NativeCulture，而编译步骤包含（保证编辑器界面语言的原生 .locres 一起重建）。

任务与退出码

场景	任务列表（按序串行执行）
导入（单 Target）	`Import Translations` → `Generate Reports`
导入（TargetSet）	每个 Target 一组 `CLIFF 导入：<Target>` / `CLIFF 报告：<Target>`
导出（单 Target）	`Export Translations`
导出（TargetSet）	每个 Target 一个 `CLIFF 导出：<Target>`
AI 翻译（单 Target）	`Export Translations` → `AI 翻译` → `Import Translations` → `Generate Reports`
AI 翻译（TargetSet）	每个 Target 一组 `AI 翻译：导出 <Target>` / `AI 翻译：<Target>` / `AI 翻译：导入 <Target>` / `AI 翻译：报告 <Target>`

GUI 路径：官方子进程 FLocalizationCommandletProcess::Execute(config, true)，ReturnCode == 0 视为成功
无头路径（无活动顶层窗口）：嵌入 UGatherTextCommandlet::Execute("-Config=\"…\" -Unattended")
任一步骤返回非 0 → 该任务标记失败，进度窗口给出红叉与失败日志

命令let 日志样例

UCliffImportCommandlet::Main (Import) started with 2 CLIFF file(s)...
Importing CLIFF file '<path>'...
CLIFF import succeeded for '<path>': 42 sources, 40 translations.
CLIFF batch import succeeded: 84 sources, 80 translations.

UCliffExportCommandlet::Main (Export) started...
CLIFF export succeeded: 3 documents, 126 entries -> '<dir>'.

UCliffAITranslateCommandlet::Main started with 2 culture(s) in '<dir>'.
AI translation succeeded: 84 candidates, 82 translated, 2 failed, 0 repairs.