Localizzare l'app

Android viene eseguito su molti dispositivi in molte regioni. Per raggiungere il maggior numero di utenti, assicurati che la tua app gestisca testo, file audio, numeri, valuta e grafica in modi appropriati per le impostazioni internazionali in cui viene utilizzata.

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

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

È buona norma utilizzare il framework delle risorse Android per separare il più possibile gli aspetti localizzati dell'app dalla funzionalità di base dell'app.

  • Inserisci la maggior parte o tutti i contenuti dell'interfaccia utente della tua app nei file di risorse, come descritto in questa pagina e nella panoramica delle risorse dell'app.
  • Il comportamento dell'interfaccia utente, invece, è gestito 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, utilizzi Kotlin per gestire i dati in modo programmatico. Questa pagina non spiega come localizzare il codice basato su Kotlin.

Questa guida illustra il sistema di localizzazione Android di base utilizzato in tutte le app per Android. Per scoprire come caricare queste risorse localizzate nella UI di Jetpack Compose, consulta Risorse in Compose.

Per una breve guida alla localizzazione delle stringhe nella tua app, consulta Supporta lingue e culture diverse.

Panoramica: cambio di risorse in Android

Le risorse sono stringhe di testo, suoni, elementi grafici e qualsiasi altro dato statico di cui l'app per Android ha bisogno. Un'app può includere più insiemi di risorse, ognuno personalizzato per una configurazione dispositivo diversa. Quando un utente esegue l'app, Android seleziona e carica automaticamente le risorse che meglio corrispondono al dispositivo.

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

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

Perché le risorse predefinite sono importanti

Quando l'app viene eseguita in un'impostazione internazionale per cui non hai fornito un testo specifico, Android carica le stringhe predefinite da res/values/strings.xml. Se questo file predefinito non è presente o se manca una stringa necessaria per l'app, l'app non viene eseguita e mostra un errore. L'esempio seguente illustra cosa può accadere 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 impostazioni internazionali impostate su 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 visualizza un messaggio di errore e un pulsante Chiusura forzata. 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 insieme di file di risorse predefiniti contenenti tutte le risorse chiamate dalla tua app, come elementi drawable, caratteri o colori. Per informazioni sui test, consulta la sezione Test per le risorse predefinite.

Utilizza le risorse per la localizzazione

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

Crea 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 venga parlata dalla maggior parte degli utenti della tua app.

Il set di risorse predefinito include anche tutti gli elementi drawable predefiniti e può includere altri tipi di risorse, come icone o stringhe. Queste risorse vengono inserite nelle seguenti directory:

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

Crea risorse alternative

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

Un'app può specificare molte directory res/<qualifiers>/, ciascuna con qualificatori diversi. Per creare una risorsa alternativa per un'altra lingua, utilizza un qualificatore che specifica una lingua o una combinazione di lingua e regione. Il nome di una directory delle risorse deve essere conforme allo schema di denominazione descritto in Fornisci risorse alternative, altrimenti l'app non può essere compilata.

Esempio:

Supponiamo che la lingua predefinita della tua app sia l'inglese e che tu voglia localizzare tutto il testo dell'app in francese e tutto il testo, ad eccezione del titolo dell'app, in giapponese. In questo caso, crei tre file strings.xml, ciascuno 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
    Contenere testo in francese per tutte le stringhe, incluso title.
  3. res/values-ja/strings.xml
    Contenere testo in giapponese per tutte le stringhe ad eccezione di title.

Se il tuo 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 su giapponese, Android cerca title nel file res/values-ja/strings.xml. Tuttavia, poiché nel file non è inclusa una stringa di questo tipo, Android torna al valore predefinito e carica title in inglese dal file res/values/strings.xml.

Quali risorse hanno 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 di elementi grafici predefinito e altri due set di elementi grafici, ciascuno ottimizzato per una configurazione del dispositivo diversa:

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

Se l'app viene eseguita su un dispositivo configurato per l'utilizzo del giapponese, Android carica la grafica da res/drawable-ja/, anche se il dispositivo è uno di quelli che prevede l'input da uno stilo e ha uno schermo QVGA a bassa densità con 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 che tu abbia la seguente situazione:

  • Il codice dell'app chiama 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 è installata 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 della lingua.

Il processo di selezione non è sempre così semplice come suggeriscono questi esempi. Per una descrizione più dettagliata della procedura, consulta In che modo Android trova la risorsa con la corrispondenza migliore. Tutti i qualificatori sono descritti ed elencati in ordine di precedenza nella panoramica delle risorse dell'app.

Fai riferimento alle risorse nel codice

Nel codice basato su Kotlin della tua app, fai riferimento alle risorse utilizzando la sintassi R.resource_type.resource_name o android.R.resource_type.resource_name. Per saperne di più, consulta Accedi alle risorse dell'app.

Gestisci le stringhe per la localizzazione

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

Sposta tutte le stringhe in strings.xml

Quando crei le tue app, non impostare stringhe come hardcoded. Dichiara invece tutte le stringhe come risorse in un file strings.xml predefinito, in modo da semplificarne l'aggiornamento e la localizzazione. Le stringhe nel file strings.xml possono essere facilmente estratte, tradotte e integrate nuovamente 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)
)

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

Segui le linee guida di Android per le stringhe della UI

Quando progetti e sviluppi le tue 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 appaiono più curate e gli utenti possono comprendere più rapidamente la tua UI.

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

