SVG の変換

人間が判読できるラベルを含むSVGイラストと図用に設計されています。translate-svgコマンドは、ソース.svgファイルを読み取り、<text>、<title>、および<desc>要素からテキストを抽出し、アクティブなLLMプロバイダーを介してそれらの文字列を翻訳し、ターゲットロケールごとに1つの出力SVGを書き込みます。

これは、ロケール固有のバイナリSVGファイルを出力する唯一のパイプラインです。translate-docsはマークダウンの代替テキストとリンク参照を翻訳しますが、SVGアセットを変更またはコピーしません。ページに翻訳されたラベル付きの図が必要な場合は、features.translateSVGを有効にして、トップレベルのsvgブロックを構成します。

ロケールごとのモデルオーバーライド

translate-svg は 対象ロケールごとにモデルを解決します: 設定されている場合は最初に localeModels(locale)、その後 translationModels を使用します。各ロケールの SVG 実行では独自のフォールバックチェーンが使用されます — これは、CJK ロケールの図表ラベルにスクリプトに最適化されたモデル（例: ja）が必要な場合に便利です。プロバイダーとモデル を参照してください。

SVG翻訳は、translate-docsおよびtranslate-jsonと同じSQLiteキャッシュ（cacheDir）を使用します。すでに翻訳されたテキストセグメントはキャッシュから提供され、新規または変更されたソーステキストのみがLLMに送信されます。

SVG翻訳を使用するタイミング

次の場合にtranslate-svgを使用します。

• SVGに、ロケールごとに変更する必要がある表示ラベル、タイトル、または説明が含まれている場合。
• Webアプリが実行時にロケール固有の図ファイルをロードする場合（例：dashboard.de.svg）。
• ドキュメントシステムサイト（Docusaurus、Astro Starlight、VitePress）が、翻訳されたSVGを翻訳されたマークダウンの横に配置する場合。

次の場合にはtranslate-svgを使用しないでください。

• 翻訳可能なテキストのない装飾的なSVG（アイコン、ロゴ、背景）。
• ラスタースクリーンショット（PNG、JPEG、WebP）—これらは画像とスクリーンショットで処理されます。
• <text>要素ではなくパスデータに埋め込まれたテキスト—エクストラクターはパスのアウトラインを読み取ることができません。

最初からi18nを考慮した設計

SVGは、ラベルが最初から実際のテキスト要素である場合に最も簡単に翻訳できます。

• 人間が判読できるコピーを<text>、<title>、および<desc>に入力します。
• デザインツールでラベルをパスに変換することは避けてください。パスデータは翻訳者にとって不透明です。
• ソースSVGをsvg.outputDirとは別の専用ディレクトリに保持します。ソースと生成されたロケールファイルを混在させると、どのファイルを安全に編集または再生成できるかを判断できなくなります。

Webアプリの場合、デザインですべて小文字のラベルを使用している場合はforceLowercase: trueを有効にしてください。これにより、ファイルシステムとCDN間の大文字と小文字の不一致が回避されます。

出力レイアウト

translate-svgは2つの一般的な出力形式をサポートしています。アプリまたはドキュメントサイトが実行時にSVGファイルを参照する方法に基づいて選択してください。

レイアウト	svg.style	最適な用途	子ガイド
フラット（Webアプリ）	"flat"	Next.js、Vite、およびロケールコード化されたファイル名でSVGを埋め込むその他のアプリ	Webアプリ（フラットSVG）
コロケーション（ドキュメントシステム）	"nested" + pathTemplate	Docusaurusや、翻訳されたアセットが翻訳されたページの横に配置されるその他のドキュメントシステムサイト	コロケーションSVG

フラットレイアウトは、public/assets/diagram.de.svgのようなファイルをdiagram.en-GB.svgの横に書き込みます。アプリはロケールサフィックスでそれらを参照します。

<img src={`/assets/diagram.${locale}.svg`} alt="Architecture diagram" />

コロケーションレイアウトは、各ロケールのSVGをそのロケールのコンテンツツリーに書き込みます（例：i18n/de/.../assets/diagram.svg）。ソースと翻訳されたマークダウンは同じ相対パス（../assets/diagram.svg）を使用します。regexAdjustmentsルールは必要ありません。

SVGレイアウトがラスタースクリーンショット戦略とどのように適合するかについては、画像とスクリーンショットの決定ガイドを参照してください。

ステップ1：有効化と設定

機能を有効にし、translate-svgをソースファイルと出力ルートに指定します。

{
  "features": {
    "translateSVG": true
  },
  "svg": {
    "sourcePath": "images",
    "outputDir": "public/assets",
    "style": "flat"
  }
}

主なsvgフィールド:

• sourcePath — 1つ以上のディレクトリまたはグロブパターン（例: "images/*.svg"、"**/icons/*.svg"）。プロジェクトルートから再帰的にスキャンされます。
• outputDir — 翻訳されたSVG出力のルートディレクトリ。
• style — カスタム"flat"を使用しない場合の"nested"またはpathTemplate。
• pathTemplate — プレースホルダー{outputDir}、{locale}、{llocale}、{basename}、{stem}などを含むオプションのカスタム出力パス（併置されたドキュメントシステムレイアウトに必要）。
• forceLowercase — 再構築時に小文字に翻訳されたテキスト。

フィールドの完全なリファレンス: 設定 — svg。

ステップ2: 翻訳

ai-i18n-tools translate-svg

単一ロケールの翻訳:

ai-i18n-tools translate-svg --locale de

ファイルを書き込まずにプレビュー:

ai-i18n-tools translate-svg --dry-run

syncは、features.translateSVGとsvgの両方が設定されている場合、SVGステップを自動的に実行します（--no-svgでスキップ）。共通のフラグには、-l / --locale、-p / --path、-j / --concurrency、および--force / --force-updateが含まれます。

トラブルシューティング

一般的なSVGの問題 — 混在するソース/出力ディレクトリ、Docusaurus上の絶対静的URL、パスレイアウトの誤り — は、SVGトラブルシューティングで説明されています。ラスターアセットとリンクの書き換えについては、画像とスクリーンショットのトラブルシューティングを参照してください。