Troubleshooting

Organised as “symptom → cause → fix”. Log entry points: the Output Log (Window > Output Log), the Copy Log / Save Log... buttons of the Dashboard progress window, and the log files under Saved/Logs/.

Installation and compilation

Symptom	Cause	Fix
Compilation reports that the `CliffLocalizationSuite` module cannot be found	A misspelled module name in `Build.cs`, or a missing dependency	Use `CliffLocalizationSuite` at runtime and `CliffLocalizationSuiteEditor` in the editor
Game / Shipping packaging fails, complaining about a missing editor module	`CliffLocalizationSuiteEditor` was added to the runtime dependencies	It is built for editor targets only; the runtime module has zero editor dependencies
After enabling the plugin the editor asks for a restart	Loading the new module requires a restart	Click 立即重启
The first enable takes a long time to compile	Release packages ship as source and need a local first build	This is normal; make sure the C++ toolchain is available

Dashboard and buttons

Symptom	Cause	Fix
The toolbar has no CLIFF buttons	The Dashboard built its toolbar before the provider switch	Close and reopen the Localization Dashboard; or pick `CLIFF Localization Suite` in the Localization Service Provider dropdown
The log is missing `provider registered and selected`	The editor module is not loaded	Check that the plugin is enabled and the module is `CliffLocalizationSuiteEditor` (Type: Editor)
Clicking a button reports 「请在 Target 列表中选中一个具体 Target」	A TargetSet (collection) is currently selected	Select a concrete Target in the Target list and use the toolbar of its details panel
The target language list is empty (AI translation window)	The target only has a native culture configured	Add target Cultures to that target in the Dashboard

Import

Symptom	Cause	Fix
`所选目录中没有找到 .cliff 文件。`	There is no `.cliff` in the directory (recursive scan)	Check the directory and the file extension
`The CLIFF document is invalid; see the validation issues.`	The file failed validation	Fix it following the line numbers and categories in the log; typical cases are a missing `status` / `type`, an `emotion` without square brackets, or unbalanced braces
`Missing required CLIFF import settings in section '…'`	The configuration is missing keys when the commandlet is run by hand	The GatherText configuration must contain `SourcePath` / `ManifestName` / `ArchiveName` / `NativeCulture`
Translations do not take effect after the import	`.locres` was not compiled, or there was no live refresh	Go through the GUI / official pipeline (including the `GenerateTextLocalizationResource` step); confirm the compiled artefact paths appear in the log
Editor UI text (native language) turns blank	The compile step excluded NativeCulture	The current version includes NativeCulture in the compile; with an old configuration file, delete `Config/Localization/*_CliffImport.ini` and import again
The Translation Editor shows lots of “needs review”	The “effective source” of source-language and foreign entries does not match	The current version synchronises the Source of foreign entries automatically when the source language is imported; one more import converges
The same key shows two different translations	A legacy duplicate manifest context	Delete the ini files generated by this plugin under `Config/Localization/` plus the related target data and import again; the plugin now attaches metadata to the existing context
The entry count does not grow after the import	The entries already exist with a completely identical Source	Expected behaviour (de-duplicated by identity, so no duplicate entries are produced)

Export

Symptom	Cause	Fix
`Native culture is required (configure it or provide a valid .locmeta).`	The target has no native culture and there is no `.locmeta` in the directory	Configure the Native Culture in the Dashboard, or run the official Compile once first
`No type rule for namespace '…'; exported as 'sentence'.`	The mapping table is missing a rule	Add the rule under Semantic Mapping → Namespace to Type
`UE namespace '…' has no semantic clan mapping; exported as clan '…'.`	The reverse mapping is missing and the kebab-slug fallback was used	Add the mapping under Clan to Namespace
`Generated CLIFF document for culture '…' failed validation.`	The export result did not pass the self-check	Investigate using the issue line numbers in the log (usually a name legality problem)
The export directory contains only `*.cliffmap.json`	`DestinationPath` is empty or no directory was chosen	Choose the output directory again; the directory dialog defaults to the target data directory or the `Default Export Directory`
Source text is empty when exporting a read-only `.locres`	The binary carries no source text and there is no manifest in the directory	Use the manifest + archive as the export source (recommended), or provide the manifest in the same directory

AI translation

Symptom	Cause	Fix
`AI 翻译缺少 DeepSeek API Key；请设置 DEEPSEEK_API_KEY 环境变量或插件设置。`	No key configured	Set the `DEEPSEEK_API_KEY` environment variable (recommended) or fill in the plugin setting and restart the editor
`请至少选择一个需要 AI 翻译的 Culture。`	No language ticked	Tick at least one language in the AI translation window
`AI 翻译未产生任何译文，请检查 DeepSeek 响应日志。`	The whole run had 0 successes	Verify key/network/model with `CliffLocalizationSuite.AI.TestConnection` first; check the response fragments printed in the log
Some entries have no translation	Empty translation, self-translation or placeholder mismatch refused the write-back	Look at the warnings (`skipped` / `refused` / `mismatch`); confirm the source text and the target language actually match
One `.cliff` was not updated	Still invalid after the AI repair	The log gives `still invalid after repair; not written.`; fix the issues in that file by hand and run again
`AI returned the source unchanged for '…'; self-translation refused.`	The model returned the source text unchanged and the language does not match	Check `Translation Standard` and the prompt; confirm the target language is set correctly
The editor stutters on large batches	HTTP refresh happens synchronously (`FullFlush`)	Lower `Batch Size`, reduce `Max Concurrent Cultures`, and run in batches
The key shows up in a config file	`UDeveloperSettings` writes it in plain text into `Config/DefaultEditor.ini`	Clear the settings field and switch to the environment variable; check that file’s diff before committing

Data consistency

Symptom	Cause	Fix
`manifest` / `archive` were edited by hand and got overwritten on the next import	The official `FLocTextHelper` owns those files	Do not edit them by hand; change the `.cliff` and import again
The sidecar was lost and the keys changed	The `.cliff` and the sidecar were not moved together	Commit and distribute `<Manifest>.cliffmap.json` together with the `.cliff`
`.cliff` conflicts in Git	Two branches changed the same file	Conflicts usually happen on the `target:` and `status:` lines and can be merged semantically; `id` and `group` should not conflict
Import fails in CI but succeeds locally	Missing environment variables, or the target is not configured	Set `DEEPSEEK_API_KEY` in CI and make sure the target configuration under `Config/Localization/` is committed

Diagnostic commands

CliffLocalizationSuite.Hello                  # 模块加载自检
CliffLocalizationSuite.AI.TestConnection      # DeepSeek Key / 网络 / 模型自检
CliffLocalizationSuite.Export <targetName> <outputDirectory>
CliffLocalizationSuite.Import <clifFilePath> <targetName>
CliffLocalizationSuite.AITranslate <targetName> <culture1,culture2,...>

TIP

When filing an issue, attach: editor version, plugin version, the complete log (progress window Save Log...) and a minimal reproducible .cliff fragment (redacted if needed). With the full Copy Log output, the vast majority of problems can be traced down to a specific entry and line number.