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 modo appropriato per le impostazioni internazionali in cui viene utilizzata.

In questa pagina vengono descritte le best practice per la localizzazione delle app Android.

Devi avere una conoscenza pratica di Kotlin o del linguaggio di programmazione Java e avere familiarità con il caricamento delle risorse Android, la dichiarazione degli elementi dell'interfaccia utente in XML, considerazioni di sviluppo come il ciclo di vita delle attività e i principi generali di internazionalizzazione e localizzazione.

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

  • Inserisci la maggior parte o la totalità dei contenuti dell'interfaccia utente della tua app in file di risorse, come descritto in questa pagina e nella panoramica delle risorse per l'app.
  • Il comportamento dell'interfaccia utente, invece, è determinato dal codice basato su Kotlin o Java. Ad esempio, se gli utenti inseriscono dati che devono essere formattati o ordinati in modo diverso a seconda delle impostazioni internazionali, puoi utilizzare Kotlin o il linguaggio di programmazione Java per gestire i dati in modo programmatico. Questa pagina non spiega come localizzare il codice basato su Kotlin o Java.

Per una breve guida alla localizzazione di stringhe nell'app, vedi Supportare lingue e culture diverse.

Panoramica: cambio delle risorse in Android

Le risorse sono stringhe di testo, layout, suoni, grafici e qualsiasi altro dato statico necessario per la tua app per Android. Un'app può includere più insiemi di risorse, ognuna personalizzata per una configurazione diversa del dispositivo. Quando un utente esegue l'app, Android seleziona e carica automaticamente le risorse più adatte al dispositivo.

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

Quando scrivi la tua app, crei risorse predefinite e alternative da usare. 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, posiziona 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 qualsiasi lingua per cui non hai fornito un testo specifico per le impostazioni internazionali, Android carica le stringhe predefinite da res/values/strings.xml. Se questo file predefinito è assente o manca una stringa necessaria all'app, l'app non viene eseguita e viene visualizzato un errore. L'esempio seguente illustra cosa può succedere quando il file di testo predefinito è incompleto.

Esempio:

Il codice basato su Kotlin o Java di un'app si riferisce 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 di text_a, ma non di text_b.

  • Quando l'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 l'app viene avviata su un dispositivo impostato su una lingua diversa dall'inglese, l'utente vede un messaggio di errore e un pulsante di chiusura forzata. L'app non si carica.

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, ad esempio layout, disegnabili o animazioni. Per informazioni sui test, consulta la sezione Test per risorse predefinite.

Utilizza le risorse per la localizzazione

Questa sezione illustra come creare risorse predefinite e risorse alternative. Spiega inoltre come viene assegnata la precedenza delle risorse e come fai 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 dovrebbe parlare la maggior parte degli utenti della tua app.

Il set di risorse predefinito include anche eventuali disegni e layout predefiniti e può includere altri tipi di risorse, ad esempio le animazioni. Queste risorse vengono inserite nelle seguenti directory:

  • res/drawable/: directory richiesta che contiene almeno un file grafico per l'icona dell'app su Google Play
  • res/layout/: directory richiesta contenente un file XML che definisce il layout predefinito
  • res/anim/: obbligatorio se sono presenti res/anim-<qualifiers> cartelle
  • res/xml/: obbligatorio se sono presenti res/xml-<qualifiers> cartelle
  • res/raw/: obbligatorio se sono presenti res/raw-<qualifiers> cartelle

Suggerimento: nel codice, esamina ogni riferimento a una risorsa Android. Assicurati di definire una risorsa predefinita per ciascun tipo. Assicurati inoltre che il file di stringa predefinito sia completo: un file di stringa localizzato può contenere un sottoinsieme di stringhe, ma il file di stringa default deve contenerle tutte.

Creare risorse alternative

Gran parte della localizzazione di un'app consiste nel fornire testo alternativo per diverse lingue. In alcuni casi, puoi anche fornire grafica, suoni, layout alternativi 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'impostazione internazionale diversa, utilizza un qualificatore che specifica una combinazione di lingua o lingua-regione. Il nome di una directory delle risorse deve essere conforme allo schema di denominazione descritto nella sezione Fornire risorse alternative, altrimenti la tua app non potrà 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 in giapponese, tranne il titolo. In questo caso, creerai tre file strings.xml, ciascuno archiviato in una directory di risorse specifica delle 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
    Contengono testo in francese per tutte le stringhe, tra cui title.
  3. res/values-ja/strings.xml
    Contengono testo giapponese per tutte le stringhe tranne title.

Se il tuo codice basato su Kotlin o Java 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 sulla lingua francese, Android carica title dal file res/values-fr/strings.xml.

