# General Translation Knowledge Base: Comment traduire du Markdown et du MDX sans casser la syntaxe ? URL: https://generaltranslation.com/fr/kb/translate-markdown-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduisez la prose, le texte alternatif des images, les titres et descriptions du frontmatter, ainsi que les props de composants qui affichent du texte. Laissez inchangés les blocs de code, le code intégré, les imports, les noms de composants JSX, les clés du frontmatter et les URL des liens, sauf si une correspondance personnalisée des paramètres régionaux les réécrit. Placez les valeurs YAML traduites entre guillemets, puis lancez la compilation de votre site. Category: Traduction Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Un fichier Markdown mêle prose et syntaxe technique. Le MDX y ajoute du JavaScript sous forme de lignes `import`, de composants JSX et d’`{expressions}` qu’un compilateur doit toujours pouvoir analyser une fois la traduction effectuée. Avant de traduire, identifiez les champs qui contiennent du texte affiché : le `title` d’un composant peut devoir être traduit, alors que son `id` doit rester stable. ## Ce qui casse lorsque du Markdown passe par un traducteur générique Un traducteur qui considère le fichier comme du texte brut le traite intégralement comme du langage naturel. Voici les défaillances à vérifier : * **Blocs de code et code intégré.** Les commandes et les identifiants peuvent être traduits : `npm install` peut ainsi revenir sous la forme `npm installer`. * **URL et ancres des liens.** Un slug ou un `#fragment` dans un lien peut être traduit et ne plus pointer nulle part. Les titres traduits reçoivent également de nouveaux ID générés, ce qui casse tous les liens `#anchor` qui y renvoient ; c'est pourquoi Docusaurus recommande des [ID de titre explicites](https://docusaurus.io/docs/i18n/tutorial#translate-markdown-files). * **Frontmatter.** Des clés comme `title` peuvent être traduites, les valeurs de `slug` peuvent changer, ou une valeur traduite peut rendre le YAML invalide. Le français place une espace avant les deux-points : `title: Installer la CLI : guide rapide` est donc du YAML invalide (l’analyseur `yaml` signale une correspondance imbriquée). La valeur doit être placée entre guillemets. * **Attributs HTML.** Traduisez le texte de `alt` et de `title`. Conservez `class` et les autres identifiants ; ne modifiez `src` ou `href` que via une correspondance explicite de ressources localisées ou d'URL. * **Imports MDX et JSX.** Si `import Tabs from '@theme/Tabs'` est traduit comme une phrase, ou si `` devient ``, la compilation échoue. Le [guide Crowdin de Docusaurus](https://docusaurus.io/docs/i18n/crowdin#mdx) prévient que les outils qui interprètent le JSX comme du HTML peuvent produire du JSX invalide, et que les props dont les valeurs sont des objets ou des tableaux sont les plus exposées. * **Encadrés.** Docusaurus reconnaît `:::note`, `:::tip`, `:::info`, `:::warning` et `:::danger` comme [mots-clés](https://docusaurus.io/docs/markdown-features/admonitions). Un `:::astuce` traduit n'en fait pas partie : l'encadré s'affiche alors en texte brut. * **Tableaux.** Un tableau GFM n'est reconnu que si la ligne d'en-tête comporte le même nombre de cellules que la ligne de séparation, et une barre verticale littérale dans une cellule doit être échappée sous la forme `\|` ([spécification GFM](https://github.github.com/gfm/#tables-extension-)). Un traducteur qui ajoute une barre verticale ou un saut de ligne dans une cellule casse la ligne. Voici un fichier source, suivi d'un exemple de sortie présentant chacune de ces défaillances. Cet exemple regroupe les problèmes en un seul endroit et ne provient d'aucun outil en particulier. ```mdx --- title: Install the CLI slug: /install --- import Tabs from '@theme/Tabs'; ## Install the CLI {/* #install */} Run `npm install my-cli`, then read the [setup guide](/docs/setup#api-keys). :::tip Use a package manager you already have. ::: ``` ```mdx --- titre: Installer la CLI : guide rapide slug: /installer --- importer Tabs depuis '@theme/Tabs'; ## Installer la CLI {/* #installer */} Exécutez `npm installer my-cli`, puis lisez le [guide](/docs/configuration#cles-api). :::astuce Utilisez un gestionnaire de paquets que vous avez déjà. ::: ``` Le second fichier contient une clé de frontmatter traduite, du YAML invalide, un slug modifié, un import que MDX ne parvient pas à analyser, un nouvel identifiant de titre, une commande cassée, un lien mort, un encadré inconnu et un composant qui n'existe pas. ## Comment traduire du Markdown et du MDX ### a) Traduction de documents avec Google ou DeepL La traduction de documents de [Google Cloud Translation](https://docs.cloud.google.com/translate/docs/supported-formats) (édition Advanced) accepte les fichiers Word, PDF, PowerPoint et Excel, mais pas le Markdown ; sa traduction de texte prend en charge le texte brut ou le HTML. L'[API DeepL](https://developers.deepl.com/docs/api-reference/document) propose la traduction de documents Markdown (`.md`) en version bêta, mais ne mentionne pas le MDX. Dans les deux cas, testez le résultat sur vos propres fichiers avant de vous y fier pour des blocs de code et du frontmatter. ### b) Utiliser un AST pour séparer le texte de la syntaxe [remark](https://github.com/remarkjs/remark) analyse le Markdown et le convertit en arborescence [mdast](https://github.com/syntax-tree/mdast). L'exemple d'extraction suivant parcourt les nœuds `text` en ignorant le code, les attributs et le frontmatter. Il constitue un bon point de départ pour inspecter le contenu, mais ne remplace pas un pipeline de traduction complet : ```js // extract.mjs: npm i unified remark-parse remark-stringify remark-mdx // remark-frontmatter remark-gfm remark-directive unist-util-visit import { readFileSync } from 'node:fs'; import { unified } from 'unified'; import remarkParse from 'remark-parse'; import remarkFrontmatter from 'remark-frontmatter'; import remarkGfm from 'remark-gfm'; import remarkMdx from 'remark-mdx'; import remarkDirective from 'remark-directive'; import remarkStringify from 'remark-stringify'; import { visit } from 'unist-util-visit'; const processor = unified() .use(remarkParse) .use(remarkFrontmatter, ['yaml']) // le frontmatter devient un seul nœud `yaml` .use(remarkGfm) // tableaux .use(remarkMdx) // import/export et JSX .use(remarkDirective) // encadrés :::tip .use(remarkStringify); const tree = processor.parse(readFileSync(process.argv[2], 'utf8')); // Cette démonstration n'extrait que les nœuds de texte. Le texte affiché dans les attributs // et le frontmatter doit être traité séparément dans un traducteur destiné à la production. const segments = []; visit(tree, 'text', (node) => { if (node.value.trim()) segments.push(node); }); console.log(segments.map((n) => JSON.stringify(n.value)).join('\n')); // Remplace un appel de traduction : chaque segment est modifié sur place. for (const node of segments) node.value = node.value.toUpperCase(); console.log('\n' + processor.stringify(tree)); ``` Exécuté sur le fichier source ci-dessus, auquel on a ajouté un bloc `bash` délimité et un tableau à deux colonnes, `node extract.mjs guide.mdx` a produit les segments suivants (extrait) : ```text "Install the CLI " "Run " ", then read the " "setup guide" "." "Use " "a package manager" " you already have." ``` Le fichier resérialisé a conservé le contenu du frontmatter, l’import, l’ID de titre, le code intégré, la destination du lien, le nom de l’encadré, les attributs JSX et le contenu du bloc de code, tout en mettant les nœuds de texte en majuscules. En revanche, le formatage n’a pas été conservé à l’octet près. Trois limites sont apparues : * **Les phrases arrivent en morceaux.** "Run … then read the … setup guide" se découpe en cinq segments : un traducteur ne peut donc pas réorganiser les mots autour du code et du lien. En production, les scripts traduisent un paragraphe entier en remplaçant les nœuds intégrés par des espaces réservés. * **Une partie du texte ne se trouve pas dans des nœuds `text`.** Le texte `alt` des images, les valeurs d’attributs JSX comme une prop `title` et les valeurs du frontmatter telles que `title` nécessitent un traitement spécifique. * **La sortie est reformatée.** `remark-stringify` a réaligné les colonnes du tableau, si bien que le diff affiche des lignes que vous n’avez pas modifiées. L’analyse syntaxique permet aussi de repérer les erreurs de syntaxe en amont. Un suffixe de titre `{#install}` de style Mintlify a fait échouer `remark-mdx` avec le message "Could not parse expression with acorn", car en MDX, les accolades ouvrent une expression JavaScript. Docusaurus accepte également la forme commentaire `{/* #install */}`, que `docusaurus write-heading-ids --syntax mdx-comment` peut générer pour vous. Le remplacement en majuscules montre quel texte l’analyseur sélectionne ; il ne mesure pas la qualité de la traduction. Avant de mettre en place un pipeline de traduction, comparez les champs protégés avec la source, validez la syntaxe YAML et MDX, et lancez la véritable compilation de votre site pour repérer les imports, les liens ou les composants propres au framework qui seraient cassés. ### c) Un système de gestion de la traduction Un système de gestion de la traduction (TMS) analyse le fichier à votre place. Crowdin prend en charge nativement [Markdown](https://store.crowdin.com/md) et [MDX](https://store.crowdin.com/mdx), et sa [configuration des analyseurs](https://support.crowdin.com/parsers-configuration/) permet d'exclure les blocs de code ainsi que certains éléments du frontmatter ; par défaut, les fichiers MDX sont téléversés en MDX v1, la v2 se sélectionnant avec le type `mdx_v2`. Il vous reste toutefois à mapper les chemins source et de sortie, à assurer la synchronisation des fichiers dans la CI et à contourner le JSX mal interprété par l'analyseur. ### d) Fournir des règles à un LLM dans le prompt Un modèle qui reçoit le fichier entier peut conserver le contexte des paragraphes. Précisez les champs de texte affiché à traduire : la prose, le texte alt des images, les champs `title` et `description` du frontmatter, ainsi que les props de composants que vous désignez. Protégez le code, les clés structurelles, les imports, les noms de composants JSX et les mots-clés `:::`. N’autorisez les modifications d’URL que par le biais de votre correspondance personnalisée des paramètres régionaux, et exigez des guillemets YAML valides. Rien ne garantit le respect des règles d’un prompt : analysez donc le résultat, compilez le MDX et comparez le contenu protégé avec la source. ### Comparaison | Approche | Comprend la structure Markdown | MDX et JSX | Frontmatter | Maintient les traductions synchronisées | Votre effort | | --------------------------------------- | ------------------------------------ | ------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Traduction de documents Google ou DeepL | DeepL : `.md` en bêta ; Google : non | Non mentionné | Non testé ; à vérifier | Relancer pour chaque fichier | Faible, plus vérification | | Script remark | Oui, vous choisissez les nœuds | Oui, avec `remark-mdx` | À gérer vous-même | Détection des changements à écrire vous-même | Élevé | | TMS (Crowdin) | Oui | Natif, avec des limitations JSX documentées | Exclusion des clés choisies | Synchronisation via la CLI dans la CI | Moyen | | LLM avec des règles | Uniquement via les instructions | Uniquement via les instructions | Uniquement via les instructions | À scripter vous-même | Moyen, plus vérification | | CLI de General Translation | Traitement dédié du Markdown | Traitement dédié du MDX | Traduit les titres et descriptions Mintlify | Réutilise les traductions correspondantes lors des exécutions suivantes | Configurer les chemins source, relire le résultat, lancer la compilation du site | Pour un fichier `.md` ponctuel que vous relirez à la main, utilisez la prise en charge bêta du Markdown de DeepL. Si vous avez besoin d’un contrôle total sur un petit ensemble de fichiers stable, écrivez un script remark. Optez pour un TMS lorsque les traducteurs travaillent dans son éditeur, et pour un prompt LLM si vous voulez des brouillons rapides dont vous examinerez le diff. Choisissez General Translation pour une documentation qui évolue au fil des livraisons : il se charge de la génération et de la réutilisation, tandis que les fichiers traduits restent dans votre dépôt. ## Comment traduire du Markdown et du MDX avec General Translation Lorsque des fichiers Markdown et MDX se trouvent dans un dépôt qui évolue fréquemment, la CLI de General Translation, `gt`, peut les traduire à chaque exécution. Elle traduit les [fichiers MDX et Markdown](/docs/cli/reference/formats/mdx-md-files) en préservant leur syntaxe et leur formatage. Après avoir exécuté [`npx gt init`](/docs/cli/reference/commands/init) comme indiqué dans le [Démarrage rapide de la CLI](/docs/cli/quickstart), ajoutez une entrée `mdx` ou `md` sous `files` dans `gt.config.json` : ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "ja"], "files": { "mdx": { "include": ["docs/[locale]/**/*.mdx"] }, "md": { "include": ["docs/[locale]/**/*.md"] } } } ``` Exécutez ensuite [`npx gt translate`](/docs/cli/reference/commands/translate). La CLI lit les sources dans `docs/en/` et écrit les traductions dans `docs/fr/` et `docs/ja/`. Pour une documentation, quelques comportements sont à connaître : * **ID de titres.** Les suffixes `{#id}` de style Mintlify restent rattachés à leurs titres (`gt` 2.17.3 ou version ultérieure). * **Frontmatter.** Pour les sites Mintlify, les titres et descriptions du frontmatter sont traduits. * **Exécutions incrémentales.** Les traductions correspondantes issues d’exécutions précédentes sont réutilisées ; seul le contenu nouveau ou modifié est traduit et facturé. `--force` retraduit tout et écrase les modifications locales. * **Modifications manuelles.** La synchronisation des modifications vers la plateforme se fait sur activation volontaire, avec [`npx gt translate --save-local`](/docs/cli/reference/commands/translate) ou [`npx gt save-local`](/docs/cli/reference/commands/save-local). * **Liens et imports.** La réécriture des URL, des imports et des chemins de ressources par paramètre régional est expérimentale et s’active via des options telles que `--experimental-localize-static-urls`. Exécutez la commande [dans votre CI](/docs/cli/guides/generating-translations) avant la compilation, gérez les termes produit dans un [glossaire](/docs/platform/dashboard/guides/defining-context-for-translations) partagé avec l’application, et relisez la formulation dans l’[éditeur du tableau de bord](/docs/platform/dashboard/guides/reviewing-translations). Avant la publication, lancez la compilation et la vérification des liens pour chaque paramètre régional. (Consultez [General Translation vs. Google Translate](/kb/general-translation-vs-google-translate) et [General Translation vs. Crowdin](/kb/general-translation-vs-crowdin) pour une comparaison plus complète des compromis.) ## Points clés * Traduisez les phrases complètes et une sélection de champs de texte affiché, notamment le texte alternatif (alt), les valeurs du frontmatter et les props pertinentes. Préservez la syntaxe technique et les identifiants ; ne réécrivez les URL que par le biais d'une correspondance configurée. * La ponctuation française `" : "` peut casser un frontmatter YAML sans guillemets, et les suffixes de titre `{#id}` font échouer un analyseur MDX standard. * La traduction de documents de Google ne prend pas en charge le Markdown ; DeepL indique que `.md` est en bêta et ne mentionne pas le MDX. * La démonstration avec remark expose les nœuds de texte, mais un pipeline complet doit conserver le contexte des phrases et traiter le texte affiché situé hors de ces nœuds. * La CLI de General Translation traduit les fichiers `md` et `mdx` en préservant la syntaxe, et réutilise les traductions correspondantes lors des exécutions suivantes. ## Related questions - [Comment traduire des fichiers JSON i18n ?](https://generaltranslation.com/fr/kb/translate-json-files.mdx): Traduisez uniquement les valeurs de type chaîne de caractères d’un fichier JSON de paramètres régionaux. Conservez telles quelles les clés non plurielles, les espaces réservés comme {{name}} et les balises, mais attendez-vous à ce que les clés de pluriel varient selon la langue : le polonais exige inbox_few et inbox_many. Utilisez un outil ou une API qui prend en charge le format, puis analysez et validez le résultat avant la relecture. - [Comment rendre un site web multilingue ?](https://generaltranslation.com/fr/kb/make-website-multilingual.mdx): Choisissez où stocker les traductions (dans un proxy, un plugin de CMS, un constructeur de sites ou votre propre code), puis attribuez à chaque langue sa propre URL, comme le recommande Google. Traduisez les pages entières ainsi que les titres et les méta-descriptions, reliez les versions avec hreflang et proposez un sélecteur de langue plutôt que de rediriger automatiquement les visiteurs. - [Alternatives à Google Translate : General Translation vs Google Translate](https://generaltranslation.com/fr/kb/general-translation-vs-google-translate.mdx): Google Translate permet de traduire rapidement un texte ponctuel, mais pour livrer un produit dans une autre langue, il faut aussi traduire chaque chaîne de caractères dans son contexte, garantir la cohérence des termes, gérer correctement les variables et les formes plurielles, prévoir une relecture et mettre en place un processus de livraison. General Translation comprend le contexte de chaque chaîne de caractères dans votre code et automatise l’ensemble du workflow de localisation, du code à la relecture, jusqu’à chaque livraison. - [Alternatives à Crowdin : General Translation ou Crowdin](https://generaltranslation.com/fr/kb/general-translation-vs-crowdin.mdx): Choisissez General Translation pour conserver vos textes dans vos composants et générer les traductions lors de la compilation. Crowdin gère des projets de traduction articulés autour de fichiers de ressources, de traducteurs et de processus de révision, que les ingénieurs doivent connecter à l’application et maintenir à mesure que le produit évolue. Crowdin reste un choix solide pour la traduction communautaire de projets open source et les programmes pilotés par des prestataires. ## Previous and next questions - Previous question: [Comment traduire des sous-titres SRT sans casser la synchronisation ?](https://generaltranslation.com/fr/kb/translate-srt-subtitles.mdx) - Next question: [Comment trouver les chaînes codées en dur qui ne sont pas traduites ?](https://generaltranslation.com/fr/kb/find-hardcoded-strings.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/fr/kb/sitemap.md) for every article.