Dépannage
Les liens d'ancrage de section ne fonctionnent pas dans les documents traduits
Un lien comme [label](other.md#section-id) peut ouvrir le bon fichier traduit mais échouer à faire défiler jusqu’au titre visé — ou sauter vers une section incorrecte. Le fragment #… ne correspond plus à aucun attribut id de titre dans cette langue.
Causes fréquentes :
- Les titres sources n’avaient jamais d’identifiants d’ancre explicites ; le site dérive les slugs à partir du texte visible des titres, qui change après traduction.
- Vous avez renommé un titre dans le code source, mais la ligne
<a id="…"></a>précédente est absente ou contient encore l’ancien identifiant. - Les liens d’ancre utilisent un fragment
#…deviné à partir de mots anglais au lieu de l’identifiant quewrite-heading-idsgénérerait.
Correction
- Exécutez
ai-i18n-tools write-heading-idssur votre source.md/.mdx(mêmedocs[]/contentPathsquetranslate-docs). Par défaut, il insère<a id="slug"></a>avant chaque en-tête ATX, ou actualise une ancre existante lorsque le texte de l'en-tête ne correspond plus au slug actuel. Pour les identifiants de commentaire Docusaurus MDX, utilisez--slug-style mdx-comment. - Pointez les liens d'ancrage vers ces identifiants — par exemple
[setup](guide.md#first-run)où#first-runcorrespond à la ligne d'ancrage au-dessus de l'en-tête cible, et non à un slug déduit du titre anglais seul. - Réexécutez
translate-docs(ousync --force-update) afin que chaque copie de locale inclue les lignes d'ancrage mises à jour.
Utilisez --dry-run sur write-heading-ids d'abord pour prévisualiser les modifications. Voir Liens d'ancrage pour le modèle complet.
Liens d'image ou d'actif 404 dans les documents traduits
Un lien Markdown ou  fonctionne en anglais mais renvoie une erreur 404 dans les copies traduites, souvent parce que l'URL pointe toujours vers le dossier de la langue source ou un chemin statique uniquement en anglais.
Correction
- Confirmez que la disposition de votre actif correspond à votre
docsOutput.style(plate ou système de documentation). Voir Réécriture de liens et Images et captures d'écran. - Ajoutez ou ajustez
docsOutput.postProcessing.regexAdjustmentspour échanger des segments de locale ou relier des chemins/img/…absolus. Pour une disposition plate, rappelez-vous que le réécriveur de liens plats s'exécute avantregexAdjustments— faites correspondre les modèles à l'URL déjà préfixée. - Assurez-vous que les fichiers d'actifs spécifiques à la locale existent aux chemins référencés par le Markdown réécrit (
translate-docsréécrit les URL mais ne copie pas les fichiers raster).
La sortie en hindi, arabe, CJK ou cyrillique est romanisée (lettres latines)
Certains modèles traduisent le sens mais écrivent le résultat en lettres latines/romaines (par exemple, le hindi sous la forme Namaste au lieu de नमस्ते). Le simple hi signifie Devanagari ; utilisez hi-Latn uniquement lorsque vous souhaitez du hindi romanisé.
Correction
- Vérifiez que le code de la locale correspond à l'écriture souhaitée (
hivshi-Latn,zh-Hansvszh-Hant,srvssr-Latn). - Relancez la traduction pour que les lignes de cache avec une écriture incorrecte soient rejetées :
translate-ui --forcepour les chaînes de l'interface utilisateur, outranslate-docs --check-cache/sync --check-cache(l'omission au niveau du fichier est contournée uniquement pour les locales avec une écriture attendue ; le cache des segments valides est toujours réutilisé).--force-updatetraite à nouveau toutes les locales. - Si un modèle continue d'échouer à la vérification de l'écriture, ajoutez une entrée
localeModelspour cette locale afin qu'un modèle plus puissant soit essayé en premier. Voir la section Modèles d'IA.