リンクの書き換え

translate-docs は、翻訳されたマークダウン内の URL を書き換えるため、ファイルがロケール固有のパスに移動した後もリンクは解決されます。ほとんどのページ間リンクは自動的に処理されます。サイトで共有の静的 URL ツリーまたはロケールコード化されたアセットフォルダーを使用する場合は、docsOutput.postProcessing.regexAdjustments ルールを追加します。

スクリーンショットのディレクトリレイアウト、フラットな深さプレフィックス + ロケールスワップのフロー、およびレイアウト固有のアセット例については、画像とスクリーンショット — リンクの書き換えを参照してください。

組み込みのリライター

実行されるリライターは docsOutput.style によって異なります。

レイアウト	組み込みのリライター	修正内容
`"flat"` (カスタム `pathTemplate` がない場合のデフォルト)	フラットリンクのリライター (`rewriteRelativeLinks`、デフォルトでオン)	ページ間の相対リンク (`guide.md` → `guide.de.md`) およびマークダウン以外のアセット URL の深さプレフィックス
`"vitepress"`	VitePress リンク正規化機能 (`rewriteVitepressLinks`、デフォルトでオン)	README スタイルの `docs/guide/…` パス → サイトルート (`/guide/…`)
`"nextra"`	Nextra リンク正規化機能 (`rewriteNextraLinks`、デフォルトでオン)	`content/en/…` および相対 `.mdx` パス → ロケールに依存しないルート (`/guide/…`)
`"fumadocs"`	Fumadocs リンク正規化機能 (`rewriteFumadocsLinks`、デフォルトでオン)	`content/docs/…` および相対 `.mdx` パス → ロケールに依存しないルート (`/docs/…`)
`"doc-system"`、`"docusaurus"`、`"astro-starlight"`	なし	ソース URL は `postProcessing` まで変更されずに渡されます

カスタム pathTemplate は、rewriteRelativeLinks: true を明示的に設定しない限り、フラットリライターを無効にします。ページ間の #anchor の処理については、「出力レイアウト」と「アンカーリンク」を参照してください。

VitePress固有の執筆ルールについては、VitePress 統合 — リンク規約を参照してください。

Nextra固有の執筆ルールについては、Nextra 統合 — リンク規約を参照してください。

Fumadocs固有の執筆ルールについては、Fumadocs 統合 — リンク規約を参照してください。

`postProcessing.regexAdjustments`

組み込みのリライターでは不十分な場合は、docs[].docsOutput.postProcessing の下に順序付けられた { "description"?, "search", "replace" } ルールを追加します。たとえば、次のようになります。

ロケールフォルダーセグメント を含むスクリーンショットまたは画像 URL (screenshots/en-GB/ → screenshots/de/)
英語のソースツリーと翻訳された出力ツリーで異なる絶対サイトルートパス (/img/…)
ターゲットロケールごとに変更する必要があるが、単純な相対マークダウンリンクではない URL パターン

postProcessing は、再構築された翻訳済みマークダウン本文 (YAML フロントマターキーと非散文値は保持されます) で実行されます。セグメントの再構築と組み込みのリンク書き換えの後、addFrontmatter の前に実行されます。

フラットレイアウトによる 2 段階フロー

docsOutput.style = "flat" の場合、フラットリンクのリライターが最初に実行され、次に regexAdjustments が実行されます。

source URL  →  [flat link rewriter]  →  [regexAdjustments]  →  output URL

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

フラットリライター: images/screenshots/en-GB/foo.png → ../images/screenshots/en-GB/foo.png
regexAdjustments: images/screenshots/[^/]+/ → images/screenshots/${translatedLocale}/ → ../images/screenshots/de/foo.png

すでにプレフィックスが付けられた URL 内のロケールセグメントに一致するように search パターンを記述します。正規表現に ../ の深さプレフィックスを含める必要はありません。

doc-system レイアウトの場合、フラットリライターは実行されません。regexAdjustments は、ソースマークダウンからの元の URL (通常は /img/screenshots/en-GB/foo.png のような絶対パス) を参照します。

深さプレフィックスの動作と flatPreserveRelativeDir については、「フラットリンクのリライターと 2 段階フロー」を参照してください。

`replace` プレースホルダー

replace 文字列は、ファイルごとおよびロケールごとに展開されるテンプレート変数をサポートしています。

プレースホルダー	値
`${translatedLocale}`	ターゲットロケール (正規化された BCP-47)
`${sourceLocale}`	ソースロケール
`${sourceFullPath}`	絶対ソースファイルパス (POSIX `/`)
`${translatedFullPath}`	絶対翻訳出力パス
`${sourceFilename}` / `${translatedFilename}`	拡張子付きのベース名
`${sourceBasedir}` / `${translatedBasedir}`	ソース/出力ファイルの親ディレクトリ

