CLI 选项

有关 translate-docs 缓存行为、标志、批处理提示格式和内部 SQLite 路径键的参考。

缓存行为和 translate-docs 标志

CLI 在 SQLite 中维护文件跟踪（每个文件 × 区域设置的源哈希）和片段行（每个可翻译块的哈希 × 区域设置）。在常规运行中，当跟踪的哈希与当前源匹配、输出文件已存在，且输出的修改时间至少与源一样新时，会完全跳过该文件。否则，它会处理该文件并使用片段缓存，以便未更改的文本不会调用 API。当存储的文本未通过脚本验证时，片段缓存命中也会被拒绝。使用 --check-cache 可为具有预期书写系统的区域设置（hi、ja、zh-Hans、ar、…）绕过文件级跳过，从而无需 --force-update 即可重试罗马化或错误脚本的缓存行。

标志	效果
(默认)	当跟踪与磁盘上的输出匹配时跳过未更改的文件；对其余文件使用片段缓存。错误脚本的缓存命中将被拒绝，并仅对正在处理的文件重新翻译。
-l, --locale <codes>	逗号分隔的目标区域设置（省略时，默认值与根 targetLocales 和每个 docs[] 块的可选 targetLocales 的并集匹配）。
-p, --path / -f, --file	仅翻译此路径下的 Markdown/JSON（项目相对路径、绝对路径或通配符模式）；--file 是 --path 的别名。
--dry-run	不进行文件写入，也不调用 API。
--type <kind>	限制为 markdown 或 json（否则，如果在配置中启用了两者，则两者都包含）。
--json-only / --no-json	仅翻译 JSON 标签文件，或跳过 JSON，仅翻译 markdown。
-j, --concurrency <n>	最大并行目标语言（默认为配置或 CLI 内置默认值）。
-b, --batch-concurrency <n>	每个文件（文档）的最大并行批量 API 调用次数（默认为配置或 CLI）。
--emphasis-placeholders	在翻译之前将 Markdown 强调标记屏蔽为占位符。除非通过 docs[].emphasisPlaceholders 针对每个块进行覆盖或通过 --no-emphasis-placeholders 禁用，否则 CJK 和 RTL 区域设置会自动启用。
--debug-failed	全局。为每次失败的翻译检查（脚本错误、解析错误或质量问题）在 cacheDir 下写入详细的 FAILED-TRANSLATION 日志，包括回退情况（如罗马音转写的 zh-Hans/hi）——不仅限于所有模型都失败时。提供商 API 错误将打印到控制台而非文件。同样适用于 sync / sync-ui / cleanup。
--check-cache	即使文件跟踪会跳过，也为具有强制原生脚本的区域设置重新验证缓存的片段。没有预期脚本的区域设置仍会跳过。片段缓存仍然适用。
--force-update	重新处理每个匹配的文件（提取、重组、写入输出），即使文件跟踪会跳过。段缓存仍然适用 — 未更改的段不会发送到 LLM。
--force	清除每个已处理文件的文件跟踪，并且不读取段缓存进行 API 翻译（完全重新翻译）。新结果仍会写入段缓存。
--stats	打印段计数、跟踪文件计数以及每个语言的段总数，然后退出。
--clear-cache [locale]	删除缓存的翻译（和文件跟踪）：所有语言，或单个语言，然后退出。
--prompt-format <mode>	每个批次的段如何发送到模型和解析（xml、json-array 或 json-object）。默认 json-array。不改变提取、占位符、验证、缓存或回退行为 — 请参阅 批量提示格式。

您不能将 --force 与 --force-update 结合使用（它们是互斥的）。

批处理提示格式

translate-docs 以 批次（按 batchSize / maxBatchChars 分组）将可翻译段发送到活动的 LLM 提供程序。--prompt-format 标志仅更改该批次的 有线格式；PlaceholderHandler 令牌、Markdown AST 检查、SQLite 缓存键以及批处理解析失败时的每段回退保持不变。

模式	用户消息	模型回复
xml	伪 XML：每个段一个 <seg id="N">…</seg>（带 XML 转义）。	仅 <t id="N">…</t> 块，每个块对应一个段索引。
json-array (默认)	字符串的 JSON 数组，每个条目按顺序对应一个分段。	长度 相同（顺序相同）的 JSON 数组。
json-object	按分段索引 {"0":"…","1":"…",…} 键控的 JSON 对象。	键相同且值已翻译的 JSON 对象。

某些模型对一种格式的遵循比另一种更可靠，因此如果模型频繁返回格式错误的批次或不匹配的段 ID，请尝试使用不同的模式。json-array 是默认模式，因为它是一种常见、简单的格式，模型通常能很好地处理。

运行标题还会打印 Batch prompt format: …，以便您可以确认活动模式。JSON 标签文件 (docusaurusCatalogDir) 和 SVG 文件批次在这些步骤作为 translate-docs（或 sync 的文档阶段 — sync 不公开此标志；它默认为 json-array）的一部分运行时使用相同的设置。