Tradotto con l’IA di Lara Translate
Lanciare il tuo prodotto in più lingue senza fornire la documentazione in più lingue è un lavoro fatto a metà. Gli utenti nei tuoi mercati di riferimento possono usare un prodotto localizzato, ma quando incontrano un problema di configurazione o devono seguire una guida all’installazione, si ritrovano di nuovo a dover analizzare un testo tecnico complesso in inglese. È in quel momento che le richieste di assistenza aumentano vertiginosamente e l’adozione del prodotto si blocca. Localizzare la documentazione per sviluppatori è più difficile che localizzare l’interfaccia utente di un prodotto perché il contenuto è più tecnico, più variabile e ha maggiori probabilità di contenere elementi che non dovrebbero mai essere tradotti: codice, comandi, sintassi di configurazione. Se sbagli questi elementi, non hai solo un errore di traduzione. Hai una documentazione che confonde gravemente gli sviluppatori.
|
TL;DR
|
Risposta breve
Per localizzare la documentazione per sviluppatori scritta in Markdown: scrivi e mantieni aggiornata tutta la documentazione in inglese, traduci i file .md a ogni ciclo di rilascio usando Lara Translate (che protegge automaticamente i code fence, i comandi CLI, il front matter e gli URL dei link) e inserisci i file tradotti nella directory i18n del tuo framework. Docusaurus, MkDocs e Hugo li mostreranno automaticamente agli utenti nella locale corrispondente.
Perché è importante: Gli acquirenti enterprise in Giappone, Germania e Francia spesso richiedono la documentazione localizzata come condizione per l’acquisto. Nelle comunità di sviluppatori dei mercati non anglofoni, l’adozione di strumenti con documentazione solo in inglese è notevolmente più bassa. E i costi dell’assistenza aumentano direttamente quando gli utenti non riescono a risolvere i problemi consultando la documentazione nella loro lingua.
Localizza la tua documentazione per sviluppatori senza modificare il codice
Carica i tuoi file di documentazione .md. Lara preserva gli esempi di codice, i comandi CLI, il front matter e la sintassi dei link, e traduce solo il testo. Caricamento in blocco, memoria di traduzione e oltre 200 lingue.
Chi ha bisogno di localizzare la documentazione per sviluppatori
Aziende software che si espandono in mercati non anglofoni — in particolare Giappone, Germania, Francia, Brasile e Corea — dove le comunità di sviluppatori hanno forti preferenze per i contenuti tecnici nella loro lingua madre. Le doc API e i tutorial di integrazione disponibili solo in inglese creano difficoltà che la documentazione localizzata elimina.
Aziende di tool per sviluppatori che creano prodotti utilizzati a livello globale: piattaforme CI/CD, SDK cloud, librerie per sviluppatori. Se il tuo sito di documentazione serve sviluppatori in 30 paesi, avere doc solo in inglese ti mette in svantaggio rispetto ai concorrenti che le hanno localizzate.
Fornitori di software aziendale che pubblicano la documentazione tecnica insieme alle versioni localizzate dei prodotti. In Germania, Giappone e Francia, la documentazione localizzata è spesso un requisito per l’approvvigionamento.
Progetti open source con community internazionali che vogliono rendere più facile per i collaboratori non anglofoni capire le convenzioni del progetto, l’architettura e le linee guida per i contributi.
Come i framework di documentazione Markdown gestiscono l’i18n
I tre framework di documentazione basati su Markdown più diffusi supportano tutti l’internazionalizzazione e, in fondo, funzionano tutti allo stesso modo: tu fornisci i file .md tradotti; il framework si occupa del routing e della pubblicazione.
Docusaurus
Se esegui docusaurus write-translations, vengono estratti i testi dell’interfaccia utente. I contenuti della documentazione si trovano in docs/. Le traduzioni specifiche per la locale vanno in i18n/[locale]/docusaurus-plugin-content-docs/current/, riproducendo il nome del file e la struttura delle directory originali. Docusaurus mostra la versione tradotta agli utenti la cui lingua del browser o il cui percorso URL corrisponde alla locale.
MkDocs con tema Material
MkDocs Material supporta più lingue tramite mkdocs.yml e il plugin i18n. Il plugin mappa i file .md di origine alle versioni tradotte specifiche per la locale. Il tema gestisce gli elementi dell’interfaccia utente; il contenuto della documentazione sono i tuoi file tradotti.
Hugo
Hugo offre il supporto multilingue nativo. I contenuti per ogni lingua si trovano in directory separate (content/en/, content/ja/) o si distinguono tramite suffissi nei nomi dei file (getting-started.md vs getting-started.ja.md). La configurazione della lingua va in hugo.toml.
Cosa tradurre e cosa lasciare così com’è
Per la localizzazione della documentazione per sviluppatori ci sono regole più rigide rispetto alla traduzione di contenuti generici, e le conseguenze di eventuali errori sono più gravi.
Traduci sempre: spiegazioni concettuali, tutorial e guide pratiche, titoli di sezione, avvisi e note, descrizioni di parametri e tipi, e spiegazioni dei messaggi di errore (non i messaggi di errore stessi).
Non tradurre mai: blocchi di codice ed esempi di codice, istruzioni da riga di comando, contenuto dei file di configurazione, percorsi degli endpoint API, nomi delle variabili di ambiente, nomi di parametri e chiavi, nonché percorsi di file e nomi di directory.
Traduci con attenzione: valori del front matter come title e description (sì); valori tecnici come slug o layout (no); testo dei link (sì); URL dei link (no).
Il processore Markdown di Lara gestisce automaticamente i casi più evidenti — code fence, codice inline, URL dei link e percorsi delle immagini sono protetti per impostazione predefinita. Un glossario di progetto gestisce i nomi dei prodotti e le etichette delle funzionalità.
Creare un flusso di lavoro di localizzazione ripetibile
Stabilisci l’inglese come fonte di verità. Tutta la documentazione viene prima scritta e revisionata in inglese. I file localizzati derivano sempre dal testo di origine in inglese e non vengono mai aggiornati in modo indipendente.
Traduci in base alla frequenza dei rilasci. Alla fine di ogni sprint, traduci in batch tutti i file .md in inglese modificati usando il caricamento in blocco di Lara. Carica tutti i file modificati in una volta sola e scarica le versioni tradotte per ogni locale.
Usa la memoria di traduzione per mantenere la coerenza. Se un termine viene tradotto in un modo specifico nella versione 1.0, nella versione 2.0 verrà tradotto automaticamente allo stesso modo. Questo è particolarmente utile per la terminologia tecnica che ha una traduzione consolidata in ogni lingua di destinazione.
Crea un glossario di progetto. Includi il nome del tuo prodotto, i nomi delle funzionalità, le etichette dell’interfaccia utente e tutti i termini con traduzioni approvate specifiche per la lingua. A ogni traduzione, questi termini verranno applicati in modo coerente.
Consigli pratici per la documentazione su larga scala
Inizia dalle pagine con più traffico, non da tutto. Per prima cosa traduci la guida introduttiva, la panoramica di riferimento dell’API e gli articoli pratici più consultati. Per favorire l’adozione internazionale, una guida introduttiva tradotta è più efficace di un archivio completo di note di rilascio minori.
Non tradurre i documenti di riferimento generati automaticamente. Le referenze API generate dalle annotazioni del codice o dalle specifiche OpenAPI sono troppo tecniche e cambiano troppo rapidamente per poterle mantenere tradotte. Concentrati sui contenuti concettuali e sui tutorial.
Tieni i file localizzati nello stesso repository. Avere repository di traduzione separati crea problemi di sincronizzazione. Usare lo stesso repository significa che i file localizzati vengono versionati insieme alla versione originale in inglese e revisionati nello stesso flusso di lavoro PR.
Per le pagine più importanti, usa la revisione umana. Le guide per la prima configurazione, la documentazione sulla sicurezza e i tutorial di integrazione sono le pagine che i clienti aziendali esaminano con maggiore attenzione. Per queste pagine, far revisionare da un madrelingua il testo tradotto automaticamente è un investimento che vale la pena.
Inizia oggi stesso a localizzare la tua documentazione per sviluppatori
Caricamento in blocco, memoria di traduzione, glossario e protezione della sintassi per Docusaurus, MkDocs, Hugo e qualsiasi framework di documentazione basato su Markdown. Non serve la carta di credito.
FAQ
Posso usare Lara per tradurre un sito di documentazione Docusaurus?
Sì. Traduci i tuoi file .md in inglese con Lara usando il caricamento in blocco, poi inserisci i file di output in i18n/[locale]/docusaurus-plugin-content-docs/current/. Lara mantiene intatti il front matter, i blocchi di codice e la sintassi dei link, quindi i file si inseriscono nella struttura i18n di Docusaurus senza modifiche.
I file Markdown tradotti funzionano con MkDocs e con il tema Material?
Sì. Il plugin i18n di MkDocs Material accetta file .md tradotti con la convenzione di denominazione indicata nella tua configurazione mkdocs.yml. Purché l’output di Lara conservi il front matter e la struttura dei file, i file si integrano senza problemi.
Come faccio a gestire la documentazione che include admonition (blocchi nota, avvertenza, suggerimento)?
La sintassi delle admonition come !!! note o gli avvisi basati su blockquote è compatibile con Markdown. Lara considera i marker di admonition come sintassi strutturale e traduce il contenuto al loro interno. Controlla l’output per assicurarti che la parola chiave del tipo di avviso (note, warning, tip) non sia stata modificata — determina il rendering e deve rimanere in inglese.
E la documentazione che combina Markdown e MDX?
Il processore Markdown di Lara protegge i blocchi di codice e il codice inline, gestendo la maggior parte del JSX incorporato. Per i file MDX molto ricchi di componenti, controlla l’output per verificare se la sintassi JSX potrebbe essere stata alterata. I file MDX con molto testo si traducono in modo pulito.
Come gestisco un glossario di termini tecnici con traduzioni specifiche per i nostri mercati di destinazione?
Crea un glossario di progetto in Lara prima di eseguire la traduzione. Abbina ogni termine inglese alla relativa traduzione approvata in ciascuna lingua di destinazione. A ogni esecuzione della traduzione, queste associazioni vengono applicate in modo coerente a tutti i file, anche quando nel tempo vengono aggiunte nuove pagine alla documentazione.
Questo articolo tratta di
- Spiegare chi ha bisogno di localizzare la documentazione per sviluppatori e perché la documentazione solo in inglese crea problemi misurabili nei mercati internazionali.
- Mostrare come i principali framework di documentazione basati su Markdown (Docusaurus, MkDocs, Hugo) gestiscono l’i18n e dove finiscono i file tradotti.
- Definire cosa tradurre, cosa proteggere e cosa richiede un attento giudizio nella localizzazione della documentazione per sviluppatori.
- Analizzare un flusso di lavoro di localizzazione ripetibile: fonte di verità in inglese, raggruppamento per cicli di rilascio, memoria di traduzione e glossari di progetto.
- Consigli pratici per scalare la localizzazione della documentazione: definizione delle priorità, esclusione dei documenti di riferimento generati automaticamente e quando ricorrere alla revisione umana.
Localizza la tua documentazione per sviluppatori
Carica i tuoi file di documentazione .md su laratranslate.com/translate-markdown e ottieni traduzioni rispettose della sintassi e coerenti con la terminologia, pronte da inserire nel tuo framework di documentazione.
Anche in questa serie:
