Localizzare l'app

Android è in esecuzione su molti dispositivi in molte regioni. Per raggiungere la maggior parte degli utenti, assicurati che la tua app gestisca testo, file audio, numeri, valute e grafici in modi adeguati alle convenzioni dei luoghi in cui viene utilizzata.

Questa pagina descrive le best practice per la localizzazione delle app Android.

Devi avere una conoscenza pratica di Kotlin e conoscere il caricamento delle risorse Android, le considerazioni sullo sviluppo come il ciclo di vita delle attività e i principi generali di internazionalizzazione e localizzazione.

È una buona pratica utilizzare il framework delle risorse Android per separare il più possibile gli aspetti localizzati dell'app dalla funzionalità principale dell'app.

• Inserisci la maggior parte o tutti i contenuti dell'interfaccia utente dell'app nei file di risorse, come descritto in questa pagina e nella panoramica delle risorse dell'app.
• Il comportamento dell'interfaccia utente, d'altra parte, è determinato dal codice basato su Kotlin. Ad esempio, se gli utenti inseriscono dati che devono essere formattati o ordinati in modo diverso a seconda delle impostazioni internazionali, devi utilizzare Kotlin per gestire i dati a livello di programmazione. Questa pagina non spiega come localizzare il codice basato su Kotlin.

Questa guida illustra il sistema di localizzazione Android principale utilizzato in tutte le app Android. Per scoprire come caricare queste risorse localizzate nell'interfaccia utente di Jetpack Compose, consulta la sezione Risorse in Compose.

Per una breve guida alla localizzazione delle stringhe nell'app, consulta la sezione Supportare lingue e culture diverse.

Panoramica: cambio di risorse in Android

Le risorse sono stringhe di testo, suoni, grafici e altri dati statici di cui la tua app per Android ha bisogno. Un'app può includere più set di risorse, ognuno personalizzato per una configurazione del dispositivo diversa. Quando un utente esegue l'app, Android seleziona e carica automaticamente le risorse che corrispondono meglio al dispositivo.

Questa pagina è incentrata sulla localizzazione e sulle impostazioni internazionali. Per una descrizione completa del cambio di risorse e di tutti i tipi di configurazioni che puoi specificare, come l'orientamento dello schermo o il tipo di touchscreen, consulta la sezione Fornire risorse alternative.

Quando scrivi l'app, crei risorse predefinite e alternative da utilizzare. Quando gli utenti eseguono l'app, il sistema Android seleziona le risorse da caricare in base alle impostazioni internazionali del dispositivo. Per creare risorse, inserisci i file nelle sottodirectory con nomi speciali della directory res/ del progetto.

Perché le risorse predefinite sono importanti

Quando l'app viene eseguita in impostazioni internazionali per cui non hai fornito testo specifico, Android carica le stringhe predefinite da res/values/strings.xml. Se questo file predefinito non è presente o se manca una stringa di cui l'app ha bisogno, l'app non viene eseguita e mostra un errore. L'esempio seguente illustra cosa può succedere quando il file di testo predefinito è incompleto.

Esempio:

Il codice basato su Kotlin di un'app fa riferimento solo a due stringhe, text_a e text_b. L'app include un file di risorse localizzato (res/values-en/strings.xml) che definisce text_a e text_b in inglese. L'app include anche un file di risorse predefinito (res/values/strings.xml) che include una definizione per text_a, ma non per text_b.

• Quando questa app viene avviata su un dispositivo con le impostazioni internazionali impostate sull'inglese, l'app potrebbe essere eseguita senza problemi, perché res/values-en/strings.xml contiene entrambe le stringhe di testo necessarie.
• Tuttavia, quando questa app viene avviata su un dispositivo impostato su una lingua diversa dall'inglese, l'utente vede un messaggio di errore e un pulsante Forza chiusura. L'app non viene caricata.

Per evitare questa situazione, assicurati che esista un file res/values/strings.xml e che definisca ogni stringa necessaria. Questa situazione si applica a tutti i tipi di risorse, non solo alle stringhe: devi creare un set di file di risorse predefiniti contenenti tutte le risorse che l'app chiama, come elementi disegnabili, caratteri o colori. Per informazioni sui test, consulta la sezione Testare le risorse predefinite.

Utilizzare le risorse per la localizzazione

Questa sezione spiega come creare risorse predefinite e risorse alternative. Spiega anche come viene assegnata la precedenza alle risorse e come fare riferimento alle risorse nel codice.

Creare risorse predefinite

Inserisci il testo predefinito dell'app in res/values/strings.xml. Per queste stringhe, utilizza la lingua predefinita, ovvero la lingua che prevedi che la maggior parte degli utenti dell'app parli.

Il set di risorse predefinito include anche tutti gli elementi disegnabili predefiniti e può includere altri tipi di risorse come icone o stringhe. Queste risorse si trovano nelle seguenti directory:

• res/drawable/: directory obbligatoria contenente almeno un file grafico, per l'icona dell'app su Google Play
• res/xml/: obbligatoria se hai cartelle res/xml-<qualifiers>
• res/raw/: obbligatoria se hai cartelle res/raw-<qualifiers>

Creare risorse alternative

Una parte importante della localizzazione di un'app è fornire testo alternativo per lingue diverse. In alcuni casi, fornisci anche grafici, suoni e altre risorse specifiche per le impostazioni internazionali alternative.

Un'app può specificare molte res/<qualifiers>/ directory, ognuna con qualificatori diversi. Per creare una risorsa alternativa per impostazioni internazionali diverse, utilizza un qualificatore che specifica una lingua o una combinazione lingua-regione. Il nome di una directory delle risorse deve essere conforme allo schema di denominazione descritto nella sezione Fornire risorse alternative, altrimenti l'app non può essere compilata.

Esempio:

Supponiamo che la lingua predefinita dell'app sia l'inglese e che tu voglia localizzare tutto il testo dell'app in francese e tutto il testo tranne il titolo dell'app in giapponese. In questo caso, crei tre file strings.xml, ognuno archiviato in una directory delle risorse specifica per le impostazioni internazionali:

1. res/values/strings.xml
   Contiene il testo in inglese per tutte le stringhe utilizzate dall'app, incluso il testo per una stringa denominata title.
2. res/values-fr/strings.xml
   Contiene il testo in francese per tutte le stringhe, incluso title.
3. res/values-ja/strings.xml
   Contiene il testo in giapponese per tutte le stringhe tranne title.

Se il codice basato su Kotlin fa riferimento a R.string.title, ecco cosa succede in fase di runtime:

• Se il dispositivo è impostato su una lingua diversa dal francese, Android carica title dal file res/values/strings.xml.
• Se il dispositivo è impostato sul francese, Android carica title dal file res/values-fr/strings.xml.

Se il dispositivo è impostato sul giapponese, Android cerca title nel file res/values-ja/strings.xml. Tuttavia, poiché in questo file non è inclusa alcuna stringa di questo tipo, Android torna alla stringa predefinita e carica title in inglese dal file res/values/strings.xml.

A quali risorse viene assegnata la precedenza?

Se più file di risorse corrispondono alla configurazione di un dispositivo, Android segue un insieme di regole per decidere quale file utilizzare. Tra i qualificatori che possono essere specificati nel nome di una directory delle risorse, le impostazioni internazionali hanno quasi sempre la precedenza.

Esempio:

Supponiamo che un'app includa un set predefinito di grafici e altri due set di grafici, ognuno ottimizzato per una configurazione del dispositivo diversa:

• res/drawable/
  Contiene grafici predefiniti.
• res/drawable-small-land-stylus/
  Contiene grafici ottimizzati per l'uso con un dispositivo che prevede l'input da uno stilo e ha uno schermo QVGA a bassa densità in orientamento orizzontale.
• res/drawable-ja/
  Contiene grafici ottimizzati per l'uso con il giapponese.

Se l'app viene eseguita su un dispositivo configurato per utilizzare il giapponese, Android carica i grafici da res/drawable-ja/, anche se il dispositivo prevede l'input da uno stilo e ha uno schermo QVGA a bassa densità in orientamento orizzontale.

Eccezione: gli unici qualificatori che hanno la precedenza sulle impostazioni internazionali nel processo di selezione sono il Mobile Country Code (MCC) e il Mobile Network Code (MNC).

Esempio:

Supponiamo di avere la seguente situazione:

• Il codice dell'app richiede R.string.text_a.
• Sono disponibili due file di risorse pertinenti:
  • res/values-mcc404/strings.xml, che include text_a nella lingua predefinita dell'app, in questo caso l'inglese.
  • res/values-hi/strings.xml, che include text_a in hindi.
• L'app è in esecuzione su un dispositivo con la seguente configurazione:
  • La scheda SIM è connessa a una rete mobile in India (MCC 404).
  • La lingua è impostata su hindi (hi).

