Skip to content

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 que write-heading-ids générerait.

Correction

  1. Exécutez ai-i18n-tools write-heading-ids sur votre source .md / .mdx (même docs[] / contentPaths que translate-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.
  2. Pointez les liens d'ancrage vers ces identifiants — par exemple [setup](guide.md#first-run) où #first-run correspond à la ligne d'ancrage au-dessus de l'en-tête cible, et non à un slug déduit du titre anglais seul.
  3. Réexécutez translate-docs (ou sync --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 ![alt](url) 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

  1. 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.
  2. Ajoutez ou ajustez docsOutput.postProcessing.regexAdjustments pour é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 avant regexAdjustments — faites correspondre les modèles à l'URL déjà préfixée.
  3. Assurez-vous que les fichiers d'actifs spécifiques à la locale existent aux chemins référencés par le Markdown réécrit (translate-docs réé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

  1. Vérifiez que le code de la locale correspond à l'écriture souhaitée (hi vs hi-Latn, zh-Hans vs zh-Hant, sr vs sr-Latn).
  2. Relancez la traduction pour que les lignes de cache avec une écriture incorrecte soient rejetées : translate-ui --force pour les chaînes de l'interface utilisateur, ou translate-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-update traite à nouveau toutes les locales.
  3. Si un modèle continue d'échouer à la vérification de l'écriture, ajoutez une entrée localeModels pour cette locale afin qu'un modèle plus puissant soit essayé en premier. Voir la section Modèles d'IA.

Publié sous licence MIT.