Se il dispositivo è impostato sulla modalità giapponese, Android cerca title nel file res/values-ja/strings.xml. Tuttavia, poiché questa stringa non è inclusa nel file, Android torna al valore predefinito e carica l'elemento 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 della directory di una risorsa, le impostazioni internazionali hanno quasi sempre la precedenza.

Esempio:

Supponiamo che un'app includa un insieme predefinito di elementi grafici e altri due insiemi di immagini, ciascuno ottimizzato per una configurazione del dispositivo diversa:

  • res/drawable/
    Contiene immagini predefinite.
  • res/drawable-small-land-stylus/
    Contiene grafica ottimizzata per l'utilizzo con un dispositivo che richiede input da uno stilo e dispone di uno schermo QVGA a bassa densità con orientamento orizzontale.
  • res/drawable-ja/
    Contiene immagini ottimizzate 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 richiede l'input di uno stilo e presenta uno schermo QVGA a bassa densità con orientamento orizzontale.

Eccezione: nel processo di selezione, gli unici qualificatori che hanno la precedenza sulle impostazioni internazionali sono il codice paese mobile (Centro clienti) e il codice della rete mobile (MNC).

Esempio:

Supponiamo che la tua situazione sia la seguente:

  • 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 è in esecuzione su un dispositivo con la seguente configurazione:
    • La scheda SIM sia collegata a una rete mobile in India (Centro clienti 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 del Centro clienti rispetto a una corrispondenza di lingua.

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

Consulta le risorse nel codice

Nel codice basato su Kotlin o Java della tua app, fai riferimento alle risorse utilizzando la sintassi R.resource_type.resource_name o android.R.resource_type.resource_name. Per maggiori informazioni, consulta Accedere 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 nel file shortcuts.xml

Durante la creazione delle app, non impostare stringhe come hardcoded. Dichiara invece tutte le stringhe come risorse in un file strings.xml predefinito, così è più semplice aggiornarle e localizzarle. Le stringhe nel file strings.xml possono essere facilmente estratte, tradotte e integrate nella tua app, con qualificatori appropriati, senza alcuna modifica al codice compilato.

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 UI

Durante la progettazione e lo sviluppo delle UI, presta molta attenzione a come parli con l'utente. In generale, usa uno stile conciso che sia semplice ma conciso e coerente in tutte le interfacce utente.

Assicurati di leggere e seguire i suggerimenti di Material Design per lo stile di scrittura e la scelta delle parole. In questo modo, le app appariranno più eleganti e utili per gli utenti, che potranno comprendere più rapidamente la tua UI.

Inoltre, se possibile, usa sempre la terminologia standard di Android, ad esempio per elementi UI come barra delle app, menu opzioni, barra di sistema e notifiche. L'utilizzo corretto e coerente dei termini di Android semplifica la traduzione e migliora il prodotto finale 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 inestimabili per il traduttore e consentono di migliorare la qualità della traduzione. Ti aiuta anche a gestire le corde 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 presentato all'utente?
  • In quale punto del layout si trova? Ad esempio, le traduzioni sono meno flessibili nei pulsanti che nelle 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 porzione 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 così com'è, senza traduzione, in modo che il traduttore non lo cambi.

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 rompere 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 lo scopo del segnaposto. Se in un secondo momento la tua app sostituirà il valore segnaposto, assicurati di fornire un attributo di esempio per chiarire l'utilizzo previsto.

Di seguito sono riportati 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 della procedura di localizzazione e distribuzione di un'app Android, consulta l'articolo Tradurre e localizzare le app.

Suggerimenti per la localizzazione

Segui questi suggerimenti durante la localizzazione della tua app.

Progetta la tua app in modo che funzioni in qualsiasi località

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

Importante: assicurati che la tua app includa un insieme 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 necessari alla tua app.

Se per un'app manca anche una risorsa predefinita, non viene eseguita su un dispositivo impostato su una lingua non supportata. Ad esempio, se nel file predefinito res/values/strings.xml 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 vede un messaggio di errore e un pulsante di chiusura forzata.

Per ulteriori informazioni, consulta la sezione Test per risorse predefinite.

Progetta un layout flessibile

Se devi riorganizzare il layout per adattarlo a una determinata lingua, puoi crearne uno alternativo per quella lingua, ad esempio res/layout-de/main.xml per un layout in tedesco. Tuttavia, questo può rendere la tua app più difficile da gestire. È meglio creare un unico layout più flessibile.

Un'altra situazione tipica è una lingua che richiede qualcosa di diverso nel suo layout. Ad esempio, potresti avere un modulo di contatto che include due campi nome quando l'app viene eseguita in giapponese e tre campi nome quando l'app viene eseguita in un'altra lingua. Puoi gestire questa situazione in due modi:

  • Crea un unico layout con un campo che puoi attivare o disattivare in modo programmatico in base alla lingua.
  • Fai in modo che il layout principale includa un altro layout che includa il campo modificabile. Il secondo layout può avere configurazioni diverse per lingue diverse.

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

Probabilmente non è necessario creare un'alternativa specifica per ogni risorsa nella tua app. Ad esempio, il layout definito nel file res/layout/main.xml potrebbe funzionare in tutte le impostazioni internazionali, nel qual caso non è necessario creare file di layout alternativi.

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

  • La lingua predefinita dell'app è l'inglese americano. Ogni stringa utilizzata dall'app viene definita in res/values/strings.xml utilizzando l'ortografia dell'inglese americano.
  • Per alcune frasi importanti, è necessario specificare 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 che sono diverse quando l'app viene eseguita nel Regno Unito. Per tutte le altre stringhe, l'app torna ai valori predefiniti e utilizza ciò che è definito in res/values/strings.xml.

Utilizzare l'oggetto Android Context per la ricerca manuale delle impostazioni internazionali

Puoi cercare le impostazioni internazionali utilizzando l'oggetto Context reso disponibile da Android, come mostrato nell'esempio seguente:

Kotlin

val primaryLocale: Locale = context.resources.configuration.locales[0]
val locale: String = primaryLocale.displayName

Java

Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
String locale = primaryLocale.getDisplayName();

Utilizzare il servizio di traduzione delle app

Il Servizio di traduzione app è integrato in Play Console. Ti consente di ricevere un preventivo istantaneo ed effettuare un ordine con una società di traduzione. Puoi ordinare le traduzioni in una o più lingue per le stringhe dell'interfaccia utente delle app, il testo delle schede del Play Store, i nomi degli IAP e il testo della campagna pubblicitaria.

Testare le app localizzate

Testa la tua app localizzata su un dispositivo o utilizzando l'emulatore di 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 il test potrebbe essere notevolmente diverso dai dispositivi disponibili per i consumatori in altri paesi. Le impostazioni internazionali disponibili sul dispositivo possono essere diverse da quelle disponibili su altri dispositivi. Inoltre, la risoluzione e la densità dello schermo del dispositivo potrebbero variare, il che può influire sulla visualizzazione di stringhe e disegnabili nella UI.

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

Testa su un emulatore

Per maggiori dettagli sull'utilizzo dell'emulatore, vedi Eseguire app sull'emulatore Android.

Creare e utilizzare impostazioni internazionali personalizzate

Le impostazioni internazionali "personalizzate" sono una combinazione di lingua o regione non supportata esplicitamente dall'immagine del sistema Android. Puoi testare l'esecuzione dell'app in una lingua personalizzata creando un'impostazione internazionale personalizzata nell'emulatore. Puoi farlo in due modi:

  • Usare l'app Impostazioni internazionali personalizzate, accessibile dalla scheda App. Dopo aver creato un'impostazione internazionale personalizzata, passa all'impostazione toccando e tenendo premuto il nome dell'impostazione internazionale.
  • Passa a un'impostazione internazionale personalizzata dalla shell adb, come descritto nella sezione seguente.

Quando imposti l'emulatore su un'impostazione internazionale non disponibile nell'immagine del sistema Android, il sistema viene visualizzato nella lingua predefinita. La tua app, tuttavia, si localizza correttamente.

Modifica delle 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 tag lingua BCP-47, ad esempio fr-CA per il francese canadese.
  2. Avvia un emulatore.
  3. Dalla shell della riga di comando sul computer host, esegui questo comando:
    adb shell
    oppure, se hai un dispositivo collegato, specifica che vuoi utilizzare 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 un test in francese canadese:
    setprop persist.sys.locale fr-CA;stop;sleep 5;start

Questa operazione determina il riavvio dell'emulatore. Quando viene visualizzata di nuovo la schermata Home, riavvia l'app e l'app verrà avviata con le nuove impostazioni internazionali.

Test per risorse predefinite

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

  1. Imposta l'emulatore o il dispositivo su una lingua non supportata dalla tua app. Ad esempio, se l'app ha stringhe in francese in res/values-fr/ ma non in 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 una lingua non supportata.
  2. Esegui l'app.
  3. Se l'app mostra un messaggio di errore e un pulsante di chiusura forzata, potrebbe cercare 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 layout denominato res/layout-land/main.xml, ma non contiene un file denominato res/layout-port/main.xml, imposta l'emulatore o il dispositivo sull'orientamento verticale e controlla se l'app viene eseguita.