フラットリンク書き換えと2段階フロー

スクリーンショットのURLレイアウトとフラットな2ステップのアセットフローについてはこのページを参照してください。ページ間のMarkdownリンクとreplaceプレースホルダーについては、ドキュメント — リンクの書き換えを参照してください。

docsOutput.style = "flat"の場合（およびrewriteRelativeLinks: falseまたはカスタムpathTemplateが設定されていない限り）、組み込みのリライターはpostProcessingの前に実行されます。これは、ドキュメント間のリンクを処理し（ロケールサフィックスを追加）、非マークダウンアセットURLに深さプレフィックスを付加します。ロケール固有のアセットパス（スクリーンショット、/img/…ブリッジ）は、その後docsOutput.postProcessing.regexAdjustmentsによって書き換えられます。

docsOutput.style = "flat"時の2段階の処理フロー

1. ソースURL — 翻訳済みMarkdown内の画像パス（セグメント再構築後）
2. フラットリンクリライター — 深度プレフィックスを付加（../, ../../docs/, …）
3. regexAdjustments — ロケールフォルダーセグメントを置換（en-GB → ${translatedLocale}）
4. 出力URL — 翻訳済みファイルに書き込まれる最終パス

outputDir: "translated-docs/"かつソースREADME.mdがリポジトリのルートにある場合の例：

1. フラットリンクリライター: images/screenshots/en-GB/foo.png → ../images/screenshots/en-GB/foo.png (translated-docs/に1つの../)
2. regexAdjustmentsルールimages/screenshots/[^/]+/ → images/screenshots/${translatedLocale}/: ../images/screenshots/de/foo.png

flat以外のスタイル（"nested"、"doc-system"、および"docusaurus"、"astro-starlight"、"vitepress"などのプリセットを含む）の場合、フラットリンクリライターは実行されません。regexAdjustmentsは翻訳済みMarkdownの元のURL（通常は/img/screenshots/en-GB/foo.pngのような絶対パス）をそのまま認識します。

Astro Starlight MDX: Starlightのコンテンツはしばしば.mdxです。これらのファイルに対して、translate-docsはpostProcessing.regexAdjustmentsのみを実行します — フラット、VitePress、Nextra、またはFumadocsのリンクリライターは実行されません。ロケールごとのスクリーンショットパスは引き続き同じscreenshots/[^/]+/ → screenshots/${translatedLocale}/ルールを使用します。examples/astro-docsを参照してください。

VitePress リンク正規化機能 (style: "vitepress")

docsOutput.rewriteVitepressLinksがtrue（styleが"vitepress"の場合のデフォルト）の場合、セグメントの再構成後に（フラットなリライターではなく）別のノーマライザーが実行されます。これは、英語がコンテンツルートにあり、ロケールが兄弟フォルダー（docs/de/guide/…）にあるVitePress / ドキュメントシステムサイトを対象としています。

1. ソースhref — 翻訳済みMarkdown内のリンク（セグメント再構築後）
2. VitePressリンクノーマライザー — ドキュメントパスをサイトルートに書き換え（/guide/…）
3. regexAdjustments — スクリーンショットのオプションのロケールフォルダー置換（screenshots/en-GB/ → screenshots/de/, …）
4. 出力href — 翻訳済みファイルに書き込まれる最終URL

一般的な書き換え:

ソースパターン	正規化されたターゲット
docs/guide/foo.md	/guide/foo
../guide/foo.md (ロケールファイルから)	/guide/foo
https://github.com/…/examples/console-app/	変更なし（リポジトリパスには完全なURLを使用）

README.md → docs/index.md を同期するプロジェクトでは、VitePressツリー外の LICENSE、examples/、およびその他のファイルの README.md において完全なGitHub URLを使用してください。VitePress integration — README as the docs homepage を参照してください。

フラットリライターとVitePressノーマライザーは、docs[] ブロックごとに相互排他であり、regexAdjustments の前に実行されるのはどちらか一方のみです。VitePress integration — Link conventions を参照してください。