Android carica text_a da res/values-mcc404/strings.xml (in inglese), anche se il dispositivo è configurato per l'hindi. Questo perché nel processo di selezione delle risorse, Android preferisce una corrispondenza MCC a una corrispondenza linguistica.

Il processo di selezione non è sempre semplice come suggeriscono questi esempi. Per una descrizione più dettagliata del processo, consulta la sezione Come Android trova la risorsa che corrisponde meglio. Tutti i qualificatori sono descritti ed elencati in ordine di precedenza nella panoramica delle risorse dell'app.

Fare riferimento alle risorse nel codice

Nel codice basato su Kotlin dell'app, fai riferimento alle risorse utilizzando la sintassi R.resource_type.resource_name o android.R.resource_type.resource_name. Per ulteriori informazioni, consulta la sezione Accedere alle risorse dell'app.

Gestire le stringhe per la localizzazione

Questa sezione descrive le best practice per la gestione delle stringhe relative alla localizzazione.

Spostare tutte le stringhe in strings.xml

Quando crei le app, non codificare le stringhe. Dichiara invece tutte le stringhe come risorse in un file strings.xml predefinito, in modo da poterle aggiornare e localizzare facilmente. Le stringhe nel file strings.xml possono essere estratte, tradotte e integrate facilmente nell'app, con i qualificatori appropriati, senza apportare modifiche al codice compilato.

Ad esempio, con Compose puoi caricare una stringa come questa:

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

Se generi immagini con testo, inserisci anche queste stringhe in strings.xml e rigenera le immagini dopo la traduzione.

Seguire le linee guida di Android per le stringhe dell'interfaccia utente

Quando progetti e sviluppi le UI, presta molta attenzione a come ti rivolgi all'utente. In generale, utilizza uno stile conciso, amichevole ma breve e uno stile coerente in tutte le UI.

Assicurati di leggere e seguire i consigli di Material Design per lo stile di scrittura e la scelta delle parole. In questo modo, le tue app appariranno più raffinate per l'utente e gli utenti comprenderanno più rapidamente la tua UI.

Inoltre, utilizza sempre la terminologia standard di Android, ove possibile, ad esempio per gli elementi dell'interfaccia utente come la barra delle app, il menu Opzioni, la barra di sistema e le notifiche. L'utilizzo corretto e coerente dei termini di Android semplifica la traduzione e produce un prodotto finale migliore per gli utenti.

Fornire un contesto sufficiente per le stringhe dichiarate

Quando dichiari le stringhe nel file strings.xml, assicurati di descrivere il contesto in cui viene utilizzata la stringa. Queste informazioni sono preziose per il traduttore e si traducono in una traduzione di qualità migliore. Ti aiutano anche a gestire le stringhe in modo più efficace.

Ecco un esempio:

<!-- The action for submitting a form. This text is on a button that can fit 30 chars -->
<string name="login_submit_button">Sign in</string>

Valuta la possibilità di fornire informazioni sul contesto come le seguenti:

• A cosa serve questa stringa? Quando e dove viene presentata all'utente?
• Dove si trova questa stringa nell'interfaccia utente? Ad esempio, le traduzioni sono meno flessibili nei pulsanti rispetto alle caselle di testo.

Contrassegnare le parti dei messaggi che non devono essere tradotte

Spesso, le stringhe contengono testo che non deve essere tradotto in altre lingue. Esempi comuni sono un pezzo di codice, un segnaposto per un valore, un simbolo speciale o un nome. Quando prepari le stringhe per la traduzione, cerca e contrassegna il testo che deve rimanere invariato, senza traduzione, in modo che il traduttore non lo modifichi.

Per contrassegnare il testo che non deve essere tradotto, utilizza un tag segnaposto <xliff:g>. Ecco un esempio di tag che indica che il testo "%1$s" non deve essere modificato durante la traduzione, per evitare di interrompere il messaggio:

<string name="countdown">
  <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday
</string>

Quando dichiari un tag segnaposto, aggiungi un attributo ID che spiega a cosa serve il segnaposto. Se in un secondo momento l'app sostituisce il valore del segnaposto, assicurati di fornire un attributo di esempio per chiarire l'utilizzo previsto.

Ecco altri esempi di tag segnaposto:

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
<!-- Example placeholder for a special Unicode symbol -->
<string name="star_rating">Check out our 5
    <xliff:g id="star">\u2605</xliff:g>