Fornisci 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 consentono di ottenere una traduzione di qualità migliore. Inoltre, ti aiuta 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 di contesto come le seguenti:

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

Contrassegna le parti del messaggio che non devono essere tradotte

Spesso, le stringhe contengono testo che non deve essere tradotto in altre lingue. Esempi comuni sono una parte di codice, un segnaposto per un valore, un simbolo speciale o un nome. Mentre 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 tag di esempio 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 spieghi a cosa serve il segnaposto. Se l'app sostituisce in un secondo momento il valore segnaposto, assicurati di fornire un attributo di esempio per chiarire l'utilizzo previsto.

Ecco alcuni 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 l'articolo Traduci e localizza le app.

Suggerimenti per la localizzazione

Segui questi suggerimenti per localizzare la tua app.

Progetta la tua app in modo che funzioni in qualsiasi lingua

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

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

Se un'app non dispone anche di una sola risorsa predefinita, non viene eseguita su un dispositivo impostato su una lingua non supportata. Ad esempio, se nel file res/values/strings.xml predefinito manca una stringa necessaria all'app, quando l'app viene eseguita in un'impostazione internazionale non supportata e tenta di caricare res/values/strings.xml, l'utente visualizza un messaggio di errore e un pulsante Chiusura forzata.

Per saperne di più, consulta la sezione Test per le risorse predefinite.

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

Probabilmente non è necessario creare un'alternativa specifica per ogni risorsa della tua app. Ad esempio, un logo dell'app definito nella directory res/drawable/ potrebbe funzionare in qualsiasi lingua, nel qual caso non è necessario creare file grafici alternativi.

Inoltre, potrebbe non essere necessario creare un testo alternativo per ogni stringa. Ad esempio, supponiamo quanto segue:

  • La lingua predefinita della tua app è l'inglese americano. Ogni stringa utilizzata dall'app è definita, utilizzando l'ortografia dell'inglese americano, in res/values/strings.xml.
  • Per alcune frasi importanti, vuoi fornire l'ortografia dell'inglese britannico. Vuoi che queste stringhe alternative vengano utilizzate quando la tua 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 utilizza i valori predefiniti e ciò che è definito in res/values/strings.xml.

Utilizza LocalConfiguration per la ricerca manuale delle impostazioni internazionali

Puoi cercare le impostazioni internazionali utilizzando LocalConfiguration che Android mette a disposizione, come mostrato nell'esempio seguente:

val locale = LocalConfiguration.current.locales[0]

Utilizza il servizio di traduzione app

Il servizio di traduzione app è integrato in Play Console. Ti consente di ottenere un preventivo istantaneo ed effettuare un ordine con un'azienda 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.

Utilizza Gemini per tradurre le stringhe dell'app

Puoi utilizzare Gemini in Android Studio per tradurre le risorse stringa della tua app direttamente nel tuo progetto. Per saperne di più, consulta l'articolo Traduci e localizza le app.

Testa 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.

Esegui il test su un dispositivo

Tieni presente che il dispositivo su cui stai eseguendo i test potrebbe essere molto diverso da quelli disponibili per i consumatori in altri luoghi. Le impostazioni internazionali disponibili sul tuo dispositivo possono essere diverse 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 e drawable nella UI.

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

Esegui test con anteprime componibili

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

Esegui il test su un emulatore

Per maggiori dettagli sull'utilizzo dell'emulatore, consulta Esegui app su emulatore Android.

Crea e utilizza impostazioni internazionali personalizzate

Un'impostazione internazionale "personalizzata" è una combinazione di lingua o regione non supportata esplicitamente dall'immagine di sistema Android. Puoi testare il funzionamento della tua app in un'impostazione internazionale personalizzata creandone una nell'emulatore. Puoi farlo in due modi:

  • Utilizza l'app Custom Locale, accessibile dalla scheda delle app. Dopo aver creato una lingua personalizzata, passa a questa lingua toccando e tenendo premuto il nome della lingua.
  • Passa a un'impostazione internazionale personalizzata 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, la tua app viene localizzata correttamente.

Modifica le impostazioni internazionali dell'emulatore dalla shell adb

Per modificare le impostazioni internazionali nell'emulatore utilizzando la shell adb, segui questi passaggi:

  1. Scegli le impostazioni internazionali che vuoi testare e determina il tag della 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 questo comando:
    adb shell
    In alternativa, 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 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

L'emulatore verrà riavviato. Quando viene visualizzata di nuovo la schermata Home, riavvia l'app, che verrà avviata con le nuove impostazioni internazionali.

Test per le risorse predefinite

Per verificare se un'app include tutte le risorse stringa di cui ha bisogno, segui questi passaggi:

  1. Imposta l'emulatore o il dispositivo su una lingua non supportata dalla tua app. Ad esempio, se l'app contiene stringhe in francese in res/values-fr/, ma non contiene stringhe in spagnolo in res/values-es/, imposta le impostazioni internazionali dell'emulatore su Spagnolo. Puoi utilizzare l'app Custom Locale per impostare l'emulatore su un'impostazione internazionale non supportata.
  2. Esegui l'app.
  3. Se l'app mostra un messaggio di errore e un pulsante Chiusura forzata, 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 va a buon fine, 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 saperne di più sulla localizzazione, consulta le seguenti risorse aggiuntive:

Documentazione

Visualizza contenuti

Avanti
Test your app with pseudolocales