ドキュメント

主にMarkdown、MDX、および.astroドキュメント用に設計されており、docs[]設定ブロックを通じて管理されます。各ブロックのcontentPathsフィールドには、翻訳するファイルまたはフォルダーがリストされます。

Docusaurus サイトでは、docusaurusCatalogDir を write-translations カタログフォルダ（例: docs-site/i18n/en）に設定します。これにより、translate-docs にはナビバー、フッター、テーマ文字列などのシェル JSON も含まれます。

VitePress サイトでは、ページ本文は同じ docs[] パイプラインを使用します。ナビ、サイドバー、フッターのラベルは docsOutput.vitepressThemeCatalog に存在し、translate-docs は英語カタログをブートストラップしてページと一緒に翻訳するため、別のパイプラインは不要です。

Nextra サイトでは、ページ本文は docsOutput.style: "nextra" を伴う同じ docs[] パイプラインを使用します。_meta.ts サイドバーのラベルは translate-docs によって自動的に収集および翻訳されます。テーマ辞書の文字列は、同じパイプライン内で docs[].nextraDictionaryPath を介して翻訳されます。

Fumadocs サイトでは、ページ本文は fumadocsParser "dot" (デフォルト) または "dir" を伴う docsOutput.style: "fumadocs" を使用します。meta.json サイドバーのラベルは自動的に収集されます。UI オーバーライドは docsOutput.fumadocsUiCatalog を介して翻訳されます。

Astro Starlight サイトでは、ページ本文は Starlight コンテンツルート（通常は src/content/docs/）にある docsRoot と共に docsOutput.style: "astro-starlight" を使用します。translate-docs は、英語ツリーの隣にある src/content/docs/<locale>/ の下にローカライズされた markdown/MDX を書き込みます。Starlight は多くのロケール向けの組み込み UI 文字列を出荷しているため、別のテーマカタログパイプラインは不要です。オプションの UI オーバーライドは、src/content/i18n/en.json の docs[] ブロックで jsonPathTemplate を使用できます。

Markdownに埋め込まれたPNGやその他のラスター画像については、画像とスクリーンショットを参照してください。translate-docsは代替テキストのみを翻訳し、ラスターファイルをコピーしません。

README またはドキュメント内のオプションの 言語スイッチャー ブロックについては、docsOutput.style を "flat" に設定してください - 言語スイッチャー を参照してください。

SVG ファイルは、features.translateSVG が有効な場合に translate-svg を介して翻訳されます - docs[] / contentPaths は経由しません。

ドキュメントフレームワークのシェル/テーマ文字列とは無関係な任意のネストされたUI JSONバンドルは、docs[]ではなく、JSONパイプラインに属します。

UIとドキュメント間の用語の一貫性を確保するため、glossary.uiGlossaryをstrings.jsonパスに設定します。— translate-docsは、セグメントに一致する用語が含まれている場合、既存のUI翻訳をLLMプロンプトのヒントとして再利用します。オプションのglossary.userGlossaryは、製品用語のCSVオーバーライドを追加します（translate-uiおよびproofread-uiと共有されます）。狭い列に合わせるために使用されるコンパクトなUIラベル略語（例：Size → Tam）は、UI翻訳では引き続き使用できますが、ドキュメントの用語集ヒントからは除外されます。glossary-generateを使用してスターターCSVを生成し、翻訳ダッシュボードの用語集タブで行を編集するか、または設定 — glossaryおよび用語集を参照してください。

ロケールごとのモデルオーバーライド

translate-docs と sync のドキュメントステップは、ターゲットロケールごとに モデルを解決します。設定されている場合は最初に localeModels(locale)、次にプロバイダーのグローバルな translationModels チェーンが使用されます。特定の言語がデフォルトのフォールバックリストとは異なるモデルを必要とする場合にこれを使用します。例えば、グローバルチェーンがポルトガル語の処理に苦戦する場合、pt-BR ドキュメントには Gemini を優先します。プロバイダーとモデル および 設定 - localeModels を参照してください。

読むべきガイド