</string>
<!-- Example placeholder for a URL -->
<string name="app_homeurl">
    Visit us at <xliff:g
    id="application_homepage">http://my/app/home.html</xliff:g>
</string>
<!-- Example placeholder for a name -->
<string name="prod_name">
    Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g>
</string>
<!-- Example placeholder for a literal -->
<string name="promo_message">
    Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount.
</string>
...
</resources>

Elenco di controllo per la localizzazione

Per una panoramica completa del processo di localizzazione e distribuzione di un'app per Android, consulta la sezione Tradurre e localizzare le app.

Suggerimenti per la localizzazione

Segui questi suggerimenti quando localizzi l'app.

Progettare l'app in modo che funzioni in qualsiasi impostazione internazionale

Non dare per scontato nulla sul dispositivo su cui un utente esegue la tua app. Il dispositivo potrebbe avere hardware che non avevi previsto o potrebbe essere impostato su impostazioni internazionali che non avevi pianificato o che non puoi testare. Progetta l'app in modo che funzioni normalmente o che non funzioni correttamente, indipendentemente dal dispositivo su cui viene eseguita.

Importante: assicurati che l'app includa un set completo di risorse predefinite: includi le cartelle res/drawable/ e res/values/ senza modificatori aggiuntivi nei nomi delle cartelle, che contengono tutte le immagini e il testo di cui l'app ha bisogno.

Se a un'app manca anche una sola risorsa predefinita, non viene eseguita su un dispositivo impostato su impostazioni internazionali non supportate. Ad esempio, se il file predefinito res/values/strings.xml non contiene una stringa di cui l'app ha bisogno, quando l'app viene eseguita in impostazioni internazionali non supportate e tenta di caricare res/values/strings.xml, l'utente vede un messaggio di errore e un pulsante Forza chiusura.

Per ulteriori informazioni, consulta la sezione Testare le risorse predefinite.

Evitare di creare più file di risorse e stringhe di testo del necessario

Probabilmente non devi creare un'alternativa specifica per le impostazioni internazionali per ogni risorsa dell'app. Ad esempio, un logo dell'app definito nella directory res/drawable/ potrebbe funzionare in qualsiasi impostazione internazionale, nel qual caso non è necessario creare file grafici alternativi.

Inoltre, potresti non dover creare testo alternativo per ogni stringa. Ad esempio, supponiamo che:

• La lingua predefinita dell'app sia l'inglese americano. Ogni stringa utilizzata dall'app è definita, utilizzando l'ortografia inglese americana, in res/values/strings.xml.
• Per alcune frasi importanti, vuoi fornire l'ortografia inglese britannica. Vuoi che queste stringhe alternative vengano utilizzate quando l'app viene eseguita su un dispositivo nel Regno Unito.

Per farlo, crea un piccolo file denominato res/values-en-rGB/strings.xml che includa solo le stringhe diverse quando l'app viene eseguita nel Regno Unito. Per tutte le altre stringhe, l'app torna alle impostazioni predefinite e utilizza ciò che è definito in res/values/strings.xml.

Utilizzare LocalConfiguration per la ricerca manuale delle impostazioni internazionali

Puoi cercare le impostazioni internazionali utilizzando LocalConfiguration che Android rende disponibile, come mostrato nell'esempio seguente:

val locale = LocalConfiguration.current.locales[0]

Utilizzare il servizio di traduzione app

Il servizio di traduzione app è integrato in Play Console. Ti consente di ottenere un preventivo immediato ed effettuare un ordine presso una società di traduzione. Puoi ordinare traduzioni in una o più lingue per le stringhe dell'interfaccia utente dell'app, il testo della scheda del Play Store, i nomi degli acquisti in-app e il testo della campagna pubblicitaria.

Utilizzare Gemini per tradurre le stringhe dell'app

Puoi utilizzare Gemini in Android Studio per tradurre le risorse stringa dell'app direttamente nel progetto. Per ulteriori informazioni, consulta la sezione Tradurre e localizzare le app.

Testare le app localizzate

Testa l'app localizzata su un dispositivo o utilizzando l'emulatore Android. In particolare, testa l'app per assicurarti che siano incluse tutte le risorse predefinite necessarie.

Testare su un dispositivo

