Anker-Links

Wenn docsOutput.style = "flat", schreibt die Ausgabe relative Pfade zwischen Seiten für jede Sprache um (guide.md → guide.de.md). Ankerlinks — die übliche Markdown-Inlineform mit einem # nach dem Pfad — springen zu einem Abschnitt in der Zieldatei:

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

Hier ist das Link-Ziel setup.md und #first-run der Anker: Es sollte zum richtigen Überschriftenelement innerhalb dieser Datei scrollen.

Warum Anker-Links besondere Aufmerksamkeit erfordern

• rewriteRelativeLinks legt den Dateinamen für jede Sprache fest (setup.md → setup.de.md).
• Viele Renderer leiten den #-Slug aus dem sichtbaren Überschriftentext ab. Nach der Übersetzung unterscheiden sich die Überschriften je nach Sprache, sodass sich ein automatisch generierter Slug ändern kann, während der umgeschriebene Link möglicherweise immer noch #first-run enthält – oder Ihr englischer #…-Anker passt nicht mehr zum Slug, den der Renderer aus der übersetzten Überschrift erstellt.
• Ergebnis: Leser landen auf der richtigen Datei, aber an der falschen Stelle, oder der Browser findet keine passende Überschrift.

Was zu tun ist

Docusaurus-Sites (bevorzugt)

In der Docusaurus-Dokumentation (docsOutput.style = "docusaurus") sollten die nativen Überschriften-IDs von Docusaurus anstelle von ai-i18n-tools write-heading-ids bevorzugt werden:

1. Fügen Sie eine explizite ID in der Überschriftenzeile mit dem {#…}-Suffix von Docusaurus hinzu, z. B. ## TLS configuration {#tls-configuration}. Während der translate-docs wird nur der sichtbare Überschriftentext übersetzt – das {#tls-configuration}-Suffix bleibt in jedem Gebietsschema erhalten.
2. Führen Sie docusaurus write-heading-ids aus dem Stammverzeichnis Ihres Docusaurus-Projekts aus (oft pnpm run write-heading-ids, wenn es in package.json verdrahtet ist), um {#…}-Suffixe zu Überschriften hinzuzufügen oder zu aktualisieren, die keine haben. Führen Sie es nach dem Umbenennen von Überschriften erneut aus, damit veraltete IDs mit den aktuellen Titeln übereinstimmen.

Verweisen Sie Ihre Markdown-Ankerlinks auf diese stabilen IDs, z. B. [label](other.md#tls-configuration), wobei das Fragment mit dem {#…}-Suffix übereinstimmt – nicht mit einem Slug, der nur aus englischen Wörtern erraten wurde. Siehe examples/docusaurus-docs für festgeschriebene Dokumente, die dieses Muster verwenden.

Andere Layouts (Flat, Starlight, VitePress usw.)

Wenn Sie nicht Docusaurus verwenden oder HTML-Anker anstelle von {#…}-Suffixen benötigen:

1. Führen Sie ai-i18n-tools write-heading-ids auf Ihrer Quelle .md / .mdx vor translate-docs aus (gleicher docs[] / contentPaths wie üblich). Es fügt explizite HTML-Anker in die Zeile vor jeder Überschrift ein, sodass id-Werte von jeder übersetzten Kopie gemeinsam genutzt werden. Führen Sie es erneut aus, nachdem Sie Überschriften umbenannt haben, damit veraltete Anker-IDs aktualisiert werden und dem aktuellen Titel entsprechen.
2. Verweisen Sie Ihre Markdown-Ankerlinks auf diese stabilen IDs, z. B. [label](other.md#section-id), wobei section-id mit dem Anker übereinstimmt, den das Tool geschrieben hat — nicht nur eine Vermutung aus englischen Wörtern.

Beispiel

Docusaurus {#…}-Suffix

docs/overview.md:

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

docs/security.md (englische Quelle):

## TLS configuration {#tls-configuration}

Your CA and cert steps…

Nach translate-docs bleibt das Linkfragment in jedem Gebietsschema #tls-configuration; nur der Überschriftentext und die Linkbeschriftung ändern sich:

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

HTML-Anker (write-heading-ids)

docs/overview.md:

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

docs/security.md nach write-heading-ids (vereinfacht):

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

---

# TLS configuration

Your CA and cert steps…

Nach translate-docs bleiben Dateipfade und #…-Anker in jeder Sprachdatei synchron, zum Beispiel:

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

Der #tls-configuration-Anker ist in allen Sprachversionen identisch, da die id in der Quelle festgelegt ist; nur der Überschriftstext und die Linkbezeichnung werden übersetzt.

Wenn Links nach der Übersetzung immer noch fehlschlagen, siehe Fehlerbehebung.