Liens d'ancrage
Lorsque docsOutput.style = "flat", la sortie réécrit les chemins relatifs entre les pages pour chaque locale (guide.md → guide.de.md). Les liens d'ancre — la forme habituelle en ligne dans le markdown avec un # après le chemin — permettent de sauter vers une section dans le fichier cible :
Read the [installation checklist](setup.md#first-run) before you deploy.Ici, la cible du lien est setup.md, et #first-run est l'ancre : elle doit faire défiler jusqu'au bon titre à l'intérieur de ce fichier.
Pourquoi les liens d'ancrage nécessitent une attention particulière
rewriteRelativeLinkscorrige le nom de fichier pour chaque locale (setup.md→setup.de.md).- De nombreux moteurs de rendu dérivent le slug
#du texte d'en-tête visible. Après traduction, les en-têtes diffèrent par locale, de sorte qu'un slug auto-généré peut changer tandis que le lien réécrit pourrait toujours indiquer#first-run— ou l'ancre#…de la locale source ne correspond plus au slug que le moteur de rendu construit à partir de l'en-tête traduit. La langue source estsourceLocaleet peut être n'importe quelle langue. - Résultat : les lecteurs atterrissent sur le bon fichier mais la mauvaise ligne, ou le navigateur ne trouve aucun en-tête correspondant.
Que faire
Sites Docusaurus (préféré)
Dans la documentation Docusaurus (docsOutput.style = "docusaurus"), préférez les identifiants d'en-tête natifs de Docusaurus aux ancres HTML de ai-i18n-tools write-heading-ids :
- Ajoutez un identifiant explicite sur la ligne du titre avec le suffixe classique
{#…}de Docusaurus (CommonMark) ou le commentaire MDX{/* #… */}(préféré pour.mdx), par ex.## TLS configuration {#tls-configuration}ou## TLS configuration {/* #tls-configuration */}. Lors detranslate-docs, seul le texte visible du titre est envoyé au modèle — le suffixe d'identifiant est d'abord supprimé puis réattaché à la fin de la ligne du titre traduit (Docusaurus ignore un{/* #id */}qui se retrouve au milieu du titre). - Exécutez
docusaurus write-heading-idsdepuis la racine de votre projet Docusaurus (souventpnpm run write-heading-idslorsqu'il est configuré danspackage.json) pour ajouter ou actualiser les identifiants sur les titres qui en sont dépourvus — utilisez--syntax mdx-commentpour la forme{/* #… */}. Vous pouvez également exécuterai-i18n-tools write-heading-ids --slug-style mdx-commentsur le mêmedocs[]/contentPaths. Cette commande repositionne également les mêmes identifiants anglais dans les fichiers traduits existants (elle ne génère pas de slug pour le titre traduit) et met à jour le segment mis en cache correspondant lorsque le nombre de segments correspond, afin qu'unsync --force-updateultérieur conserve l'identifiant corrigé. Réexécutez-la après avoir renommé les titres afin que les anciens identifiants correspondent aux titres actuels.
Pointez vos liens d'ancrage markdown vers ces identifiants stables, par exemple [label](other.md#tls-configuration), où le fragment correspond à l'identifiant {#…} ou {/* #… */} — et non à un slug deviné à partir de mots anglais uniquement. Voir examples/docusaurus-docs pour les documents validés qui utilisent ce modèle.
Autres mises en page (flat, Starlight, VitePress, etc.)
Lorsque vous n'êtes pas sur Docusaurus, ou que vous avez besoin d'ancres HTML au lieu de suffixes {#…} / {/* #… */} :
- Exécutez
ai-i18n-tools write-heading-idssur vos fichiers source.md/.mdxavanttranslate-docs(les mêmesdocs[]/contentPathsque d'habitude). Il insère des ancres HTML explicites sur la ligne précédant chaque titre afin que les valeursidsoient partagées par chaque copie traduite, et il copie ces mêmes identifiants anglais sur les fichiers traduits existants. Lorsque les nombres de segments correspondent, le segment mis en cache correspondant est également mis à jour, de sorte qu'unsync --force-updateultérieur conserve l'identifiant réparé. Réexécutez-le après avoir renommé les titres afin que les identifiants d'ancrage obsolètes soient actualisés pour correspondre au titre actuel. Un renommage ne laisse qu'une seule ancre : les lignes<a id>supplémentaires empilées au-dessus de ce titre sont supprimées, et les liens Markdown internes au dépôt qui ciblaient un identifiant supprimé sont reciblés. Un<a id>qui n'est pas directement au-dessus d'un titre est laissé en place. - Pointez vos liens d'ancrage Markdown vers ces identifiants stables, par exemple
[label](other.md#section-id), oùsection-idcorrespond à l'ancre que l'outil a écrite — et non une supposition basée uniquement sur des mots anglais.
Exemple
Suffixe Docusaurus {#…} / {/* #… */}
docs/overview.md:
See [TLS setup](security.md#tls-configuration) for certificate steps.docs/security.md (source anglaise, classique) :
## TLS configuration {#tls-configuration}
Your CA and cert steps…Ou la forme de commentaire préférée de MDX :
## TLS configuration {/* #tls-configuration */}
Your CA and cert steps…Après translate-docs, le fragment de lien reste #tls-configuration dans chaque langue ; seuls le texte de l'en-tête et l'étiquette du lien changent :
Siehe [TLS-Einrichtung](security.md#tls-configuration) für die Zertifikatsschritte.Ancres HTML (write-heading-ids)
docs/overview.md:
See [TLS setup](security.md#tls-configuration) for certificate steps.docs/security.md après write-heading-ids (simplifié) :
<a id="tls-configuration"></a>
---
# TLS configuration
Your CA and cert steps…Après translate-docs, les chemins de fichiers et les ancres #… restent alignés dans chaque fichier de langue, par exemple :
Siehe [TLS-Einrichtung](security.de.md#tls-configuration) für die Zertifikatsschritte.L'ancre #tls-configuration est identique dans toutes les langues car le id est fixé dans la source ; seuls le texte du titre et l'étiquette du lien sont traduits.
Si les liens ne fonctionnent toujours pas après la traduction, consultez Dépannage.