Tradurre Markdown è facile, finché non ti ritrovi con duecento pagine. A quel punto le parole non sono il problema: lo è tutto ciò che le circonda, dal codice che non deve cambiare ai link che devono continuare a funzionare, fino alla prossima release che aggiunge altre dieci pagine.
Questa guida è pensata per siti di documentazione, README, changelog e cartelle di blog scritti in Markdown o MDX.
Quale opzione scegliere?
| Ideale per | Limiti | |
|---|---|---|
| AI Glot | Una cartella di documentazione, più lingue, un glossario da rispettare, ogni release | Non serve per un breve paragrafo di un README |
| Una piattaforma di gestione delle traduzioni (Crowdin, Lokalise, Phrase) | Un team con un flusso di lavoro continuo, revisori e un collegamento al repository | Prima di tradurre la prima pagina, devi configurare un progetto e collegare il repository |
| DeepL | I documenti indicati: Word, PowerPoint, Excel, PDF, HTML, testo e altri | Markdown non è nell’elenco: devi incollare il testo o convertire prima il file |
| ChatGPT, Claude o un altro assistente | Una breve pagina | Devi incollare ogni pagina e inserire il glossario in ogni chat. Per ogni pagina devi controllare che il codice o i link non siano cambiati; inoltre, una cartella di documentazione voluminosa esaurisce il tuo limite di utilizzo |
| Un freelance o un’agenzia | La landing page e la pagina dei prezzi | Tempi lunghi, tariffa a parola e i file devi comunque prepararli tu |
Affida a una persona la revisione della pagina che vende il prodotto. Elabora la documentazione di riferimento con un motore di traduzione: è lì che si concentra il volume.
Perché AI Glot è adatto a una cartella di documentazione
- I contenuti entrano, la struttura resta intatta. Titoli, paragrafi, elementi degli elenchi e celle delle tabelle sono testo. Il codice, le destinazioni dei link, i blocchi HTML e i separatori delle tabelle restano invariati.
- La formattazione segue le parole. Il grassetto, il corsivo e il testo dei link restano associati alle parole a cui si riferiscono.
- Un unico glossario per tutto il sito di documentazione. I nomi dei prodotti e i termini dell’API sono coerenti in ogni pagina e anche nelle release successive.
- Un piano prima di spendere. Elenca ciò che ha rilevato e ciò che tradurrà.
- Un’intera cartella in un’unica operazione. Inserisci i file in uno ZIP e la struttura verrà ricreata.
Il percorso di un singolo file
- 1CaricaUn file .md o .mdx, oppure uno ZIPFino a 4 MB ciascuno
- 2Dì ciò di cui hai bisognoUna semplice fraseGratis
- 3Leggi il pianoRisultati, lingue, costoGratis
- 4ApprovaL'unico passaggio a pagamentoConsuma crediti
- 5ScaricaMarkdown tradottoCaricalo
Cosa cambia in una pagina
Cambia solo il testo. Il codice, il link e le chiavi del front matter restano invariati.
---title: Install the CLItitle: Installer la CLIslug: install---Run `npm install -g tool` and read the [guide](/it/docs/setup).Lancez `npm install -g tool` et lisez le [guide](/it/docs/setup).Cosa controllare in MDX
Import, tag dei componenti ed espressioni restano invariati. Così la pagina continua a essere compilata. Attenzione però al testo passato a un componente come prop, per esempio il titolo assegnato a una scheda. Fa parte del componente, non del testo, quindi controlla quelle poche stringhe alla fine.
Ancore dei titoli. Se il tuo sito crea un’ancora a partire dal testo del titolo, un titolo tradotto avrà una nuova ancora. Controlla i link che puntano a un titolo, come quello della sezione Install.
Come fare, passo dopo passo
1. Prova un file gratis. Il traduttore Markdown non richiede un account e accetta file fino a 2 MB e 5,000 parole.
2. Carica il file o un archivio ZIP della cartella nell’app.
3. Spiega in una frase cosa ti serve.
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 frase determina cosa viene tradotto in tutta la cartella. Una regola di stile, come “mantieni in inglese i nomi dei prodotti e i termini API”, va inserita nella seconda casella al momento dell’approvazione, perché si applica a ogni paragrafo man mano che viene scritto.
4. Aggiungi un glossario con i nomi dei prodotti, i termini API e le parole che vuoi tradurre sempre nello stesso modo. Come crearne uno.
5. Leggi il piano e scegli il livello di qualità.
Lite offre circa tre volte più parole per credito ed è più veloce: l’ideale per aggiornare in blocco la documentazione di riferimento. Standard è pensato per la pagina di destinazione. Un credito equivale a una parola con Standard.
6. Approva e scarica.
Una cartella di documentazione, più lingue
I numeri sono un esempio. Un file Markdown contiene una sola lingua, quindi ogni lingua è una copia tradotta della cartella.
Tre modi per usarlo
Dalla riga di comando è la scelta giusta per un repository di documentazione, perché gli stessi quattro passaggi possono essere eseguiti con uno script o in CI ogni volta che cambia l’inglese:
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.zipCon il tuo agente AI: collega AI Glot come server MCP. L’agente può leggere il tuo repository, suggerire i termini del glossario che trova, avviare il processo e rimettere i file al loro posto.
Nell’app: carica, fai clic, scarica. Ideale per una singola pagina.
Per integrare l’API, consulta la documentazione dell’API.
Verifica il risultato
Genera il sito della documentazione in una lingua tradotta e apri tre pagine: una con codice, una con una tabella e una con un link a un’altra pagina. Esegui il tuo solito controllo dei link, perché è lì che emerge un’eventuale modifica all’ancora. Conserva i file in inglese finché una persona che conosce la lingua non ha controllato le pagine più importanti.
Prezzi indica quanto costa un volume maggiore; con un account gratuito hai crediti per provare con una cartella reale.
I limiti indicati qui erano in vigore al momento della stesura: 4 MB per file Markdown, 200 file e 20 MB per ZIP, e 2 MB e 5,000 parole nello strumento gratuito. L’elenco di DeepL proviene dalla sua documentazione. I nomi dei file e il numero di pagine nei diagrammi sono esempi. Il tuo piano mostra i dati reali dei tuoi file ed è consultabile gratuitamente.