アンカーリンク
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と表示されるか、またはソースロケールの#…アンカーが、レンダラーが翻訳された見出しから構築するスラッグと一致しなくなる可能性があります。ソース言語はsourceLocaleであり、任意の言語である可能性があります。 - 結果: 読者は正しいファイルに到達しますが、間違った行に移動するか、ブラウザが一致する見出しを見つけられません。
実行すること
Docusaurusサイト (推奨)
Docusaurus のドキュメント (docsOutput.style = "docusaurus") では、ai-i18n-tools write-heading-ids からの HTML アンカーではなく、Docusaurus のネイティブな見出し ID を優先してください:
- 見出し行に明示的なIDを追加します。Docusaurusの従来の
{#…}サフィックス(CommonMark)またはMDXコメント{/* #… */}(.mdxではこちらが推奨されます)を使用し、## TLS configuration {#tls-configuration}や## TLS configuration {/* #tls-configuration */}のように記述します。translate-docs中は、表示される見出しテキストのみがモデルに送信されます。IDサフィックスは最初に削除され、翻訳された見出し行のendに再度固定されます(Docusaurusはタイトルの途中にある{/* #id */}を無視します)。 - 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 アンカーが必要な場合:
translate-docsの前に、ソースの.md/.mdxでai-i18n-tools write-heading-idsを実行します (通常と同じdocs[]/contentPaths)。これにより、各見出しの前の行に明示的な HTML アンカーが挿入され、翻訳されたすべてのコピーでidの値が共有され、既存の翻訳ファイルに同じ英語の ID がコピーされます。セグメント数が一致する場合、一致するキャッシュされたセグメントも更新されるため、後でsync --force-updateを実行しても、修正された ID が保持されます。見出しの名前を変更した後、それを再実行して、古いアンカー ID が現在のタイトルと一致するように更新します。名前変更により単一のアンカーが残ります。その見出しの上に積み重ねられた余分な<a id>行は削除され、削除された ID をターゲットとしていたリポジトリ内の Markdown リンクは再ターゲットされます。見出しの直上にない<a id>はそのまま残されます。- Markdown の アンカーリンク をそれらの安定した 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がソースで固定されているため、すべてのロケールで同じです。見出しのテキストとリンクのラベルのみが翻訳されます。
翻訳後もリンクが機能しない場合は、トラブルシューティングを参照してください。