Best practice per la localizzazione del software: guida completa per sviluppatori

Previeni i bug di traduzione nel processo di localizzazione del tuo software. Scopri la struttura del codice, la sintassi dei placeholder e i pattern dell’interfaccia utente. Include uno strumento di traduzione AI gratuito.

Quando non ti prepari per la localizzazione del software, i tuoi utenti francesi potrebbero ritrovarsi a vedere questo:

Il motivo? Perché il tuo codice assomiglia a questo:

<button style="width: 120px">Salva modifiche</button>

<button style="width: 120px">Save Changes</button>

Questa guida ti mostra come strutturare il tuo codice per la localizzazione fin dal primo giorno. Ogni sezione include esempi chiari ed evidenzia ciò che fa la differenza maggiore per la qualità della traduzione.

Cosa imparerai:

• Come utilizzare file separati per i contenuti localizzabili
• Best practice per la gestione di placeholder e contenuti dinamici
• Pattern di progettazione dell’interfaccia utente per l’espansione del testo
• Come caricare la lingua giusta per i tuoi utenti
• Come impostare traduzioni automatizzate

Suggerimento n. 1: utilizza file separati per i contenuti localizzabili

Translation tools can’t detect hard-coded strings in your source code. Move all user-facing text into resource files. This includes:

• Etichette dell’interfaccia utente, pulsanti e voci di menu
• Messaggi di errore e testo di convalida
• Modelli di email e notifiche
• Testo di aiuto, suggerimenti e testo placeholder
• Messaggi di successo/conferma

Utilizza le funzioni di internazionalizzazione del tuo framework invece di codificare stringhe.

Esempio React:

// Errato - hard-coded
<button>Submit</button>

// Corretto - utilizzando react-intl
<button>{t('submit_button')}</button>

// Wrong - hard-coded
<button>Submit</button>

// Right - using react-intl
<button>{t('submit_button')}</button>

Esempio WordPress:

// Errato - hard-coded
echo 'Submit';

// Corretto - utilizzando WordPress i18n
echo __( 'Submit', 'your-textdomain' );

// Wrong - hard-coded
echo 'Submit';

// Right - using WordPress i18n
echo __( 'Submit', 'your-textdomain' );

Esempio Rails:

# Errato - hard-coded
flash[:notice] = "Profile updated successfully"

# Corretto - utilizzando Rails I18n
flash[:notice] = t('profile.update_success')

# Wrong - hard-coded
flash[:notice] = "Profile updated successfully"

# Right - using Rails I18n
flash[:notice] = t('profile.update_success')

Seleziona il formato del file di risorse in base al tuo framework:

• .json – Framework JavaScript (React, Vue, Angular)
• .po/.pot – WordPress, PHP, Python (gettext)
• .yaml/.yml – Ruby on Rails
• .xml – Android (strings.xml)
• .xcstrings – iOS/macOS

Suggerimento n. 2: gestisci correttamente i placeholder e i contenuti dinamici

Quando il testo include valori dinamici come nomi utente, conteggi o date, utilizza i placeholder invece della concatenazione di stringhe.

Lingue diverse hanno ordini di parole diversi. La concatenazione interrompe questo processo dividendo le frasi in frammenti che non possono essere riordinati.

L’esempio seguente crea tre parti separate che i traduttori non possono riorganizzare. In lingue come il giapponese, dove l’ordine delle parole differisce dall’inglese, la traduzione diventa grammaticalmente scorretta.

Esempio errato (concatenazione di stringhe)

const name = 'John';
const message = 'Hello, ' + name + '!';

const name = 'John';
const message = 'Hello, ' + name + '!';

Esempi corretti

msgid "Hello, %s!"
msgstr ""

msgid "Hello, %s!"
msgstr ""

{
 "greeting": "Hello, {name}!"
}

{
  "greeting": "Hello, {name}!"
}

greeting: "Hello, %{name}!"

greeting: "Hello, %{name}!"

Assicurati di utilizzare una sintassi di placeholder che funzioni con il tuo framework:

Suggerimento n. 3: progetta l’interfaccia utente per l’espansione del testo

La lunghezza del testo cambia notevolmente tra le lingue. Layout a larghezza fissa, pulsanti e menu di navigazione si interrompono quando il testo si espande o quando si supportano lingue da destra a sinistra come l’arabo.

• Il testo tedesco è in genere il 30% più lungo dell’inglese
• Il francese è circa il 20% più lungo
• Le lingue asiatiche come il cinese e il giapponese sono spesso più brevi

Prima di iniziare a programmare, pensa a come le diverse lingue influiscono sullo spazio durante la fase di progettazione. Questo consente di risparmiare tempo per il debug dei problemi di layout in seguito.

Per i dettagli di implementazione e gli esempi di codice, consulta come prevenire problemi di layout con traduzioni lunghe.

Suggerimento n. 4: scrivi contenuti che si traducono bene

