# General Translation Knowledge Base: Come tradurre Markdown e MDX senza compromettere la sintassi? URL: https://generaltranslation.com/it/kb/translate-markdown-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduci il testo descrittivo, il testo alt delle immagini, i titoli e le descrizioni nel frontmatter e le props dei componenti che mostrano testo. Lascia invariati blocchi di codice, codice inline, import, nomi dei componenti JSX, chiavi del frontmatter e URL dei link, a meno che una mappatura dei locale non li riscriva. Racchiudi tra virgolette i valori YAML tradotti, quindi esegui la build del sito. Category: Traduzione Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Un file Markdown combina testo descrittivo e sintassi tecnica. MDX aggiunge JavaScript tramite righe `import`, componenti JSX ed `{expressions}` che un compilatore deve poter analizzare anche dopo la traduzione. Prima di tradurre, stabilisci quali campi contengono testo visualizzato: il `title` di un componente potrebbe dover essere tradotto, mentre il suo `id` deve restare invariato. ## Cosa si rompe quando il Markdown passa per un traduttore generico Un traduttore che considera il file come testo semplice tratta tutto il contenuto come linguaggio naturale. Ecco gli errori da verificare: * **Blocchi di codice e codice inline.** Comandi e identificatori possono venire tradotti, per cui `npm install` può diventare `npm installer`. * **URL e ancore dei link.** Uno slug o un `#fragment` in un link può venire tradotto e finire per non puntare più da nessuna parte. Inoltre, le intestazioni tradotte ricevono nuovi ID generati, il che rompe tutti i link `#anchor` che vi fanno riferimento; per questo motivo Docusaurus consiglia di usare [ID espliciti per le intestazioni](https://docusaurus.io/docs/i18n/tutorial#translate-markdown-files). * **Frontmatter.** Chiavi come `title` possono venire tradotte, i valori di `slug` possono cambiare, oppure un valore tradotto può rendere lo YAML non valido. In francese si inserisce uno spazio prima dei due punti, quindi `title: Installer la CLI : guide rapide` non è YAML valido (il parser `yaml` segnala una mappatura annidata). Il valore va racchiuso tra virgolette. * **Attributi HTML.** Traduci il testo di `alt` e `title`. Mantieni invariati `class` e gli altri identificatori; modifica `src` o `href` solo tramite una mappatura esplicita di risorse o URL localizzati. * **Import MDX e JSX.** Se `import Tabs from '@theme/Tabs'` viene tradotto come una frase, o se `` diventa ``, la build fallisce. La [guida Crowdin di Docusaurus](https://docusaurus.io/docs/i18n/crowdin#mdx) avverte che gli strumenti che interpretano JSX come HTML possono produrre JSX non valido e che le props con valori di tipo oggetto o array sono le più soggette a errori. * **Admonition.** Docusaurus riconosce `:::note`, `:::tip`, `:::info`, `:::warning` e `:::danger` come [parole chiave](https://docusaurus.io/docs/markdown-features/admonitions). Un `:::astuce` tradotto non lo è, quindi il riquadro viene renderizzato come testo semplice. * **Tabelle.** Una tabella GFM viene riconosciuta solo se la riga di intestazione ha lo stesso numero di celle della riga di delimitazione, e una barra verticale letterale all'interno di una cella deve essere sottoposta a escape come `\|` ([specifica GFM](https://github.github.com/gfm/#tables-extension-)). Un traduttore che aggiunge una barra verticale o un a capo all'interno di una cella rompe la riga. Ecco un file sorgente e un esempio di output che presenta tutti questi errori. L'esempio riunisce i problemi in un unico punto e non corrisponde all'output di uno strumento specifico. ```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à. ::: ``` Il secondo file contiene una chiave del frontmatter tradotta, YAML non valido, uno slug modificato, un import che MDX non riesce ad analizzare, un nuovo ID di intestazione, un comando non funzionante, un link non valido, un'admonition sconosciuta e un componente inesistente. ## Come tradurre Markdown e MDX ### a) Traduzione di documenti con Google o DeepL La traduzione di documenti di [Google Cloud Translation](https://docs.cloud.google.com/translate/docs/supported-formats) (edizione Advanced) supporta file Word, PDF, PowerPoint ed Excel, ma non Markdown; la traduzione di testo, invece, accetta testo semplice o HTML. L'[API di DeepL](https://developers.deepl.com/docs/api-reference/document) indica la traduzione di documenti Markdown (`.md`) come funzionalità in beta e non cita MDX. In entrambi i casi, verifica l'output sui tuoi file prima di affidargli blocchi di codice e frontmatter. ### b) Usare un AST per separare il testo dalla sintassi [remark](https://github.com/remarkjs/remark) esegue il parsing del Markdown e lo converte in un albero [mdast](https://github.com/syntax-tree/mdast). Il seguente esempio di estrazione visita i nodi `text` e salta il codice, gli attributi e il frontmatter. È un buon punto di partenza per ispezionare i contenuti, ma non è una pipeline di traduzione completa: ```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']) // il frontmatter diventa un unico nodo `yaml` .use(remarkGfm) // tabelle .use(remarkMdx) // import/export e JSX .use(remarkDirective) // avvisi :::tip .use(remarkStringify); const tree = processor.parse(readFileSync(process.argv[2], 'utf8')); // Questa dimostrazione estrae solo i nodi di testo. Il testo visualizzato negli attributi // e nel frontmatter va gestito separatamente in un traduttore per la produzione. const segments = []; visit(tree, 'text', (node) => { if (node.value.trim()) segments.push(node); }); console.log(segments.map((n) => JSON.stringify(n.value)).join('\n')); // Sostituto di una chiamata di traduzione: sostituisce ogni segmento in-place. for (const node of segments) node.value = node.value.toUpperCase(); console.log('\n' + processor.stringify(tree)); ``` Eseguito sul file sorgente riportato sopra, con l'aggiunta di un blocco di codice delimitato `bash` e di una tabella a due colonne, `node extract.mjs guide.mdx` ha restituito questi segmenti (estratto): ```text "Install the CLI " "Run " ", then read the " "setup guide" "." "Use " "a package manager" " you already have." ``` Il file riserializzato ha mantenuto il contenuto del frontmatter, l'import, l'ID dell'intestazione, il codice inline, la destinazione del link, il nome dell'admonition, gli attributi JSX e il contenuto del blocco di codice, convertendo in maiuscolo i nodi di testo. Non ha però mantenuto la formattazione byte per byte. Sono emersi tre limiti: * **Le frasi arrivano a pezzi.** "Run … then read the … setup guide" è suddivisa in cinque segmenti, quindi un traduttore non può riordinare le parole attorno al codice e al link. Gli script usati in produzione traducono l'intero paragrafo, sostituendo i nodi inline con dei segnaposto. * **Non tutto il testo si trova nei nodi `text`.** Il testo `alt` delle immagini, i valori degli attributi JSX come una prop `title` e i valori del frontmatter come `title` vanno gestiti a parte. * **L'output viene riformattato.** `remark-stringify` ha ricalcolato la spaziatura delle colonne della tabella, quindi il diff mostra righe che non hai modificato. Il parsing, inoltre, fa emergere subito gli errori di sintassi. Un suffisso di intestazione `{#install}` in stile Mintlify ha fatto fallire `remark-mdx` con l'errore "Could not parse expression with acorn", perché in MDX le parentesi graffe aprono un'espressione JavaScript. Docusaurus accetta anche la forma a commento `{/* #install */}`, che puoi generare automaticamente con `docusaurus write-heading-ids --syntax mdx-comment`. La sostituzione in maiuscolo mostra quale testo viene selezionato dal parser, ma non misura la qualità della traduzione. Prima di adottare una pipeline di traduzione, confronta i campi protetti con la sorgente, valida la sintassi YAML e MDX ed esegui la build reale del sito per individuare import, link o componenti specifici del framework non funzionanti. ### c) Un sistema di gestione delle traduzioni Un sistema di gestione delle traduzioni (TMS) esegue il parsing del file al posto tuo. Crowdin supporta nativamente [Markdown](https://store.crowdin.com/md) e [MDX](https://store.crowdin.com/mdx), e la sua [configurazione del parser](https://support.crowdin.com/parsers-configuration/) consente di escludere i blocchi di codice e determinati elementi del frontmatter; per impostazione predefinita i file MDX vengono caricati come MDX v1, mentre per la v2 occorre selezionare il tipo `mdx_v2`. Resta comunque necessario mappare i percorsi sorgente e di output, sincronizzare i file in CI e trovare soluzioni alternative per il JSX che il parser interpreta in modo errato. ### d) Fornire a un LLM un prompt con regole Un modello che riceve l'intero file può mantenere il contesto dei paragrafi. Specifica quali campi di testo visualizzato tradurre, come la prosa, il testo alt delle immagini, `title` e `description` nel frontmatter e determinate props dei componenti, indicate per nome. Proteggi il codice, le chiavi strutturali, gli import, i nomi dei componenti JSX e le parole chiave `:::`; consenti modifiche agli URL solo tramite la tua mappatura dei locale e richiedi un uso corretto delle virgolette YAML. Nulla garantisce che le regole di un prompt vengano rispettate, quindi analizza il risultato, compila l'MDX e confronta il contenuto protetto con la sorgente. ### Confronto | Approccio | Comprende la struttura Markdown | MDX e JSX | Frontmatter | Mantiene le traduzioni sincronizzate | Il tuo impegno | | ------------------------------------------ | ------------------------------- | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Traduzione di documenti con Google o DeepL | DeepL `.md` in beta; Google no | Non indicato | Non testato; da verificare | Da rieseguire per ogni file | Basso, più le verifiche | | Script remark | Sì, decidi tu quali nodi | Sì, con `remark-mdx` | Lo gestisci tu | Il rilevamento delle modifiche lo scrivi tu | Alto | | TMS (Crowdin) | Sì | Nativo, con limitazioni JSX documentate | Esclude le chiavi scelte | Sincronizzazione tramite CLI in CI | Medio | | LLM con regole | Solo tramite istruzioni | Solo tramite istruzioni | Solo tramite istruzioni | Lo automatizzi tu con uno script | Medio, più le verifiche | | CLI di General Translation | Elaborazione Markdown dedicata | Elaborazione MDX dedicata | Traduce titoli e descrizioni di Mintlify | Riutilizza le traduzioni corrispondenti nelle esecuzioni successive | Configurare i percorsi sorgente, revisionare l'output, eseguire la build del sito | Usa il supporto Markdown in beta di DeepL per un singolo file `.md` da revisionare a mano. Scrivi uno script remark quando ti serve il pieno controllo su un insieme di file ridotto e stabile. Usa un TMS se i traduttori lavorano nel suo editor. Usa un prompt LLM per bozze rapide di cui controllerai il diff. Scegli General Translation per una documentazione che cambia a ogni rilascio: si occupa di generazione e riutilizzo, mentre i file tradotti restano nel tuo repository. ## Come tradurre Markdown e MDX con General Translation Quando i file Markdown e MDX si trovano in un repository che cambia spesso, la CLI di General Translation, `gt`, può tradurli a ogni esecuzione. Traduce i [file MDX e Markdown](/docs/cli/reference/formats/mdx-md-files) mantenendone intatte la sintassi e la formattazione. Dopo aver eseguito [`npx gt init`](/docs/cli/reference/commands/init) come indicato nell'[Avvio rapido della CLI](/docs/cli/quickstart), aggiungi una voce `mdx` o `md` sotto `files` in `gt.config.json`: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "ja"], "files": { "mdx": { "include": ["docs/[locale]/**/*.mdx"] }, "md": { "include": ["docs/[locale]/**/*.md"] } } } ``` Quindi esegui [`npx gt translate`](/docs/cli/reference/commands/translate). La CLI legge i file sorgente da `docs/en/` e scrive le traduzioni in `docs/fr/` e `docs/ja/`. Per la documentazione sono importanti alcuni comportamenti: * **ID delle intestazioni.** I suffissi `{#id}` in stile Mintlify restano associati alle rispettive intestazioni (`gt` 2.17.3 o versioni successive). * **Frontmatter.** Per i siti Mintlify, i titoli e le descrizioni nel frontmatter vengono tradotti. * **Esecuzioni incrementali.** Le traduzioni corrispondenti delle esecuzioni precedenti vengono riutilizzate, mentre i contenuti nuovi o modificati vengono tradotti e addebitati. `--force` ritraduce tutto e sovrascrive le modifiche locali. * **Modifiche manuali.** La sincronizzazione delle modifiche è opt-in e avviene tramite [`npx gt translate --save-local`](/docs/cli/reference/commands/translate) o [`npx gt save-local`](/docs/cli/reference/commands/save-local). * **Link e import.** La riscrittura di URL, import e percorsi degli asset per ogni impostazione regionale è sperimentale e si attiva con flag come `--experimental-localize-static-urls`. Eseguilo [in CI](/docs/cli/guides/generating-translations) prima della build, gestisci i termini di prodotto in un [Glossario](/docs/platform/dashboard/guides/defining-context-for-translations) condiviso con l'app e rivedi i testi nell'[editor della Dashboard](/docs/platform/dashboard/guides/reviewing-translations). Prima della pubblicazione, esegui la build e verifica i link per ogni impostazione regionale. (Per un confronto più ampio dei pro e contro, consulta [General Translation vs. Google Translate](/kb/general-translation-vs-google-translate) e [General Translation vs. Crowdin](/kb/general-translation-vs-crowdin).) ## Punti chiave * Traduci frasi complete e una selezione di campi con testo visualizzato, tra cui testo alt, valori del frontmatter e props pertinenti. Preserva la sintassi tecnica e gli identificatori; riscrivi gli URL solo tramite una mappatura configurata. * La punteggiatura francese `" : "` può rendere non valido il frontmatter YAML senza virgolette, e i suffissi di intestazione `{#id}` mandano in errore un parser MDX standard. * Il servizio di traduzione di documenti di Google non supporta Markdown; DeepL indica `.md` come beta e non menziona MDX. * La dimostrazione con remark espone i nodi di testo, ma una pipeline completa deve preservare il contesto delle frasi e gestire anche il testo visualizzato al di fuori di quei nodi. * La CLI di General Translation traduce i file `md` e `mdx` preservandone la sintassi e riutilizza le traduzioni corrispondenti nelle esecuzioni successive. ## Related questions - [Come si traducono i file JSON di i18n?](https://generaltranslation.com/it/kb/translate-json-files.mdx): Traduci solo i valori stringa di un file JSON di impostazione regionale. Lascia invariati le chiavi non plurali, i segnaposto come {{name}} e i tag, ma tieni presente che le chiavi plurali cambiano da una lingua all'altra: il polacco, ad esempio, richiede inbox_few e inbox_many. Usa uno strumento o un'API in grado di gestire il formato, quindi esegui il parsing dell'output e validalo prima della revisione. - [Come si rende multilingue un sito web?](https://generaltranslation.com/it/kb/make-website-multilingual.mdx): Scegli dove gestire le traduzioni (in un proxy, in un plugin del CMS, in un site builder o nel tuo codice), poi assegna a ogni lingua un URL dedicato, come raccomanda Google. Traduci le pagine per intero, compresi titoli e meta description, collega le versioni con hreflang e offri un selettore della lingua anziché reindirizzare automaticamente i visitatori. - [Alternative a Google Translate: General Translation vs. Google Translate](https://generaltranslation.com/it/kb/general-translation-vs-google-translate.mdx): Google Translate è un modo rapido per tradurre testi occasionali, ma pubblicare un prodotto in un'altra lingua richiede anche che ogni stringa sia tradotta nel suo contesto, con termini coerenti, variabili e plurali corretti, una revisione e un processo di rilascio. General Translation comprende il contesto di ogni stringa nel tuo codice e automatizza l'intero flusso di lavoro di localizzazione, dal codice alla revisione fino a ogni rilascio. - [Alternative a Crowdin: General Translation o Crowdin](https://generaltranslation.com/it/kb/general-translation-vs-crowdin.mdx): Scegli General Translation per mantenere i testi nei tuoi componenti e generare le traduzioni durante la build. Crowdin gestisce progetti di traduzione incentrati su file di risorse, traduttori e flussi di lavoro di revisione, che gli ingegneri devono collegare all'app e mantenere man mano che il prodotto evolve. Crowdin resta un'ottima scelta per le traduzioni affidate alla community nei progetti open source e per i programmi gestiti da fornitori esterni. ## Previous and next questions - Previous question: [Come si trovano le stringhe hardcoded non tradotte?](https://generaltranslation.com/it/kb/find-hardcoded-strings.mdx) - Next question: [Internazionalizzazione vs. localizzazione (i18n vs. l10n)](https://generaltranslation.com/it/kb/internationalization-vs-localization.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.