Come localizzare un file README per GitHub e progetti open source

Tradotto con l’IA di Lara Translate

La maggior parte dei progetti open source la scrivono sviluppatori che parlano in inglese. Però le persone che usano quei progetti — e che potrebbero contribuirvi — parlano tutte le lingue. Se il tuo README è solo in inglese, escludi silenziosamente una buona parte dei tuoi potenziali utenti e collaboratori. Localizzare un file README online è una delle cose più efficaci e meno costose che puoi fare per rendere un progetto open source più accogliente a livello internazionale. In questa guida ti spieghiamo come farlo nel modo giusto — dalle regole per nominare i file al flusso di lavoro per la traduzione, fino a come tenere sincronizzate le versioni localizzate quando cambia il README in inglese.

Perché è importante: GitHub non fornisce traduzioni automatiche. Quando uno sviluppatore di Tokyo o San Paolo apre il tuo repository, vede il tuo README in inglese esattamente come l’hai scritto. Gli sviluppatori di lingua giapponese, cinese, coreana, tedesca e portoghese brasiliano sono una forza importante su GitHub — fornire un README nella loro lingua non è una cortesia, ma un contributo alla salute del tuo progetto.

Perché i file README multilingue sono importanti per l’open source

Alcune delle community di collaboratori open source più attive al mondo si trovano in paesi in cui l’inglese non è la lingua principale. Un README pieno di termini tecnici, con lunghe istruzioni di installazione o contenuti tecnici difficili da capire in un’altra lingua riduce le probabilità che uno sviluppatore internazionale si coinvolga — e rende quasi impossibile aprire una PR o un issue.

Oltre che per i singoli collaboratori, i file README multilingue migliorano anche la visibilità. I dev che cercano su GitHub nella loro lingua madre trovano i progetti con README localizzati più utili ed è più probabile che li aggiungano ai preferiti, li forkino e li consiglino nelle loro community.

Come strutturare i file README multilingue su GitHub

Non esiste uno standard ufficiale di GitHub, ma la convenzione usata dai progetti grandi e ben mantenuti è coerente:
Tieni il README.md principale in inglese. Crea versioni specifiche per la locale usando i tag linguistici BCP 47 o i codici ISO 639-1 come suffissi dei nomi dei file: README.ja.md per il giapponese, README.de.md per il tedesco, README.zh-CN.md per il cinese semplificato, README.pt-BR.md per il portoghese brasiliano.
In cima a README.md, prima di qualsiasi altro contenuto, aggiungi un selettore di lingua:

**Read this in other languages:** [日本語](README.ja.md) | [Deutsch](README.de.md) | [Português](README.pt-BR.md)

Ogni README localizzato segue la stessa struttura dell’originale in inglese: stesse sezioni, stesso ordine, stessi link ai badge (gli URL dei badge rimandano a servizi esterni e non devono mai essere modificati), testo tradotto.

Cosa tradurre e cosa lasciare così com’è

Da tradurre: titoli delle sezioni, paragrafi esplicativi, istruzioni di installazione (le parti in prosa), descrizioni d’uso, linee guida per i contributi e spiegazioni sulla licenza.
Non tradurre: blocchi di codice ed esempi di comandi, URL dei badge e sintassi Markdown dei badge, URL dei repository, nomi e percorsi dei file, nomi di variabili e chiavi di configurazione, e nomi delle lingue nel selettore in alto.
Problema da tenere d’occhio: esempi di comando come npm install package-name o git clone https://github.com/user/repo vengono tradotti solo in parte. Se uno strumento non capisce i blocchi di codice, genererà istruzioni errate che non funzioneranno quando l’utente proverà a seguirle.

Come tradurre un file README con Lara

1. Vai su laratranslate.com/translate-markdown
2. Carica il tuo file README.md
3. Seleziona l’inglese come lingua di partenza e la tua lingua di destinazione
4. Aggiungi un glossario con il nome del tuo progetto, i nomi delle librerie e i termini tecnici che non vanno tradotti
5. Scegli lo stile di traduzione Faithful per garantire la precisione tecnica
6. Scarica il file di output e salvalo come README.[locale].md nella cartella principale del tuo repository

Per più lingue, usa il caricamento in blocco di Lara per tradurre lo stesso README in diverse locale in un’unica sessione.

