トラブルシューティング

翻訳されたドキュメントでセクションアンカーリンクが機能しない

[label](other.md#section-id)のようなリンクは、正しい翻訳済みファイルを開くことはできるが、目的の見出しにスクロールできなかったり、誤ったセクションにジャンプしたりする可能性がある。#…のフラグメントは、そのロケールのどの見出しidとも一致しなくなっている。

一般的な原因:

• ソースの見出しに明示的なアンカーIDが設定されていない。サイトは表示されている見出しテキストからスラグを生成しているため、翻訳後に変更される。
• ソースで見出し名を変更したが、直前の<a id="…"></a>行が欠落しているか、古いIDのままになっている。
• アンカーリンクが英単語から推測された#…フラグメントを使用しており、write-heading-idsが生成するIDではなくなっている。

修正方法

1. ソースの .md / .mdx（translate-docs と同じ docs[] / contentPaths）で ai-i18n-tools write-heading-ids を実行します。ATX見出しの直前に <a id="slug"></a> を挿入するか、見出しのテキストが現在のスラッグと一致しない場合に既存のアンカーを更新します。
2. それらのIDを指すようにアンカーリンクを設定します — たとえば、[setup](guide.md#first-run) の #first-run は英語のタイトルから推論されたスラッグではなく、対象となる見出しの上にあるアンカー行と一致する必要があります。
3. translate-docs（または sync --force-update）を再実行して、すべてのロケールのコピーに更新されたアンカー行が含まれるようにします。

変更をプレビューするには、まず--dry-runでwrite-heading-idsを使用します。完全なパターンについては、アンカーリンクを参照してください。

翻訳されたドキュメントで画像またはアセットのリンクが404になる

Markdown リンクまたは ![alt](url) は英語では機能しますが、翻訳されたコピーでは 404 を返します。これは、URL がソースロケールフォルダーまたは英語のみの静的パスを指していることが原因であることがよくあります。

修正方法

1. アセットのレイアウトが docsOutput.style (フラット vs ドキュメントシステム) と一致していることを確認します。リンクの書き換え および 画像とスクリーンショット を参照してください。
2. ロケールセグメントを交換したり、絶対 /img/… パスをブリッジしたりするために、docsOutput.postProcessing.regexAdjustments を追加または調整します。フラットレイアウトの場合、フラットリンクの書き換えは 前に regexAdjustments が実行されることを覚えておいてください。すでにプレフィックスが付けられた URL に対してパターンを照合します。
3. 書き換えられた markdown が参照するパスにロケール固有のアセットファイルが存在することを確認します (translate-docs は URL を書き換えますが、ラスターファイルをコピーしません)。