ドキュメント

主に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 で共有）。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構造（文書から解析された強調も含む）を保持しているかをチェックします。多くのboldスパンが`inline code`の周囲に重なっている段落、太字内にバッククォートがネストしている（たとえばテンプレートリテラル`fetch(\`/locales/${code}.json\`)`など）、または長い文のなかで太字とコードが複雑に交じっている場合、構造は脆弱です。一部のロケールでは語順が異なる必要があり、翻訳後に**と`の位置関係が変化してAST mismatchなどのCLIエラーを引き起こす可能性があります。

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

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

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