フラットリンク書き換えと2段階フロー
スクリーンショットのURLレイアウトとフラットな2ステップのアセットフローについてはこのページを参照してください。ページ間のMarkdownリンクとreplaceプレースホルダーについては、ドキュメント — リンクの書き換えを参照してください。
docsOutput.style = "flat"の場合(およびrewriteRelativeLinks: falseまたはカスタムpathTemplateが設定されていない限り)、組み込みのリライターはpostProcessingの前に実行されます。これは、ドキュメント間のリンクを処理し(ロケールサフィックスを追加)、非マークダウンアセットURLに深さプレフィックスを付加します。ロケール固有のアセットパス(スクリーンショット、/img/…ブリッジ)は、その後docsOutput.postProcessing.regexAdjustmentsによって書き換えられます。
docsOutput.style = "flat"時の2段階の処理フロー
- ソースURL — 翻訳済みマークダウン内の画像パス(セグメント再構成後)
- フラットリンクリライター — 深さプレフィックスを先頭に追加(
../、../../docs/、…) regexAdjustments— ロケールフォルダセグメントを入れ替える(en-GB→${translatedLocale})- 出力URL — 翻訳ファイルに書き込まれる最終パス
outputDir: "translated-docs/"かつソースREADME.mdがリポジトリのルートにある場合の例:
- フラットリンクリライター:
images/screenshots/en-GB/foo.png→../images/screenshots/en-GB/foo.png(translated-docs/に1つの../) 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/ドキュメントシステムサイトを対象としています。
- ソースhref — 翻訳されたMarkdown内のリンク (セグメント再構成後)
- VitePress リンク正規化ツール — ドキュメントパスをサイトルートに書き換える (
/guide/…) regexAdjustments— スクリーンショット用のオプションのロケールフォルダー入れ替え (screenshots/en-GB/→screenshots/de/、…)- 出力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 の統合 — ドキュメントのホームページとしての README を参照してください。
フラット書き換えツールとVitePress正規化ツールは、docs[]ブロックごとに相互排他的であり、regexAdjustmentsの前にいずれか一方のみが実行されます。VitePress連携 — リンク規約を参照してください。
ロケールごとのスクリーンショットフォルダーは、必要に応じて引き続き同じscreenshots/[^/]+/ → screenshots/${translatedLocale}/ regexAdjustmentsルールを使用します。ロケールごとのフォルダーを参照してください。
Nextraリンク正規化ツール(style: "nextra")
docsOutput.rewriteNextraLinksがtrueの場合(styleが"nextra"の場合のデフォルト)、セグメント再構成後に別の正規化ツールが実行されます。これは、content/en/…と相対的な.mdxパスをロケールに依存しないルート(/guide/…)に書き換えます。Nextra連携 — リンク規約を参照してください。
Fumadocsリンク正規化ツール(style: "fumadocs")
docsOutput.rewriteFumadocsLinksがtrueの場合(styleが"fumadocs"の場合のデフォルト)、セグメント再構成後に別の正規化ツールが実行されます。これは、content/docs/…と相対的な.mdxパスをロケールに依存しないルート(/docs/…)に書き換えます。Fumadocs連携 — リンク規約を参照してください。
ファイルごとの深さ接頭辞と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/ブリッジについては、よくある間違いとトラブルシューティングを参照してください。