search は正規表現パターンです。プレーンな文字列は g フラグを使用します。他のフラグが必要な場合は /pattern/flags を使用してください (パターンにエスケープされていない / 文字を含めることはできません)。

一般的なパターン

ロケールごとのアセットフォルダー

最初からロケールコード付きのサブディレクトリにアセットを保存し、1つの汎用ルールでセグメントを交換します。

json

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

ソースロケール (en-GB) をハードコーディングするのではなく、[^/]+ を使用すると、sourceLocale が変更されてもルールが機能します。

完全なチュートリアル: 画像とスクリーンショット — ロケールごとのフォルダー。

ドキュメントシステムの静的 URL

Docusaurus、Starlight、または共有静的ツリーからスクリーンショットを提供するその他の doc-system サイトの場合:

json

"postProcessing": {
  "regexAdjustments": [
    {
      "description": "Locale segment in static screenshot URLs",
      "search": "screenshots/[^/]+/",
      "replace": "screenshots/${translatedLocale}/"
    }
  ]
}

ジェネレーターがサポートしている場合は、ソースマークダウンで併置された相対パス (../assets/name.png) を優先してください。そうすれば、regexAdjustments ブリッジは必要ありません。画像とスクリーンショットでレイアウトの選択肢を参照してください。

正規表現が不要な場合

通常、次の場合には regexAdjustments は不要です。

ページ間のリンクが単純な相対マークダウンパスであり、docsOutput.style = "flat" (組み込みのリライターがロケールサフィックスを追加します)
アセットがソースファイルの横にあり、フラットリライターのファイルごとの深さプレフィックスがそれらを正しく解決します
英語とすべての翻訳されたコピーが同じ URL を使用している (サイトルートの共有画像、併置されたアセット、正規化後の VitePress サイトルート)
VitePress のサイト内リンクがサイトルートまたは docs/guide/… パスを rewriteVitepressLinks: true とともに使用している
Nextra および Fumadocs のページ内リンクでは、ロケールに依存しないルート (/guide/…、/docs/…) または rewriteNextraLinks / rewriteFumadocsLinks: true を使用したコンテンツルートパスを使用します。

完全な設定例

ロケールごとのスクリーンショットとオプションの言語スイッチャーブロックを含むフラットなREADME：

フラットレイアウト: regexAdjustments + languageListBlock

json

"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ],
    "languageListBlock": {
      "start": "<small id=\"lang-list\">",
      "end": "</small>",
      "separator": " · ",
      "label": "local"
    }
  }
}

フィールドリファレンス: 設定 — docs (docsOutput.postProcessing)。

トラブルシューティング

症状	考えられる原因	確認事項
翻訳されたページで画像または静的アセットが404エラーになる	URLレイアウトの`regexAdjustments`がないか、間違っている	画像とスクリーンショット — トラブルシューティング
リンクは正しいファイルを開くが、`#section`が間違っている	アンカースラッグのずれ、URL書き換えではない	アンカーリンク
`regexAdjustments`ルールがフラットレイアウトに影響しない	`search`は書き換え前のURLを想定しているが、フラットレイアウトはすでに深さプレフィックスを追加している	プレフィックス付きパス内のセグメントを一致させる（2段階フローを参照）
実行時に無効な正規表現がスキップされる	不正な形式の`search`パターン	CLIはルール`description`で警告します。サンプル翻訳出力に対してパターンをテストしてください

UI文字列

ドキュメント

統合

画像とスクリーンショット

SVG翻訳

翻訳ダッシュボード

リンクの書き換え

組み込みのリライター

`postProcessing.regexAdjustments`

フラットレイアウトによる 2 段階フロー

`replace` プレースホルダー

一般的なパターン

ロケールごとのアセットフォルダー

ドキュメントシステムの静的 URL

正規表現が不要な場合

完全な設定例

トラブルシューティング

UI文字列

ドキュメント

リンクの書き換え ​

組み込みのリライター ​

postProcessing.regexAdjustments ​

フラットレイアウトによる 2 段階フロー ​

replace プレースホルダー ​

一般的なパターン ​

ロケールごとのアセットフォルダー ​

ドキュメントシステムの静的 URL ​

正規表現が不要な場合 ​

完全な設定例 ​

トラブルシューティング ​

リンクの書き換え

組み込みのリライター

`postProcessing.regexAdjustments`

フラットレイアウトによる 2 段階フロー

`replace` プレースホルダー

一般的なパターン

ロケールごとのアセットフォルダー

ドキュメントシステムの静的 URL

正規表現が不要な場合

完全な設定例

トラブルシューティング