Come internazionalizzare e localizzare applicazioni Java

Come funziona l’internazionalizzazione Java

Il sistema i18n di Java si basa su due elementi:

• .properties file che memorizzano le tue stringhe tradotte
• La classe ResourceBundle che carica il file corretto in fase di esecuzione in base al locale dell’utente

Quando la tua app viene eseguita, ResourceBundle controlla il locale dell’utente e carica automaticamente il file corrispondente. Se manca una traduzione, torna al file predefinito in modo che nulla si interrompa.

Richiamare una stringa nel codice è semplice:

ResourceBundle bundle = ResourceBundle.getBundle("messages", Locale.FRENCH);
String greeting = bundle.getString("welcome.message");

ResourceBundle bundle = ResourceBundle.getBundle("messages", Locale.FRENCH);
String greeting = bundle.getString("welcome.message");

Questo è l’intero meccanismo. Il resto del lavoro di localizzazione avviene nei file .properties stessi, ed è per questo che strutturarli correttamente è importante.

Configurazione del tuo Resource Bundle

Un resource bundle è un insieme di file .properties che condividono un nome base comune. Il nome base è la parte del nome del file prima del suffisso del locale ed è ciò che ResourceBundle.getBundle() usa per trovare il file corretto in fase di esecuzione.

messages.properties # predefinito (di solito inglese)
messages_fr.properties # francese
messages_de.properties # tedesco
messages_es.properties # spagnolo

messages.properties         # default (usually English)
messages_fr.properties      # French
messages_de.properties      # German
messages_es.properties      # Spanish

Qui, messages è il nome base. Puoi chiamarlo come vuoi, ma dovrebbe riflettere ciò che il file contiene. Le applicazioni più grandi spesso utilizzano più resource bundle per mantenere le cose organizzate:

src/main/resources/
 messages.properties
 errors.properties
 emails.properties

src/main/resources/
  messages.properties
  errors.properties
  emails.properties

Java si aspetta un modello di denominazione specifico: basename_language.properties o basename_language_COUNTRY.properties per varianti regionali.

messages_fr.properties # francese
messages_fr_CA.properties # francese (Canada)
messages_pt_BR.properties # portoghese (Brasile)

messages_fr.properties       # French
messages_fr_CA.properties    # French (Canada)
messages_pt_BR.properties    # Portuguese (Brazil)

I codici lingua seguono ISO 639-1 e i codici paese seguono ISO 3166-1. Usare il formato sbagliato significa che ResourceBundle non troverà il file in fase di esecuzione.

Strutturazione dei file Java .properties

Ogni riga in un file .properties è una coppia chiave-valore separata da =.

welcome.message = Benvenuto nella nostra applicazione
error.login.invalid_credentials = Nome utente o password non validi
form.submit.button = Invia

welcome.message = Welcome to our application
error.login.invalid_credentials = Invalid username or password
form.submit.button = Submit

Oltre a utilizzare coppie chiave-valore, è importante sapere che il modo in cui scrivi il tuo file sorgente influisce direttamente sulla qualità delle tue traduzioni. Alcune best practice si applicano sempre, indipendentemente dal fatto che tu stia traducendo manualmente o utilizzando uno strumento di traduzione AI come PTC.

Le chiavi dovrebbero rendere ovvio dove e come viene utilizzata una stringa. Questo è importante quando gestisci centinaia di stringhe su più file.

Uso errato delle chiavi:

btn1 = Invia 
msg2 = Errore

btn1 = Submit 
msg2 = Error

form.submit.button = Invia 
error.login.invalid_credentials = Nome utente o password non validi

form.submit.button = Submit 
error.login.invalid_credentials = Invalid username or password

Scrivi la frase completa nel tuo file .properties e usa segnaposto numerati per il contenuto variabile invece di concatenare stringhe nel codice.

Errato (nel codice):

"Ciao, " + username + "! Hai " + count + " nuovi messaggi." 

"Hello, " + username + "! You have " + count + " new messages." 

dashboard.greeting = Ciao, {0}! Hai {1} nuovi messaggi.

dashboard.greeting = Hello, {0}! You have {1} new messages.

Molte lingue cambiano l’ordine delle parole e le regole di concordanza, quindi dividere le frasi in frammenti rende impossibile una traduzione corretta.

Alcune stringhe cambiano a seconda di un valore numerico. Invece di scrivere chiavi separate per singolare e plurale, usa un pattern ChoiceFormat direttamente nel tuo file .properties:

messages.count = {0,choice,0#nessun messaggio|1#un messaggio|1<{0} messaggi}

messages.count = {0,choice,0#no messages|1#one message|1<{0} messages}

Java elabora questo pattern in fase di esecuzione e restituisce la forma corretta in base al valore passato.

Caratteri come =, :, # e \ hanno un significato speciale nei file .properties:

• = o : separa le chiavi dai valori
• # o ! inizia un commento
• \ introduce sequenze di escape (come \n per la nuova riga)

Se devi usare questi caratteri in una stringa, usa l’escape con una barra rovesciata.

support.link = Visitaci su https\://support.example.com

support.link = Visit us at https\://support.example.com

Salva sempre i file .properties in UTF-8. Senza di esso, i caratteri non ASCII vengono corrotti e le traduzioni diventano illeggibili.

Se una stringa è visibile agli utenti, appartiene a un file .properties Le stringhe hardcoded non verranno tradotte e la tua app finirà per mostrare un mix di lingue.

Altre considerazioni sulla localizzazione Java

Non tutto ciò che deve essere localizzato si trova in un file .properties. Date, orari, numeri e valori di valuta vengono formattati nel codice in fase di esecuzione, e farli correttamente è importante tanto quanto le tue stringhe tradotte.

Java fornisce classi integrate per questo:

• DateTimeFormatter per la formattazione di data e ora sensibile al locale
• NumberFormat per numeri, percentuali e valori di valuta

Poiché questa guida si concentra sui file .properties e sulla loro traduzione, non li tratteremo in modo approfondito qui. La documentazione ufficiale di Java per DateTimeFormatter e NumberFormat è un buon punto di partenza.