Comment traduire des fichiers Markdown et MDX avec l’IA

Markdown est facile à traduire, jusqu’au jour où vous avez deux cents pages. Les mots ne posent alors pas de problème : c’est tout ce qui les entoure qui complique les choses. Le code qui ne doit pas changer, les liens qui doivent continuer à fonctionner et la prochaine version qui ajoute dix pages de plus.

Ce guide s’adresse aux sites de documentation, aux fichiers README, aux journaux des modifications et aux dossiers de blog rédigés en Markdown ou en MDX.

Quelle option choisir ?

Faites relire par une personne la page qui présente le produit. Faites traduire la documentation de référence par un moteur, car c’est là que se trouve le plus gros volume.

Pourquoi AI Glot convient à un dossier de documentation

• Le contenu est traduit, la structure reste intacte. Les titres, les paragraphes, les éléments de liste et les cellules de tableau sont du texte. Le code, les cibles des liens, les blocs HTML et les séparateurs de tableau restent inchangés.
• La mise en forme suit le texte. Le gras, l’italique et le texte des liens accompagnent les mots auxquels ils se rapportent.
• Un seul glossaire pour tout le site de documentation. Les noms de produits et les termes de l’API restent cohérents sur chaque page et dans les prochaines versions.
• Un plan avant toute dépense. Il répertorie les éléments trouvés et ceux qui seront traduits.
• Tout un dossier en une seule opération. Placez les fichiers dans un ZIP pour que leur arborescence soit reconstituée.

Le parcours d’un fichier

Ce qui change dans une page

Seul le texte courant change. Le code, le lien et les clés du front matter restent inchangés.

Points à vérifier dans MDX

Les imports, les balises de composants et les expressions restent inchangés. La page continue ainsi de fonctionner. Attention toutefois au texte transmis à un composant sous forme de prop, par exemple un titre passé à une carte. Il fait partie du composant, pas du texte courant. Vérifiez donc ces quelques chaînes après la traduction.

Ancres des titres. Si votre site crée une ancre à partir du texte du titre, un titre traduit aura une nouvelle ancre. Pensez à vérifier les liens qui pointent vers un titre, comme celui de la section Install.

Comment procéder, étape par étape

1. Essayez gratuitement avec un fichier. Le traducteur Markdown ne nécessite aucun compte et accepte des fichiers jusqu’à 2 MB et 5,000 mots.

2. Importez le fichier ou un ZIP du dossier dans l’application.

3. Indiquez en une phrase ce dont vous avez besoin.

Translate this folder into French.
Translate the prose and the front matter title and description.
Leave every other front matter field as it is.

La phrase détermine ce qui est traduit dans l’ensemble du dossier. Une consigne de formulation, comme « garder les noms de produits et les termes API en anglais », doit être saisie dans le deuxième champ au moment de la validation, car elle s’applique à chaque paragraphe pendant sa rédaction.

4. Ajoutez un glossaire pour les noms de produits, les termes API et les mots que vous traduisez toujours de la même façon. Comment en créer un.

5. Consultez les offres et choisissez un niveau de qualité.

Lite permet de traduire environ trois fois plus de mots par crédit et est plus rapide : idéal pour mettre à jour en bloc la documentation de référence. Standard convient à la page de destination. Un crédit équivaut à un mot en Standard.

6. Validez et téléchargez.

Un dossier de documentation, plusieurs langues

Les chiffres sont donnés à titre d’exemple. Un fichier Markdown contient une seule langue : chaque langue correspond donc à sa propre copie traduite du dossier.

Trois façons de lancer le traitement

Depuis la ligne de commande convient à un dépôt de documentation, car les quatre mêmes étapes peuvent être exécutées dans un script ou dans la CI à chaque modification de l’anglais :

id=$(aiglot batches create docs.zip \
      --instruction "Translate into French. Translate the prose and the front matter title and description." \
      --json | jq -r '.data.id')
aiglot batches get "$id" --json | jq '.data.plan'
aiglot batches approve "$id" --quality lite \
  --instructions "Keep product names and API terms in English."
aiglot batches download "$id" --output docs_fr.zip

Avec votre agent IA : connectez AI Glot comme serveur MCP. L’agent peut lire votre dépôt, proposer les termes du glossaire qu’il y trouve, lancer le traitement et remettre les fichiers à leur place.

Dans l’application : importez, cliquez, téléchargez. Idéal pour une seule page.

Pour intégrer l’API, consultez la documentation de l’API.

Vérifiez le résultat

Générez le site de documentation dans une langue traduite et ouvrez trois pages : une avec du code, une avec un tableau et une avec un lien vers une autre page. Lancez votre vérificateur de liens habituel, car c’est là que vous repérerez une modification d’ancre. Conservez les fichiers anglais jusqu’à ce qu’une personne qui lit la langue ait vérifié les pages importantes.

La page Tarifs indique le coût pour un volume plus important, et un compte gratuit comprend des crédits pour traiter un dossier réel.

Les limites indiquées ici sont celles en vigueur au moment de la rédaction : 4 MB par fichier Markdown, 200 fichiers et 20 MB par ZIP, ainsi que 2 MB et 5,000 mots dans l’outil gratuit. La liste de DeepL provient de sa propre documentation. Les noms de fichiers et le nombre de pages dans les schémas sont des exemples. Votre offre indique les chiffres réels pour vos propres fichiers, et sa consultation est gratuite.