Commands and Commandlets
CLIFF has two kinds of entry point: console commands (in-editor / headless) and GatherText steps (scheduled from the ini by the official UGatherTextCommandlet).
Console commands
All of them are registered when the editor module starts up (ECVF_Default) and unregistered when the module unloads.
| Command | Arguments | Description |
|---|---|---|
CliffLocalizationSuite.Hello | None | Module load self-check; the log prints parser, importer and exporter are active (M5 integration). |
CliffLocalizationSuite.Import | <cliffPath> <targetName> | Import a single .cliff file through the official GatherText pipeline |
CliffLocalizationSuite.Export | <targetName> <outputDirectory> | Export that Target through the official GatherText pipeline |
CliffLocalizationSuite.AITranslate | <targetName> <culture1,culture2,...> | Export CLIFF → DeepSeek translation → import CLIFF |
CliffLocalizationSuite.AI.TestConnection | None | Validate the DeepSeek key, network and model |
Examples:
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.TestConnectionBehaviour notes:
- The Target name is looked up through the official
ILocalizationModule::GetLocalizationTargetByName(name, false); a miss records a warning - When arguments are insufficient a usage warning is printed and nothing is executed
- The API key accepts no command line argument; it is only read from the environment variable or the plugin settings
- The source language argument of
AITranslateis always empty (the Target’s NativeCulture is used)
GatherText steps
All three commandlets are UGatherTextCommandletBase subclasses and are scheduled by the official code through the ini’s CommandletClass (the engine appends the Commandlet suffix to the class name, i.e. CliffImport → UCliffImportCommandlet).
| Class | CommandletClass value | Declared phase |
|---|---|---|
UCliffImportCommandlet | CliffImport | Import |
UCliffExportCommandlet | CliffExport | Export |
UCliffAITranslateCommandlet | CliffAITranslate | Import |
Every step must be invoked by the official executor in the form -Config="<ini>" -Section="GatherTextStep{N}"; when either parameter is missing the commandlet reports No config or section specified. and returns -1.
Common keys (CommonSettings)
| Key | Description |
|---|---|
SourcePath | The Target’s localization data directory (Content/Localization/<Target>) |
ManifestName | e.g. Game.manifest |
ArchiveName | e.g. Game.archive |
NativeCulture | The native language, e.g. zh-Hans |
CulturesToGenerate | Repeatable; export / import / AI all process this list |
DestinationPath | Output directory (used by the export / AI steps) |
CliffImport step keys
| Key | Required | Description |
|---|---|---|
CliffFilePath | ✅* | Absolute path of a single .cliff, repeatable |
CliffDirectory | ✅* | Root directory for batch directory import |
CliffImportCulture | ⛔ | Used together with CliffDirectory; when absent CulturesToGenerate is used |
* Choose one of the two. In directory mode *.cliff is filtered by the <CliffDirectory>/<culture>/ prefix and sorted, and the log prints the scan result:
Scanned CLIFF directory '<dir>': <N> .cliff file(s), selected <M> for cultures <list>.CliffExport step keys
| Key | Required | Description |
|---|---|---|
DestinationPath | ✅ | Export root directory |
CliffNamespace | ✅ | The namespace written into the CLIFF header |
SourceLanguage | ⛔ | Overrides the header’s source-language (defaults to NativeCulture) |
CliffAITranslate step keys
| Key | Required | Description |
|---|---|---|
SourcePath | ✅ | Root directory of the CLIFF to translate |
DestinationPath | ✅ | Directory to write back to (may be the same as SourcePath) |
CulturesToGenerate | ✅ | The cultures to translate this time, repeatable; empty is an error |
NOTE
The AI step does not touch the manifest / archive directly: it only modifies
.cliff, which theCliffImportstep then writes into the official data.
Generated config files
Both the GUI and the CLI generate official-format GatherText configuration under <Project>/Config/Localization/:
| File | Triggering action | Steps |
|---|---|---|
<Target>_CliffImport.ini | CLIFF import | GatherTextStep0 = CliffImport; GatherTextStep1 = GenerateTextLocalizationResource |
<Target>_CliffExport.ini | CLIFF export | GatherTextStep0 = CliffExport (no compilation step) |
<Target>_CliffAITranslateExport.ini | AI translation (step 1) | CliffExport, output to Saved/CliffAITranslate/<Target>/ |
<Target>_CliffAITranslate.ini | AI translation (step 2) | CliffAITranslate |
<Target>_CliffAITranslateImport.ini | AI translation (step 3) | CliffImport (the CliffDirectory form) + GenerateTextLocalizationResource |
Example (import, excerpted from an actually generated file):
[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.locresNote two things: the import step’s CulturesToGenerate does not include the NativeCulture, while the compilation step does (so that the native .locres for the editor UI language is rebuilt as well).
Tasks and exit codes
| Scenario | Task list (executed serially in order) |
|---|---|
| Import (single Target) | Import Translations → Generate Reports |
| Import (TargetSet) | One group per Target: CLIFF 导入：<Target> / CLIFF 报告：<Target> |
| Export (single Target) | Export Translations |
| Export (TargetSet) | One CLIFF 导出：<Target> per Target |
| AI translation (single Target) | Export Translations → AI 翻译 → Import Translations → Generate Reports |
| AI translation (TargetSet) | One group per Target: AI 翻译：导出 <Target> / AI 翻译：<Target> / AI 翻译：导入 <Target> / AI 翻译：报告 <Target> |
- GUI path: the official subprocess
FLocalizationCommandletProcess::Execute(config, true), whereReturnCode == 0counts as success - Headless path (no active top-level window): embeds
UGatherTextCommandlet::Execute("-Config=\"…\" -Unattended") - Any step returning non-zero → that task is marked failed, and the progress window shows a red cross plus the failure log
Commandlet log examples
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.