あなたのセットアップ	ここから始める
Docusaurus サイト	init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
VitePress サイト	テーマ用に init -t ui-vitepress + vitepressThemeCatalog - VitePress
Nextra サイト	辞書用に init -t ui-nextra + nextraDictionaryPath (サイドバー _meta.ts は自動) - Nextra
Fumadocs サイト	UI 用に init -t ui-fumadocs + fumadocsUiCatalog (サイドバー meta.json は自動) - Fumadocs
Astro Starlight	init -t ui-starlight - Astro Starlight
フラットなドキュメント (README、変更履歴など)	docsOutput.style = "flat" - 出力レイアウト、オプションの 言語スイッチャー
翻訳されたファイルの保存場所	出力レイアウト
ページ間の#anchorリンク	アンカーリンク
リンクとアセットの URL 書き換え (regexAdjustments)	リンクの書き換え
ドキュメント内のスクリーンショット	画像とスクリーンショット
製品用語とUI/ドキュメントの一貫性	設定 — glossary、用語集
translate-docsフラグとキャッシュ	CLIオプション

ステップ1: ドキュメントの初期化

ai-i18n-tools init -t ui-docusaurus [-P <provider>]

Astro Starlight ドキュメントサイトの場合：

ai-i18n-tools init -t ui-starlight [-P <provider>]

VitePressドキュメントサイトの場合:

ai-i18n-tools init -t ui-vitepress [-P <provider>]

ナビ/サイドバー/フッター文字列のために docsOutput.vitepressThemeCatalog を設定します - VitePress 統合 を参照してください。

Nextraドキュメントサイトの場合:

ai-i18n-tools init -t ui-nextra [-P <provider>]

テーマ辞書文字列のために docs[].nextraDictionaryPath を設定します - Nextra 統合 を参照してください。サイドバーの _meta.ts ラベルは自動的に収集されます。

Fumadocsドキュメントサイトの場合:

ai-i18n-tools init -t ui-fumadocs [-P <provider>]

UI オーバーライドのために docsOutput.fumadocsUiCatalog を設定します - Fumadocs 統合 を参照してください。サイドバーの meta.json ラベルは自動的に収集されます。

プレーンなAstroウェブサイトUI（Starlightなし）の場合：

ai-i18n-tools init -t ui-astro-website [-P <provider>]

このテンプレートはUI抽出のみを有効にします。ページHTMLの翻訳には、features.translateDocsも設定し、docs[]ブロックを追加します（Astroウェブサイトページ (解析と置換)を参照）。examples/astro-website設定は、両方のパイプラインを一緒に示しています。

生成されたai-i18n-tools.config.jsonを編集します。

• provider と providers — init はデフォルトのプロバイダーブロックをスキャフォールドします (-P <provider> を渡さない限り openrouter)。translate-docs または sync の前に、少なくとも1つのプロバイダーを設定し、その API キーを設定してください (Ollama はキー不要)。プロバイダーと API キー および LLM プロバイダーとモデル を参照してください。
• sourceLocale - ソース言語 (docusaurus.config.js の defaultLocale と一致する必要があります)。
• targetLocales - BCP-47 ロケールコードの配列 (例: ["de", "fr", "es"])。
• cacheDir - すべてのパイプラインの共有 SQLite キャッシュディレクトリ (および --write-logs のデフォルトログディレクトリ)。
• docs - ドキュメントブロックの配列。各ブロックにはオプションのdescription、contentPaths（文字列または配列、ファイル、ディレクトリ、またはglob）、outputDir、オプションのdocusaurusCatalogDir、docsOutput、オプションのsegmentSplitting、translateFrontmatterFields、protectAttributes、protectKeys、targetLocales、addFrontmatterなどがあります。
• docs[].description - メンテナ向けのオプションの短いメモ。設定すると、translate-docsの見出しとstatusのセクションヘッダーに表示されます。
• docs[].contentPaths - markdown/MDX/.astroソース（およびDocusaurusシェルJSON用のオプションのdocusaurusCatalogDir）。
• docs[].outputDir - そのブロックの翻訳出力ルート。
• docs[].docsOutput.style - "nested" (デフォルト), "flat", "doc-system", またはエイリアス "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs" (出力レイアウト を参照)。
• glossary.uiGlossary - strings.json へのパス。これにより、ドキュメントセグメントは UI カタログから用語のヒントを得られます (設定 — glossary を参照)。
• glossary.userGlossary - 固定の製品用語翻訳用のオプション CSV。UI パイプラインでも使用され、用語集 ダッシュボードタブで編集可能です。

