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	このパスの下でのみマークダウン/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	翻訳前にマークダウン強調マーカーをプレースホルダーとしてマスクします。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 は、翻訳可能なセグメントをアクティブな LLM プロバイダーにバッチ（batchSize / maxBatchChars でグループ化）で送信します。--prompt-format フラグは、そのバッチのワイヤー形式のみを変更します。PlaceholderHandler トークン、マークダウン AST チェック、SQLite キャッシュキー、およびバッチ解析が失敗した場合のセグメントごとのフォールバックは変更されません。

モード	ユーザーメッセージ	モデルの応答
xml	ダミーXML形式: セグメントごとに1つの <seg id="N">…</seg> (XMLエスケープ済み)。	セグメントインデックスごとに1つの <t id="N">…</t> ブロックのみ。
json-array (デフォルト)	順序通りのセグメントごとに1つのエントリを持つJSON配列。	同じ長さのJSON配列（同じ順序）。
json-object	セグメントインデックスをキーとするJSONオブジェクト {"0":"…","1":"…",…}。	同じキーと翻訳された値を持つJSONオブジェクト。

一部のモデルは別のフォーマットよりも特定のフォーマットに確実に従うため、モデルが頻繁に不正なバッチや不一致のセグメントIDを返す場合は、別のモードを試してください。json-arrayは、モデルが一般的にうまく処理できる一般的でシンプルなフォーマットであるため、デフォルトとなっています。

実行ヘッダーには Batch prompt format: … も表示されるため、アクティブなモードを確認できます。JSON ラベルファイル (docusaurusCatalogDir) と SVG ファイルバッチは、これらのステップが translate-docs (または sync のドキュメントフェーズ — sync はこのフラグを公開しません。デフォルトは json-array です) の一部として実行される場合、同じ設定を使用します。