AI Translation Setup

Every AI-related setting lives under Edit > Project Settings > Plugins > CLIFF Localization Suite > AI Translation. This page explains what each parameter does and how to tune it; the complete field list is in the settings reference.

Credentials and endpoint

Setting	Default	Description
DeepSeek API Key	empty	When left empty the DEEPSEEK_API_KEY environment variable is read
DeepSeek Base URL	https://api.deepseek.com	The official address; a trailing /v1 is joined correctly as well
DeepSeek Model	deepseek-flash	Model name

Key resolution order: the DEEPSEEK_API_KEY environment variable → the plugin setting field. A custom environment variable name is not supported.

WARNING

UDeveloperSettings writes the field in plain text into Config/DefaultEditor.ini. Clear DeepSeek API Key before committing to the repository and switch to the environment variable instead. The plugin guarantees the key never appears in logs, is never written into the GatherText configuration, and never appears in any process command line.

Thinking level

Thinking Level controls DeepSeek’s reasoning cost:

Value	Request behaviour
关闭 (default)	thinking.type = disabled, using the official translation recommendation temperature = 1.3
低	thinking.type = enabled + reasoning_effort = low
高	thinking.type = enabled + reasoning_effort = high (DeepSeek’s own default)
最高	thinking.type = enabled + reasoning_effort = max (quality first, longer runtime)

Recommendation: for game UI text 关闭 is enough (faster and cheaper); try 高 once you hit plenty of long sentences, puns or terminology-dense text.

Prompt and translation standard

System Prompt

• Left empty → the built-in default prompt is used (written in English; it emphasises mixed-language detection, strict placeholder preservation, not translating class/variable names or paths, and returning JSON only)
• Filled in → completely replaces the default prompt
• The settings panel has no “Restore Default Prompt” button; if you break the prompt, clear the field and the built-in default comes back

The built-in default prompt requires the model to return exactly this shape:

{"translations": [{"id": "...", "translation": "..."}]}

Translation Standard

Translation Standard has two effects:

1. It is written into the header’s standard: field when exporting CLIFF, so the translation files carry their style requirements with them
2. It is appended to the end of the System Prompt when sending a request (as a === Translation Standard === section)

示例：游戏 UI 使用简体中文，保留英文专有名词与品牌名，不使用方言，按钮文本不超过 8 个汉字。

TIP

Put “glossary, person, punctuation style, prohibitions” into Translation Standard rather than stuffing them into the System Prompt: the former travels with the .cliff files and is visible to external translators or other tools, while the latter only affects AI requests from this machine.

Request body structure

The plugin’s transport implementation is DeepSeek’s OpenAI-compatible POST {BaseUrl}/chat/completions:

{
  "model": "deepseek-flash",
  "messages": [
    { "role": "system", "content": "<System Prompt + Translation Standard>" },
    { "role": "user",   "content": "[{\"id\":\"1\",\"source\":\"Play\",\"context\":\"Main menu button\"}]" }
  ],
  "thinking": { "type": "disabled" },
  "temperature": 1.3,
  "stream": false,
  "max_tokens": 8192,
  "response_format": { "type": "json_object" }
}

Detail	Value	Reason
max_tokens	Fixed at 8192	A truncated long JSON translation set would fail the parsing of the whole batch
response_format	json_object	Forces JSON output
stream	false	The commandlet collects results with a unified event loop
thinking / temperature	See the table above	temperature = 1.3 is only used when thinking is off
context field	Controlled by Include Context	When off only id and source are sent, saving tokens

Batch protocol: one request carries a batch of entries (Batch Size, default 20), each with an id (canonical ID), source and optionally context; the user content also states Source language / Target language and the “mixed-language authoring” rule, and requires the model to return all the ids from the input. Response parsing order: a JSON array itself → a translations / results / data / items array inside an object → falling back to the substring between the first [ and the last ]. An empty array is a legal result.

Failure fallback: per-batch retry (up to Max Retries times, with a growing delay of 0.5s / 1.0s / …) → if the batch still fails it is skipped with a warning → after the whole round, one more round runs automatically (up to Max Retries rounds), handling only the entries that still have no translation.

Batch, concurrency and timeouts

Setting	Default	Tuning advice
Batch Size	20	Short entries allow 30–50; with long sentences or dense terminology lower it to 10 to reduce the risk of JSON truncation
Max Concurrent Cultures	4	Upper bound on concurrent batches (the implementation chunks batches and sends them concurrently, then waits for all of them); drop to 2 when the API rate-limits
Request Timeout	60 seconds	Raise to 120 when thinking is enabled or batches are large
Max Retries	3	Keep 3 on unstable networks; drop to 1 in CI to fail fast
Include Context	on	Turning it off saves a lot of tokens but costs register/tone accuracy

Repair and retranslation

Setting	Default	Description
Auto Repair CLIFF	on	When AI-produced CLIFF fails validation, the original text plus the issue list is handed back to the model for repair
Max Repair Attempts	2	Maximum repair rounds per file; beyond that the file is marked failed and is not imported
Retranslate Self Translations	on	Treats entries with target == source whose language does not match as pseudo-translations and retranslates them; reviewed / final are never touched

Details in write-back safety and repair.

Test connection

There is no connection-test button in the settings panel; the console command is the only entry point:

CliffLocalizationSuite.AI.TestConnection

Output: success/failure, HTTP status, model name and elapsed time. When the key is missing it reports:

AI 翻译缺少 DeepSeek API Key；请设置 DEEPSEEK_API_KEY 环境变量或插件设置。

Translation statistics

At the end of every run the commandlet prints one summary line (identical in the GUI and the CLI):

AI translation succeeded: <候选> candidates, <已翻译> translated, <失败> failed, <修复> repairs.

Meaning of the statistics fields: CandidateCount (candidate entries that entered a request), TranslatedCount, SkippedCount (existing translations that were skipped), FailedCount, RepairCount, BatchCount, FailedFiles.

Cost control advice

1. Fill in only what is missing: the plugin does not overwrite existing translations by default, so repeated runs do not pay twice
2. Trial a small batch first: one language + Batch Size = 5 + Max Retries = 1, confirm the prompt and terminology, then run the full set
3. Turn Context off: when the entries explain themselves well enough, the saved tokens are considerable
4. Use 关闭 thinking: short UI strings gain almost nothing from reasoning
5. Write the terminology into Translation Standard: cheaper than letting the model improvise and paying for retranslation