ロケールごとのフォルダー (URL書き換え)
docsOutput.style = "flat"を使用するREADME/ユーザーガイド、ドキュメントシステムサイト (docsOutput.style = "doc-system" またはエイリアス "docusaurus" / "astro-starlight")、および共有の静的URLツリーからスクリーンショットを提供する"vitepress" / その他のドキュメントシステムプリセットに利用します。VitePressのリンク書き換えの詳細: リンク書き換え — VitePress。
ディレクトリ構成
ロケールごとのスクリーンショットディレクトリツリーの例
images/screenshots/
├── en-GB/
│ ├── translate.png
│ └── settings.png
├── de/
│ ├── translate.png
│ └── settings.png
└── fr/
├── translate.png
└── settings.pngソースのMarkdownはソースロケールのディレクトリを参照します。
スクリーンショットスクリプトの契約
take-screenshotsスクリプトは、ソースロケールだけでなく、すべてのロケールに対してファイルを書き込む必要があります。translate-docsコマンドはパスを書き換えますが、ファイルは作成しません。一般的なヘルパーは次のとおりです。
function getScreenshotDir(locale) {
return `images/screenshots/${locale}`;
}examples/nextjs-app のスクリーンショットスクリプト にあるシンプルな bash の例、または duplistatus プロジェクトの take-screenshots.ts にあるより複雑な例(Transrewrt でも本番環境で使用されています)を参照してください。
注意: 以下の4つのサブセクションは、同じ
regexAdjustmentsロケールセグメントの置換(screenshots/[^/]+/→screenshots/${translatedLocale}/)を共有します。出力レイアウトと、フラットリンクリライターが最初に実行されるかどうかのみが異なります — 該当するdocsOutput.styleに一致するサブセクションにジャンプしてください。注意:
regexAdjustmentsは、フェンスされたコードブロックを含む翻訳済みの完全なマークダウン本文に対して実行されます。ドキュメントページに一致するパスを含む設定例(例:screenshots/en-GB/)が埋め込まれている場合、そのスニペットも翻訳出力で書き換えられます。再利用可能な例では、汎用のscreenshots/[^/]+/形式を優先してください。
設定 - docsOutput.style = "flat"
docsOutput.style = "flat"の場合、フラットリンクリライターが最初に実行され、Markdown以外のURLにディプスプレフィックスが付加されます。リポジトリルートにあるREADME.mdでoutputDir: "translated-docs/"の場合、../が追加されます。
images/screenshots/en-GB/translate.png → ../images/screenshots/en-GB/translate.pngその後、regexAdjustmentsルールがすでにプレフィックスが付加されたURL内のロケールセグメントを置き換えます。
フラットレイアウト用のregexAdjustmentsの例
"docsOutput": {
"style": "flat",
"postProcessing": {
"regexAdjustments": [
{
"description": "Per-locale screenshot folders",
"search": "images/screenshots/[^/]+/",
"replace": "images/screenshots/${translatedLocale}/"
}
]
}
}結果: ../images/screenshots/de/translate.png — translated-docs/README.de.mdからリポジトリルートへの正しい相対パス。
postProcessingステップは、フラットリンク書き換えの後に実行されます。すでにプレフィックスが付いているURL内のどこかにロケールセグメントと一致するsearch正規表現を記述します。正規表現に../プレフィックスを含める必要はありません。
実装例(本番環境): Transrewrt — README.md のスクリーンショット URL (images/screenshots/en-GB/…)、ai-i18n-tools.config.json のロケール書き換え、duplistatus の take-screenshots.ts に基づくキャプチャスクリプト(上記の スクリーンショットスクリプトコントラクト を参照)。
実装例(デモ設定):examples/nextjs-app — ai-i18n-tools.config.json の2番目の docs[] ブロック(images/screenshots/[^/]+/ → ${translatedLocale})。ヘルパースクリプト screenshot-locales.sh。
設定 - docsOutput.style = "doc-system"
共有の静的URLプレフィックスを介してスクリーンショットを参照するすべてのドキュメントシステムサイトで、ロケールごとの同じフォルダアプローチを使用します。フラットリンク書き換えは実行されません。postProcessingは元のマークダウンURLのロケールセグメントを書き換えます。
ドキュメントシステムレイアウト用のregexAdjustmentsの例
"docsOutput": {
"style": "doc-system",
"docsRoot": "docs",
"localeSubpath": "your-generator/locale/content/path",
"postProcessing": {
"regexAdjustments": [
{
"description": "Per-locale screenshot folders in static assets",
"search": "screenshots/[^/]+/",
"replace": "screenshots/${translatedLocale}/"
}
]
}
}localeSubpath を、ジェネレーターの {locale}/ と翻訳済みファイルの間のレイアウトに合わせて設定するか、デフォルトが適している場合は "doc-system" の代わりにプリセットエイリアス("docusaurus"、"astro-starlight")を使用する。ソースMarkdownでは通常、URL内にソースロケールが埋め込まれている:
すべてのターゲットロケールに対して、同じパスに一致するPNGファイルを提供してください(例: static/img/screenshots/de/screenshot.png)。sourceLocaleの変更に耐えられるように、screenshots/en-GB/をハードコーディングするよりもscreenshots/[^/]+/を優先してください。
プリセット - docsOutput.style = "docusaurus"
"doc-system" と同じで、デフォルトの localeSubpath = "docusaurus-plugin-content-docs/current" を使用。フラットリンクリライターは実行されず、postProcessing は元のMarkdown URLを認識する。英語ページでは通常、ソースロケール付きの絶対パスを使用する:
Docusaurusプリセット用のregexAdjustmentsの例
"docsOutput": {
"style": "docusaurus",
"postProcessing": {
"regexAdjustments": [
{
"description": "Per-locale screenshot folders in docs-site static assets",
"search": "screenshots/[^/]+/",
"replace": "screenshots/${translatedLocale}/"
}
]
}
}docs-site/static/img/screenshots/<locale>/screenshot.pngに一致するPNGファイルを提供してください。ソースロケールに依存しない設定の場合、screenshots/en-GB/よりもscreenshots/[^/]+/を優先してください。
実装例: examples/docusaurus-docs/docs/feature-showcase.md (/img/screenshots/en-GB/screenshot.png) および ai-i18n-tools.config.json
プリセット - docsOutput.style = "astro-starlight"
"doc-system"とlocaleSubpath: ""と同じです。翻訳されたページは{outputDir}/{locale}/の直下にあります。上記の一般的なドキュメントシステム設定と同じロケールごとのフォルダアプローチです。ソースマークダウンは/img/screenshots/en-GB/screenshot.pngを使用します。
Astro Starlightプリセット用のregexAdjustmentsの例
"docsOutput": {
"style": "astro-starlight",
"postProcessing": {
"regexAdjustments": [
{
"description": "Per-locale screenshot folders in public assets",
"search": "screenshots/[^/]+/",
"replace": "screenshots/${translatedLocale}/"
}
]
}
}public/img/screenshots/<locale>/screenshot.png に PNG を配置してください。${translatedLocale} プレースホルダーは、設定のロケール文字列を使用します(例:pt-BR)。astro-starlight プリセットは、デフォルトでロケールの出力パスを小文字化します(pt-br/)。ただし、public/img/screenshots/ 配下の静的アセットフォルダーは、Markdown URL に書き込まれたロケールセグメントと一致させる必要があります。スクリーンショットディレクトリは ${translatedLocale} に合わせ、必ずしも Astro のルートの大文字小文字に合わせる必要はありません。
実装例:examples/astro-docs — feature-showcase.mdx および ai-i18n-tools.config.json (screenshots/[^/]+/)。