ロケールごとのスクリーンショットフォルダーは、必要に応じて引き続き同じscreenshots/[^/]+/ → screenshots/${translatedLocale}/ regexAdjustmentsルールを使用します。ロケールごとのフォルダーを参照してください。

Nextra リンク正規化機能 (style: "nextra")

docsOutput.rewriteNextraLinks が true の場合（style が "nextra" の時のデフォルト）、セグメント再構築後に別のノーマライザーが実行されます。これは content/en/… と相対 .mdx パスをロケール中立のルート（/guide/…）に書き換えます。Nextra integration — Link conventions を参照してください。

Fumadocs リンク正規化機能 (style: "fumadocs")

docsOutput.rewriteFumadocsLinks が true の場合（style が "fumadocs" の時のデフォルト）、セグメント再構築後に別のノーマライザーが実行されます。これは content/docs/… と相対 .mdx パスをロケール中立のルート（/docs/…）に書き換えます。Fumadocs integration — Link conventions を参照してください。

ファイルごとの深さ接頭辞とflatPreserveRelativeDir

深さ接頭辞はバッチ全体に対してグローバルにではなく、出力ファイルごとに個別に計算されます。各ソースファイルについて、リライターは出力ファイルのディレクトリからソースファイルのディレクトリへの相対パスを計算し、それを接頭辞として使用します。

これは、flatPreserveRelativeDir: true を使用すると、サブディレクトリ内のソースファイルに正しいプレフィックスが自動的に付加されることを意味します。たとえば、docs/guide/quick-start.md は translated-docs/docs/guide/quick-start.<locale>.md に出力されます。ファイルごとのプレフィックスは ../../docs/ なので、アセット translation-dashboard.png (ソースツリーの兄弟) は ../../docs/translation-dashboard.png になります。これは translated-docs/docs/guide/ から docs/translation-dashboard.png に正しく解決されます。

ソースファイルと並行する相対パスアセットの場合、regexAdjustmentsの修正は不要です。

rewriteRelativeLinksおよびlinkRewriteDocsRoot

オプション	効果
docsOutput.rewriteRelativeLinks	フラットリンクリライターを明示的に有効または無効にします（docsOutput.style = "flat"時の既定値を上書き）
docsOutput.linkRewriteDocsRoot	depthPrefixの計算元となるルート（既定値は"."）
docsOutput.flatPreserveRelativeDir	出力パスのレイアウトに影響し、リライターは既知の翻訳済みファイルのターゲットパスを計算する際にこのレイアウトを使用します

docsOutput.postProcessing.regexAdjustments

組み込みのリライターが処理しない画像、スクリーンショット、その他のアセットURLを書き換えるには、docs[].docsOutput.postProcessingの下に順序付けられた{ "description"?, "search", "replace" }ルールを設定します。通常、ロケールフォルダセグメントを交換する（screenshots/en-GB/ → screenshots/de/）か、絶対静的パスをブリッジする（/img/… → ../assets/…）ことになります。

ルールは、セグメントの再構成と組み込みのリンク書き換え（フラットまたはVitePress）の後、およびaddFrontmatterの前に、翻訳されたマークダウンの本文で実行されます。フラットレイアウトでは、深さプレフィックスが適用された後のURLに対してsearchパターンを記述します。先頭の../ではなく、パス内のロケールセグメントに一致させます。

ロケールごとのスクリーンショットフォルダ（フラットレイアウト）:

"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ]
  }
}

ソースロケール（en-GB）をハードコーディングする代わりに[^/]+を使用すると、ルールがsourceLocaleの変更後も機能します。最も一般的なプレースホルダーは${translatedLocale}です。${sourceLocale}、${sourceFilename}、${translatedFilename}、およびパス変数も利用できます。ドキュメント — リンクの書き換えを参照してください。

レイアウト固有の例（フラット、ドキュメントシステム、Docusaurus、Starlight）: ロケールごとのフォルダ。一般的なページ間リンクルール: ドキュメント — リンクの書き換え。フィールドリファレンス: 設定 — docs。

---

ハードコードされたロケール正規表現、不足しているスクリーンショットディレクトリ、およびDocusaurusの/img/ブリッジについては、よくある間違いとトラブルシューティングを参照してください。