Mantenere sincronizzati i file README localizzati

La parte più difficile della localizzazione dei README non è la prima traduzione — è mantenere aggiornate le versioni per le varie locale man mano che il progetto si evolve. Un README accurato sei mesi fa potrebbe contenere passaggi di installazione obsoleti, flag deprecati o non includere un’importante sezione nuova.
Un approccio pratico per i progetti attivi: ogni volta che traduci un README, annota l’hash del commit della versione inglese in un commento HTML all’inizio di ogni file localizzato — non verrà visualizzato su GitHub, ma ti fornirà una traccia verificabile dell’aggiornamento della traduzione. Se il README in inglese cambia in modo significativo, ritraduci le sezioni interessate e aggiorna l’hash.
Per i progetti con pipeline CI/CD, l’API di Lara può attivare una nuova traduzione ogni volta che il README in inglese cambia nel branch principale.

Aggiungere i file README localizzati al repository

1. Metti i file tradotti nella cartella principale del tuo repository, accanto a README.md
2. Aggiorna i link del selettore di lingua in cima a README.md
3. Esegui il commit e il push sul tuo branch principale
4. Verifica che i link del selettore di lingua funzionino correttamente su GitHub

GitHub esegue il rendering dei file .md automaticamente nella visualizzazione del repository quando seguono la convenzione di denominazione README.

FAQ

GitHub mostra automaticamente i file README localizzati in base alla lingua dell’utente?
No. GitHub non mostra file README localizzati in base alle impostazioni della lingua del browser. Gli utenti devono cliccare su un link nel selettore di lingua. Ecco perché il selettore di lingua dovrebbe essere la primissima cosa in README.md, prima di qualsiasi altro contenuto.

Lara traduce i miei comandi bash e gli esempi di codice?
No. Il processore Markdown di Lara riconosce i code fence (tripli backtick) e il codice inline (backtick singoli) e li lascia completamente invariati. I comandi di installazione, gli esempi di codice e i frammenti di configurazione saranno identici nell’output tradotto.

Cosa devo fare con il badge Markdown nel mio README?
La sintassi dei badge come [![Build Status](https://img.shields.io/...)](https://link) contiene URL esterni che non devono essere modificati. Lara protegge gli URL dei link e i percorsi delle immagini, quindi i badge vengono visualizzati correttamente nei README tradotti senza alcuna modifica manuale.

Come gestisco le intestazioni usate come anchor link?
Quando le intestazioni vengono tradotte, il loro formato di ancoraggio cambia (GitHub genera gli ID di ancoraggio in base al testo dell’intestazione). Se il tuo README usa la sintassi [jump to section](#section-name), aggiorna i riferimenti di ancoraggio in modo che corrispondano al testo dell’intestazione tradotto. Dopo la traduzione, controlla i link dell’indice.

Posso mantenere aggiornati automaticamente i README tradotti?
La memoria di traduzione di Lara garantisce risultati coerenti nel tempo e l’API supporta trigger di traduzione automatica in una pipeline CI/CD. Per flussi di lavoro più semplici, ritradurre il README aggiornato tramite l’interfaccia web e confrontare l’output è efficiente per la maggior parte dei progetti open source.

Questo articolo tratta di

• Spiegare perché i file README multilingue sono importanti per i progetti open source e per le community internazionali di sviluppatori su GitHub.
• Illustrare la convenzione standard per la denominazione dei file e la struttura del selettore di lingua per i README localizzati su GitHub.
• Identificare cosa tradurre (il testo) e cosa lasciare così com’è (blocchi di codice, URL dei badge, esempi di comandi).
• Mostrare la procedura passo dopo passo per tradurre un README con Lara Translate e fare il commit nel repository.
• Affrontare la sfida continua di mantenere sincronizzati i README localizzati con la versione originale in inglese man mano che il progetto si evolve.

Localizza il tuo README

Carica il tuo README.md su laratranslate.com/translate-markdown e ottieni una traduzione con sintassi corretta, pronta per il commit nel tuo repository.
Anche in questa serie:

• Come tradurre file Markdown online senza alterare la sintassi [2026]
• Come localizzare la documentazione per sviluppatori scritta in Markdown