Tieni presente che il dispositivo su cui stai eseguendo il test potrebbe essere significativamente diverso dai dispositivi disponibili per i consumatori in altri luoghi. Le impostazioni internazionali disponibili sul tuo dispositivo possono differire da quelle disponibili su altri dispositivi. Inoltre, la risoluzione e la densità dello schermo del dispositivo potrebbero essere diverse, il che può influire sulla visualizzazione di stringhe ed elementi disegnabili nell'interfaccia utente.

Per modificare le impostazioni internazionali o la lingua su un dispositivo, utilizza l'app Impostazioni.

Testare con le anteprime dei componibili

Prima di eseguire il test su un dispositivo, puoi utilizzare le anteprime dei componibili in Android Studio per testare le UI localizzate senza eseguire il deployment su un emulatore. Per visualizzare l'anteprima della UI in lingue diverse, utilizza l'annotazione @Preview (ad esempio @Preview(locale = "fr")). Puoi anche testare i layout da destra a sinistra (RTL) specificando impostazioni internazionali RTL come @Preview(locale = "ar").

Testare su un emulatore

Per i dettagli sull'utilizzo dell'emulatore, consulta la sezione Eseguire app sull'emulatore Android.

Creare e utilizzare impostazioni internazionali personalizzate

Le impostazioni internazionali "personalizzate" sono una combinazione di lingua o regione che l'immagine di sistema Android non supporta esplicitamente. Puoi testare il funzionamento dell'app in impostazioni internazionali personalizzate creando impostazioni internazionali personalizzate nell'emulatore. Esistono due modi per farlo:

• Utilizza l'app Impostazioni internazionali personalizzate, accessibile dalla scheda dell'app. Dopo aver creato impostazioni internazionali personalizzate, passa a queste toccando e tenendo premuto il nome delle impostazioni internazionali.
• Passa a impostazioni internazionali personalizzate dalla shell adb, come descritto nella sezione seguente.

Quando imposti l'emulatore su impostazioni internazionali non disponibili nell'immagine di sistema Android, il sistema stesso viene visualizzato nella lingua predefinita. Tuttavia, l'app viene localizzata correttamente.

Modificare le impostazioni internazionali dell'emulatore dalla shell adb

Per modificare le impostazioni internazionali nell'emulatore utilizzando la shell adb, procedi nel seguente modo:

1. Scegli le impostazioni internazionali che vuoi testare e determina il relativo tag di lingua BCP-47, ad esempio fr-CA per il francese canadese.
2. Avvia un emulatore.
3. Da una shell della riga di comando sul computer host, esegui il seguente comando:
   adb shell
   oppure, se hai un dispositivo collegato, specifica che vuoi l'emulatore aggiungendo l'opzione -e:
   adb -e shell
4. Al prompt della shell adb (#), esegui questo comando:
   setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
   Sostituisci le sezioni tra parentesi quadre con i codici appropriati del passaggio 1.
   
   Ad esempio, per eseguire il test in francese canadese:
   setprop persist.sys.locale fr-CA;stop;sleep 5;start

In questo modo l'emulatore viene riavviato. Quando viene visualizzata di nuovo la schermata Home, riavvia l'app e l'app viene avviata con le nuove impostazioni internazionali.

Testare le risorse predefinite

Per verificare se un'app include tutte le risorse stringa di cui ha bisogno, procedi nel seguente modo:

1. Imposta l'emulatore o il dispositivo su una lingua non supportata dall'app. Ad esempio, se l'app ha stringhe in francese in res/values-fr/ ma non ha stringhe in spagnolo in res/values-es/, imposta le impostazioni internazionali dell'emulatore sullo spagnolo. Puoi utilizzare l'app Impostazioni internazionali personalizzate per impostare l'emulatore su impostazioni internazionali non supportate.
2. Esegui l'app.
3. Se l'app mostra un messaggio di errore e un pulsante Forza chiusura, potrebbe essere alla ricerca di una stringa non disponibile. Assicurati che il file res/values/strings.xml includa una definizione per ogni stringa utilizzata dall'app.

Se il test ha esito positivo, ripetilo per altri tipi di configurazioni. Ad esempio, se l'app ha un file di stringhe denominato res/values-land/strings.xml ma non contiene un file denominato res/values-port/strings.xml, imposta l'emulatore o il dispositivo sull'orientamento verticale e verifica se l'app viene eseguita.

Risorse aggiuntive

Per ulteriori informazioni sulla localizzazione, consulta le seguenti risorse aggiuntive:

Documentazione

• Panoramica delle risorse dell'app
• Tradurre e localizzare le app

Visualizzare i contenuti

• Localizzare l'app (Visualizzazioni)