Una scrittura chiara e semplice produce traduzioni migliori. Un linguaggio complesso richiede più modifiche dopo la traduzione.

✓ Scrivi frasi complete con soggetti e azioni chiari.

Esempio corretto

"Non hai elementi salvati nel carrello."

"You have no saved items in your cart."

Questo afferma chiaramente cosa è vuoto (carrello) e cosa dovrebbe contenere (elementi salvati).

Esempio errato

"Nessun articolo nel carrello."

"No cart items."

Nell’esempio precedente mancano il soggetto (“tu”) e l’azione (“hai”). Questi frammenti potrebbero significare “Non c’è un carrello” o “Articoli non nel carrello”, a seconda di come vengono interpretati.

✓ Mantienilo semplice. Parole brevi e chiare producono traduzioni migliori rispetto a un vocabolario complesso.

Esempio corretto

"Rimuovi articolo dal carrello"

"Remove item from cart"

Esempio errato

"Elimina questo articolo dal tuo carrello"

"Eliminate this article from your shopping cart"

✓ Evita idiomi e riferimenti culturali.

Frasi come “un gioco da ragazzi” o “fare centro” non si traducono letteralmente e potrebbero non avere senso in altre culture.

Suggerimento n. 5: configura il rilevamento della lingua e il caricamento dei file

Configura la tua applicazione per rilevare la lingua dell’utente e caricare il file di traduzione appropriato. La maggior parte dei framework moderni include librerie i18n che gestiscono automaticamente questo processo.

• React con react-i18next

React non include i18n per impostazione predefinita. Installa react-i18next con npm, quindi configuralo per rilevare la lingua del browser e caricare i tuoi file di traduzione.

• Ruby on rails

Rails include I18n per impostazione predefinita. Configuralo in config/application.rb. Quindi, rileva la lingua dell’utente nel tuo ApplicationController.

• WordPress

WordPress gestisce automaticamente il rilevamento della lingua. Gli utenti impostano la lingua del sito in Impostazioni → Generale e WordPress carica il file .mo corrispondente da wp-content/languages/. Per i siti multilingue in cui utenti diversi necessitano di lingue diverse, è necessario un plugin come WPML per gestire la selezione della lingua per singolo utente.

Gestisci le traduzioni mancanti

Imposta la tua lingua di fallback sulla tua lingua principale. Quando un file di traduzione non esiste o mancano delle stringhe, gli utenti vedono il fallback invece di testo interrotto o chiavi di traduzione.

Aggiungi un selettore di lingua (se necessario)

La maggior parte delle applicazioni dovrebbe rispettare automaticamente le impostazioni della lingua del browser o del dispositivo dell’utente. Ma se vuoi consentire agli utenti di sovrascriverlo manualmente, cosa comune per le applicazioni web, aggiungi un selettore di lingua e memorizza la loro scelta:

// Salva la selezione manuale della lingua dell'utente
localStorage.setItem('userLanguage', selectedLanguage);

// Controlla prima la selezione manuale, quindi utilizza l'impostazione predefinita del browser
const userLanguage = localStorage.getItem('userLanguage') || navigator.language;

// Save user's manual language selection
localStorage.setItem('userLanguage', selectedLanguage);

// Check for manual selection first, then use browser default
const userLanguage = localStorage.getItem('userLanguage') || navigator.language;

Le app per dispositivi mobili in genere non includono selettori di lingua poiché gli utenti si aspettano che le app seguano le impostazioni del proprio dispositivo.

Suggerimento n. 6: automatizza il processo di traduzione del tuo software

I flussi di lavoro di traduzione manuale rallentano ogni rilascio. Quando aggiorni le stringhe, le traduzioni devono avvenire automaticamente.

PTC è uno strumento di traduzione AI che automatizza questo processo. Puoi integrarlo con il tuo repository GitHub, GitLab o Bitbucket oppure utilizzare l’API per l’integrazione CI/CD. Quando aggiorni le stringhe, le traduzioni avvengono automaticamente.

La creazione di un account è gratuita e puoi tradurre 2.500 parole in 2 lingue senza alcun costo. Dopodiché, non ci sono costi di abbonamento: paghi solo per ciò che traduci.

Suggerimento n. 7: testa le versioni localizzate prima del lancio

Il test garantisce che le tue traduzioni vengano visualizzate correttamente e che la tua interfaccia utente funzioni in diverse lingue. Testa sia la visualizzazione che la funzionalità.

• Layout: il testo si adatta senza troncamento, senza overflow, la navigazione funziona
• Funzionalità: i moduli vengono inviati, i messaggi di errore vengono visualizzati correttamente, la ricerca gestisce i caratteri speciali (é, ñ, ü)
• Formattazione: date (GG/MM vs. MM/GG), numeri (1.000,00 vs 1.000,00), posizioni valuta (€100 vs 100€)