アンカーリンク

docsOutput.style = "flat" 時、出力は各ロケールのページ間の相対パスを書き換えます（guide.md → guide.de.md）。アンカーリンク — パスの後に # を付ける通常のmarkdownインライン形式 — は、ターゲットファイル内のセクションにジャンプします：

Read the [installation checklist](setup.md#first-run) before you deploy.

ここでは、リンクのターゲットはsetup.md、#first-runはアンカーです。そのファイル内の適切な見出しにスクロールする必要があります。

アンカーリンクに注意が必要な理由

• rewriteRelativeLinksは各ロケールのファイル名を修正します（setup.md → setup.de.md）。
• 多くのレンダラーは表示される見出しのテキストから#スラグを生成します。翻訳後、ロケールごとに見出しが異なるため、自動生成されたスラグが変化する一方で、書き換えられたリンクはまだ#first-runを指している可能性があります。つまり、英語の#…アンカーが、翻訳された見出しからレンダラーが生成するスラグと一致しなくなる場合があります。
• 結果として、読者は正しいファイルには到達しますが、間違った行に移動するか、ブラウザが一致する見出しを見つけられません。

実行すること

Docusaurusサイト (推奨)

Docusaurus のドキュメント (docsOutput.style = "docusaurus") では、ai-i18n-tools write-heading-ids からの HTML アンカーではなく、Docusaurus のネイティブな見出し ID を優先してください:

1. 見出し行に明示的なIDを追加します。Docusaurusの従来の{#…}サフィックス（CommonMark）またはMDXコメント{/* #… */}（.mdxではこちらが推奨されます）を使用し、## TLS configuration {#tls-configuration}や## TLS configuration {/* #tls-configuration */}のように記述します。translate-docs中は、表示される見出しテキストのみがモデルに送信されます。IDサフィックスは最初に削除され、翻訳された見出し行のendに再度固定されます（Docusaurusはタイトルの途中にある{/* #id */}を無視します）。
2. Docusaurusプロジェクトのルート（package.jsonに組み込まれている場合はpnpm run write-heading-idsであることが多いです）からdocusaurus write-heading-idsを実行し、IDがない見出しにIDを追加または更新します。{/* #… */}形式には--syntax mdx-commentを使用します。あるいは、同じdocs[] / contentPathsに対してai-i18n-tools write-heading-ids --slug-style mdx-commentを実行します。このコマンドは、既存の翻訳ファイル内の同じ英語のIDの位置を修正し（翻訳されたタイトルをスラッグ化しません）、セグメント数が一致する場合は一致するキャッシュセグメントも更新するため、その後のsync --force-updateで修正されたIDが保持されます。見出しの名前を変更した後は再実行して、古いIDが現在のタイトルと一致するようにします。

Markdown の アンカーリンク はこれらの安定した id を指すようにしてください。例: [label](other.md#tls-configuration)。ここでフラグメントは {#…} または {/* #… */} の id に一致し、英語の単語のみから推測されたスラッグではありません。このパターンを使用したコミット済みドキュメントについては、examples/docusaurus-docs を参照してください。

その他のレイアウト (フラット、Starlight、VitePressなど)

Docusaurus を使用していない場合、または {#…} / {/* #… */} サフィックスの代わりに HTML アンカーが必要な場合:

1. translate-docsの前に、ソース.md / .mdxに対してai-i18n-tools write-heading-idsを実行します（通常と同じdocs[] / contentPathsです）。これにより、各見出しの前の行に明示的なHTMLアンカーが挿入され、id値がすべての翻訳コピーで共有されるようになり、同じ英語のIDが既存の翻訳ファイルにコピーされます。セグメント数が一致する場合、一致するキャッシュセグメントも更新されるため、その後のsync --force-updateで修正されたIDが保持されます。見出しの名前を変更した後は再実行して、古いアンカーIDが更新され現在のタイトルと一致するようにします。
2. マークダウンのanchor linksをそれらの安定したIDに向けます（例: [label](other.md#section-id)）。ここで、section-idはツールが書き込んだアンカーと一致する必要があります。英語の単語だけからの推測ではありません。

例

Docusaurus {#…} / {/* #… */} サフィックス

docs/overview.md:

See [TLS setup](security.md#tls-configuration) for certificate steps.

docs/security.md (英語ソース、クラシック):

## TLS configuration {#tls-configuration}

Your CA and cert steps…

または MDX 推奨のコメント形式:

## TLS configuration {/* #tls-configuration */}

Your CA and cert steps…

translate-docsの後、リンクのフラグメントはすべてのロケールで #tls-configuration のまま維持され、変更されるのは見出しテキストとリンクラベルのみです。

Siehe [TLS-Einrichtung](security.md#tls-configuration) für die Zertifikatsschritte.

HTMLアンカー (write-heading-ids)

docs/overview.md:

See [TLS setup](security.md#tls-configuration) for certificate steps.

write-heading-ids後のdocs/security.md（簡略化）:

<a id="tls-configuration"></a>

---

# TLS configuration

Your CA and cert steps…

translate-docs後、ファイルパスと#…アンカーはすべてのロケールファイルで一致したままになります。たとえば:

Siehe [TLS-Einrichtung](security.de.md#tls-configuration) für die Zertifikatsschritte.

#tls-configurationアンカーは、idがソースで固定されているため、すべてのロケールで同じです。見出しのテキストとリンクのラベルのみが翻訳されます。

翻訳後もリンクが機能しない場合は、トラブルシューティングを参照してください。