CLI オプション

translate-docs のキャッシュ動作、フラグ、バッチプロンプト形式、および内部 SQLite パスキーのリファレンス。

キャッシュ動作と translate-docs フラグ

CLI は、SQLite にファイル追跡（ファイルごとのソースハッシュ × ロケール）とセグメント行（翻訳可能なチャンクごとのハッシュ × ロケール）を保持します。通常の実行では、追跡されたハッシュが現在のソースと一致し、出力ファイルが既に存在し、かつ出力の変更時刻がソースの変更時刻以降である場合、ファイルを完全にスキップします。それ以外の場合は、ファイルを処理し、セグメントキャッシュを使用して、変更されていないテキストが API を呼び出さないようにします。

フラグ	機能
(デフォルト)	追跡対象とディスク上の出力が一致する場合、変更のないファイルをスキップします。それ以外はセグメントキャッシュを使用します。
-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ログを出力。
--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 です) の一部として実行される場合、同じ設定を使用します。