プライマリ対サプライメンタリ： ローカライズされたページには contentPaths を使用してください。write-translations から Docusaurus シェルの JSON も必要な場合は、docusaurusCatalogDir を設定します。ページの翻訳のみを行う場合は、docusaurusCatalogDir を省略してください。

ステップ2: ドキュメントを翻訳する

ai-i18n-tools translate-docs

これは、すべての docs[] ブロックの contentPaths 内のすべてのファイル（および docusaurusCatalogDir が設定されている場合の Docusaurus カタログ JSON）を、すべての有効なドキュメントロケールに翻訳します。すでに翻訳されたセグメントは SQLite キャッシュから提供され、新規または変更されたセグメントのみが LLM に送信されます。

単一のロケールを翻訳するには：

ai-i18n-tools translate-docs --locale de

翻訳が必要な内容を確認するには：

ai-i18n-tools status

フラグ、キャッシュの動作、およびバッチプロンプトの形式については、CLIオプションを参照してください。

複雑なMarkdownと品質チェックの失敗

translate-docsは、翻訳された各セグメントがMarkdownの構造（ドキュメントから解析された強調を含む）を保持し、内部のプレースホルダートークンが正しく復元されるかどうかをチェックします。`inline code`の周囲に多数のboldスパンを重ねたり、太字の中にバッククォートをネストしたり（例えば`fetch(\`/locales/${code}.json\`)`のようなテンプレートリテラル）、1つの長い文の中に太字とコードを織り交ぜたりする段落は脆弱です。一部のロケールでは異なる語順が必要になるため、翻訳後に**と`の並びが変わり、AST mismatchのようなCLIエラーがトリガーされる可能性があります。

復元後、translate-docsは、HTMLタグのプレースホルダーが再利用または削除されたセグメント（そのため復元されたタグがソースマップと一致しなくなる）、またはモデルがソースに存在しない二重中括弧トークンを捏造したセグメント（例えば、架空の用語集スタイルのトークン）も拒否します。復元前のチェックでは、{{…}}トークンの同じ多重集合と、構造トークン（{{HTM_N}}、警告マーカー）の同じ順序付けられたサブシーケンスが必要です。{{ILC_N}}や{{URL_N}}などのコンテンツトークン、および**のような強調マーカーは、各ID/タイプの数が一致する限り、自然な語順に合わせて移動できます。これらの失敗は、残存する公式内部トークンと同じモデルフォールバックパスを使用します。

そのような検証エラーが発生した場合は、ソース言語のテキストを簡略化することをお勧めします - 段落を分割する、例をコードブロックに移動する、または階層化された太字/コードのペアを減らして同じ概念を説明するなど - すべてのモデルとロケールが密集したインラインマークアップを完全に再現することを期待するのではなく。

すべての構成済みモデルが同じセグメントで AST mismatch エラーを発生させた場合、translate-docs はそのセグメントをより小さい部分に自動的に分割できます（最初にリストの中間点、次に個々のリスト項目または短い段落のチャンク）。その後、各部分を最初のモデルから再試行し、元のセグメントキャッシュキーの下で結果を再結合します。これはデフォルトで有効になっています（segmentSplitting.qualityRetrySplit）。モデルを使い切った後に停止するには、false に設定してください。このフォールバックが実行された場合、実行サマリーに Quality split retries が報告されます。

どのセグメントが失敗したか、その頻度、および保存されている品質/エラーメッセージを確認するには、翻訳ダッシュボードの失敗タブ（翻訳ダッシュボード → 失敗）を使用します。