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
rewriteRelativeLinksbehebt den Dateinamen für jedes Gebietsschema (setup.md→setup.de.md).- Viele Renderer leiten den
#-Slug aus dem sichtbaren Überschriftentext ab. Nach der Übersetzung unterscheiden sich die Überschriften pro Gebietsschema, sodass sich ein automatisch generierter Slug ändern kann, während der umgeschriebene Link immer noch#first-runanzeigen könnte — oder der#…-Anker des Quell-Gebietsschemas nicht mehr mit dem Slug übereinstimmt, den der Renderer aus der übersetzten Überschrift erstellt. Die Ausgangssprache istsourceLocaleund kann jede beliebige Sprache sein. - Ergebnis: Leser landen auf der richtigen Datei, aber auf der falschen Zeile, oder der Browser findet keine passende Überschrift.
Was zu tun ist
Docusaurus-Sites (bevorzugt)
In der Docusaurus-Dokumentation (docsOutput.style = "docusaurus") sollten Sie die nativen Überschriften-IDs von Docusaurus anstelle von HTML-Ankern aus ai-i18n-tools write-heading-ids bevorzugen:
- Fügen Sie eine explizite ID in die Überschriftenzeile ein, mit dem klassischen
{#…}-Suffix von Docusaurus (CommonMark) oder dem MDX-Kommentar{/* #… */}(bevorzugt für.mdx), z. B.## TLS configuration {#tls-configuration}oder## TLS configuration {/* #tls-configuration */}. Währendtranslate-docswird nur der sichtbare Überschriftentext an das Modell gesendet — das ID-Suffix wird zuerst entfernt und wieder an das Ende der übersetzten Überschriftenzeile angehängt (Docusaurus ignoriert ein{/* #id */}, das in der Mitte des Titels landet). - Führen Sie
docusaurus write-heading-idsaus dem Stammverzeichnis Ihres Docusaurus-Projekts aus (oftpnpm run write-heading-ids, wenn es inpackage.jsoneingebunden ist), um IDs für Überschriften hinzuzufügen oder zu aktualisieren, die keine haben — verwenden Sie--syntax mdx-commentfür die{/* #… */}-Form. Alternativ führen Sieai-i18n-tools write-heading-ids --slug-style mdx-commentauf demselbendocs[]/ derselbencontentPathsaus. Dieser Befehl positioniert auch dieselben englischen IDs in bestehenden übersetzten Dateien neu (er erzeugt keinen Slug für den übersetzten Titel) und aktualisiert das übereinstimmende zwischengespeicherte Segment, wenn die Segmentanzahlen übereinstimmen, sodass ein späteressync --force-updatedie reparierte ID beibehält. Führen Sie den Befehl 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 der ID {#…} oder {/* #… */} ü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:
- Führen Sie
ai-i18n-tools write-heading-idsauf Ihren Quell-.md/.mdxvortranslate-docsaus (mit denselbendocs[]/contentPathswie gewohnt). Es fügt explizite HTML-Anker in der Zeile vor jeder Überschrift ein, damitid-Werte von jeder übersetzten Kopie geteilt werden, und es kopiert dieselben englischen IDs auf bestehende übersetzte Dateien. Wenn die Segmentanzahl übereinstimmt, wird auch das passende zwischengespeicherte Segment aktualisiert, sodass ein späteressync --force-updatedie reparierte ID beibehält. Führen Sie es erneut aus, nachdem Sie Überschriften umbenannt haben, damit veraltete Anker-IDs aktualisiert werden, um dem aktuellen Titel zu entsprechen. Eine Umbenennung hinterlässt einen einzelnen Anker: Zusätzliche<a id>-Zeilen, die über dieser Überschrift gestapelt sind, werden entfernt, und Markdown-Links im Repository, die auf eine entfernte ID zielten, werden neu ausgerichtet. Ein<a id>, das sich nicht direkt über einer Überschrift befindet, bleibt erhalten. - Richten Sie Ihre Markdown-Ankerlinks auf diese stabilen IDs aus, z. B.
[label](other.md#section-id), wobeisection-iddem Anker entspricht, den das Tool geschrieben hat – nicht einer Vermutung, die nur auf englischen Wörtern basiert.
Beispiel
Docusaurus {#…} / {/* #… */} Suffix
docs/overview.md:
See [TLS setup](security.md#tls-configuration) for certificate steps.docs/security.md (englische Quelle, klassisch):
## TLS configuration {#tls-configuration}
Your CA and cert steps…Oder die von MDX bevorzugte Kommentarform:
## 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.