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（專案相對路徑、絕對路徑或 glob 模式）；--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 強調標記遮罩為佔位符。對於 CJK 和 RTL 語言環境會自動啟用，除非透過 docs[].emphasisPlaceholders 每個區塊覆寫或使用 --no-emphasis-placeholders 停用。
--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	以區段索引為鍵的 JSON 物件 {"0":"…","1":"…",…}。	具有 相同鍵和已翻譯值的 JSON 物件。

某些模型對某種格式的支援比另一種更穩定，因此如果模型經常返回格式錯誤的批次或不相符的區段 ID，請嘗試不同的模式。json-array 是預設值，因為這是一種常見且簡單的格式，大多數模型都能良好處理。

執行標頭也會列印 Batch prompt format: …，以便您可以確認活動模式。JSON 標籤檔案 (docusaurusCatalogDir) 和 SVG 檔案批次在這些步驟作為 translate-docs（或 sync 的文件階段 — sync 不會公開此旗標；它預設為 json-array）的一部分執行時使用相同的設定。