Lingua preferita nelle app

In molti casi, gli utenti multilingue impostano la lingua di sistema su una lingua, ad esempio l'inglese, ma vogliono selezionare altre lingue per app specifiche, come l'olandese, il cinese o l'hindi. Per aiutare le app a offrire un'esperienza migliore a questi utenti, Android 13 introduce le seguenti funzionalità per le app che supportano più lingue:

• Impostazioni di sistema: una posizione centralizzata in cui gli utenti possono selezionare una lingua preferita per ogni app.

  Puoi configurare la tua app in modo che generi automaticamente i file necessari per supportare la lingua preferita nelle app e visualizzarla nelle impostazioni di sistema. Per scoprire di più, consulta le istruzioni per attivare il supporto automatico della lingua per app.

• API aggiuntive: queste API pubbliche, come i metodi setApplicationLocales e getApplicationLocales in LocaleManager, consentono alle app di impostare una lingua diversa da quella di sistema in fase di runtime.

  Queste API si sincronizzano automaticamente con le impostazioni di sistema, pertanto le app che le utilizzano per creare selettori di lingua personalizzati in-app garantiscono ai propri utenti un'esperienza utente coerente, indipendentemente da dove selezionano le preferenze della lingua. Le API pubbliche ti aiutano anche a ridurre la quantità di codice boilerplate, supportano gli APK divisi e il backup automatico per le app per archiviare le impostazioni della lingua dell'utente a livello di app.

  Per la compatibilità con le versioni precedenti di Android, sono disponibili anche API equivalenti in AndroidX. Tuttavia, le API compatibili con le versioni precedenti funzionano con il contesto AppCompatActivity, non con il contesto dell'applicazione, per Android 12 (livello API 32) e versioni precedenti. Accedi alle API compatibili con le versioni precedenti con Appcompat 1.6.0 o versioni successive.

Panoramica dell'implementazione di questa funzionalità

La tabella seguente mostra le implementazioni consigliate in base a diversi casi d'uso.

Impostazioni di sistema per gli utenti

A partire da Android 13, Android include una posizione centralizzata nelle impostazioni di sistema per impostare le preferenze della lingua nelle app. Per assicurarti che le lingue della tua app siano configurabili nelle impostazioni di sistema sui dispositivi con Android 13 o versioni successive, attiva il supporto automatico della lingua per app (opzione consigliata) o configura il supporto manualmente.

Attivare il supporto automatico della lingua per app

Questo è il modo consigliato per aggiungere il supporto della lingua per app alle tue app, perché non richiede modifiche XML.

A partire da Android Studio Giraffe e AGP 8.1, puoi configurare la tua app per supportare automaticamente le lingue preferite nelle app. In base alle risorse del progetto, AGP genera il file LocaleConfig e aggiunge un riferimento nel file manifest finale, quindi non devi più farlo manualmente. AGP utilizza le risorse nelle cartelle res dei moduli dell'app e le dipendenze dei moduli della libreria per determinare le impostazioni internazionali da includere nel file LocaleConfig. Ciò significa che se aggiungi risorse per una nuova lingua alla tua app, non devi preoccuparti di aggiornare il file LocaleConfig.

Tieni presente che la funzionalità di lingua automatica per app supporta le app che eseguono Android 13 (livello API 33) o versioni successive. Per utilizzare la funzionalità, devi impostare compileSdkVersion su 33 o un valore superiore. Per configurare la lingua preferita nelle app per le versioni precedenti di Android, devi comunque utilizzare le API e i selettori della lingua in-app.

Per attivare il supporto automatico della lingua per app:

1. Per attivare la funzionalità, utilizza l'impostazione generateLocaleConfig nel blocco androidResources {} del file build.gradle.kts a livello di modulo (file build.gradle se utilizzi Groovy). La funzionalità è disattivata per impostazione predefinita

    android {
      androidResources {
        generateLocaleConfig = true
      }
    }

  android {
    androidResources {
      generateLocaleConfig true
    }
  }

1. Specifica un locale predefinito:
   1. Nella cartella res del modulo dell'app, crea un nuovo file denominato resources.properties.
   2. Nel file resources.properties, imposta le impostazioni internazionali predefinite con l'etichetta unqualifiedResLocale. Per formattare i nomi delle impostazioni locali, consulta Come formare i nomi delle impostazioni locali.

AGP aggiunge questa impostazione internazionale predefinita e le eventuali impostazioni internazionali alternative che hai specificato, utilizzando le directory values-* nella cartella res, al file LocaleConfig generato automaticamente.

Come formare i nomi delle impostazioni internazionali

Per formare i nomi delle impostazioni internazionali, combina il codice lingua con i codici facoltativi di script e regione, separando ciascuno con un trattino:

• Lingua: utilizza il codice ISO 639-2 di due o tre lettere.
• Script (facoltativo): utilizza il codice ISO 15924.
• Regione (facoltativo): utilizza il codice ISO 3166-1 alpha-2 di due lettere o il codice UN_M.49 di tre cifre.

Ad esempio, se la lingua predefinita è l'inglese americano:

unqualifiedResLocale=en-US

Utilizzare android:localeConfig per aggiungere lingue supportate alle impostazioni di sistema

Puoi configurare manualmente la tua app per assicurarti che le lingue siano configurabili nelle impostazioni di sistema sui dispositivi con Android 13 o versioni successive. Per farlo, crea un file XML locale_config e aggiungilo al manifest dell'app utilizzando l'attributo android:localeConfig. L'omissione della voce del manifest android:localeConfig indica che gli utenti non devono essere in grado di impostare la lingua dell'app indipendentemente dalla lingua di sistema nelle impostazioni di sistema.

Per aggiungere manualmente le lingue supportate dalla tua app alle impostazioni di sistema di un utente:

1. Crea un file denominato res/xml/locale_config.xml e specifica le lingue della tua app, inclusa l'impostazione internazionale di riserva definitiva, ovvero l'impostazione internazionale specificata in res/values/strings.xml.

   Consulta Come formare i nomi delle località per i requisiti di formato. Consulta anche il file locale_config.xml di esempio per un elenco delle impostazioni locali più utilizzate.

   Ad esempio, formatta il file locale_config.xml in questo modo per un'app che supporta le seguenti lingue:

   • Inglese (Stati Uniti) come impostazioni internazionali di riserva
   • Inglese (Regno Unito)
   • Francese
   • Giapponese
   • Cinese (semplificato, Macao)
   • Cinese (tradizionale, Macao)

   <?xml version="1.0" encoding="utf-8"?>
   <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
      <locale android:name="en-US"/>
      <locale android:name="en-GB"/>
      <locale android:name="fr"/>
      <locale android:name="ja"/>
      <locale android:name="zh-Hans-MO"/>
      <locale android:name="zh-Hant-MO"/>
   </locale-config>
   

2. Nel manifest, aggiungi una riga che rimandi a questo nuovo file:

   <manifest>
       ...
       <application
           ...
           android:localeConfig="@xml/locale_config">
       </application>
   </manifest>
   

Puoi aggiornare dinamicamente localeConfig della tua app con LocaleManager.setOverrideLocaleConfig per personalizzare l'insieme di lingue visualizzate nell'elenco delle lingue per app nelle impostazioni di Android. In questo modo puoi personalizzare l'elenco delle lingue per regione, eseguire esperimenti A/B e fornire impostazioni locali aggiornate se la tua app utilizza push di localizzazione lato server, come mostrato nell'esempio seguente:

//For setOverrideLocaleConfig
val localeManager = applicationContext
    .getSystemService(LocaleManager::class.java)
localeManager.overrideLocaleConfig = LocaleConfig(
LocaleList.forLanguageTags("en-US,ja-JP,zh-Hans-SG")
)

//For getOverrideLocaleConfig
// The app calls the API to get the override LocaleConfig
val overrideLocaleConfig = localeManager.overrideLocaleConfig
// If the returned overrideLocaleConfig isn't equal to NULL, then the app calls the API to get the supported Locales
val supportedLocales = overrideLocaleConfig.supportedLocales()

Inoltre, gli IME ora possono utilizzare LocaleManager.getApplicationLocales per conoscere la lingua della UI dell'app corrente per aggiornare la lingua della tastiera come mostrato di seguito:

val currentAppLocales: LocaleList = applicationContext.getSystemService(LocaleManager::class.java).getApplicationLocales(appPackageName)

Specificare le lingue supportate in Gradle

Se non sono già presenti, specifica le stesse lingue utilizzando la proprietà resourceConfigurations nel file build.gradle a livello di modulo dell'app:

android {
  ...
  defaultConfig {
    resourceConfigurations += ["en", "en-rGB", "fr", "ja", "b+zh+Hans+MO", "b+zh+Hant+MO"]
  }
}

Quando è presente la proprietà resourceConfigurations, il sistema di compilazione include solo le risorse di lingua nell'APK per le lingue specificate, impedendo l'inclusione di stringhe tradotte da altre librerie che potrebbero supportare lingue non supportate dalla tua app. Per maggiori informazioni, vedi Specificare le lingue supportate dall'app.

Come gli utenti selezionano la lingua di un'app nelle impostazioni di sistema

Gli utenti possono selezionare la lingua preferita per ogni app tramite le impostazioni di sistema. Possono accedere a queste impostazioni in due modi diversi:

• Accesso tramite le impostazioni Sistema

  Impostazioni > Sistema > Lingue e immissione > Lingue delle app > (seleziona un'app)

• Accedere tramite le impostazioni delle app

  Impostazioni > App > (seleziona un'app) > Lingua

Gestire i selettori lingua in-app

Per le app che hanno già un selettore lingua in-app o che vogliono utilizzarne uno, usa le API pubbliche anziché la logica personalizzata dell'app per gestire l'impostazione e il recupero della lingua preferita di un utente per la tua app. Se utilizzi le API pubbliche per il selettore lingua in-app, le impostazioni di sistema del dispositivo vengono aggiornate automaticamente in modo che corrispondano alla lingua selezionata dall'utente tramite l'esperienza in-app.

Implementare utilizzando Jetpack Compose

Per le app create interamente con Jetpack Compose, il sistema gestisce automaticamente gli aggiornamenti dell'interfaccia utente quando cambia la lingua dell'app. La chiamata all'API per impostare una nuova lingua attiva una modifica della configurazione. Compose reagisce ricomponendo la tua UI e risolvendo automaticamente le chiamate stringResource utilizzando le nuove impostazioni internazionali.

Per la compatibilità con le versioni precedenti di Android 12 (livello API 32) e precedenti, consigliamo vivamente di utilizzare la libreria di supporto AndroidX (AppCompatDelegate) quando implementi un selettore lingua in-app. Se utilizzi questo approccio, l'attività che ospita la tua UI Compose deve estendere AppCompatActivity. Tuttavia, se necessario, puoi anche implementare direttamente le API del framework.

Il seguente snippet di codice mostra un esempio di come leggere le impostazioni internazionali correnti dell'app e impostarne di nuove all'interno di una funzione componibile:

import androidx.appcompat.app.AppCompatDelegate
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.core.os.LocaleListCompat

@Composable
fun LanguageSelector() {
    // Retrieve the currently configured app locale.
    // If no app-specific locale is set, LocaleListCompat.get(0) returns null,
    // so we safely fall back to a default (e.g., "en").
    val appLocales = AppCompatDelegate.getApplicationLocales()
    val currentLocaleTag = appLocales.get(0)?.toLanguageTag() ?: "en"

    // Example UI: A button to toggle between English and Spanish
    Button(
        onClick = {
            val newLanguageTag = if (currentLocaleTag == "en") "es" else "en"
            val localeList = LocaleListCompat.forLanguageTags(newLanguageTag)

            // Setting the locale re-creates the Activity by default,
            // which automatically applies the new configuration to Compose.
            AppCompatDelegate.setApplicationLocales(localeList)
        }
    ) {
        Text(
            text = if (currentLocaleTag == "en") "Switch to Spanish" else "Switch to English"
        )
    }
}

Per impostare la lingua preferita di un utente, chiedigli di selezionare le impostazioni internazionali nel selettore lingua, quindi imposta questo valore nel sistema:

val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY")
// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale)

Tieni presente che la chiamata a setApplicationLocales ricrea Activity, a meno che la tua app gestisca autonomamente le modifiche alla configurazione delle impostazioni internazionali.

Utilizza AppCompatDelegate.getApplicationLocales per recuperare le impostazioni internazionali preferite dell'utente. L'utente potrebbe aver selezionato le impostazioni internazionali dell'app dalle impostazioni di sistema o dal selettore lingua in-app.

Supporto di Android 12 e versioni precedenti

Per supportare i dispositivi con Android 12 (livello API 32) e versioni precedenti, indica a AndroidX di gestire l'archiviazione delle impostazioni internazionali impostando un valore autoStoreLocales su true e android:enabled su false nella voce del manifest per il servizio AppLocalesMetadataHolderService della tua app, come mostrato nel seguente snippet di codice:

<application
  ...
  <service
    android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
    android:enabled="false"
    android:exported="false">
    <meta-data
      android:name="autoStoreLocales"
      android:value="true" />
  </service>
  ...
</application>

Tieni presente che l'impostazione di un valore autoStoreLocales su true causa una lettura con blocco sul thread principale e potrebbe causare una violazione di StrictMode diskRead e diskWrite se registri le violazioni dei thread. Per saperne di più, consulta AppCompatDelegate.setApplicationLocales.

Gestione personalizzata dello spazio di archiviazione

L'omissione della voce del manifest o l'impostazione di autoStoreLocales su false indica che gestisci il tuo spazio di archiviazione. In questo caso, devi fornire le impostazioni internazionali memorizzate prima di onCreate nel ciclo di vita dell'attività e controllare le chiamate a AppCompatDelegate.setApplicationLocales in Android 12 (livello API 32) o versioni precedenti.

Se la tua app ha una posizione di archiviazione delle impostazioni internazionali personalizzata, ti consigliamo di utilizzare un trasferimento una tantum tra la tua soluzione di archiviazione delle impostazioni internazionali personalizzata e autoStoreLocales in modo che gli utenti continuino a utilizzare la tua app nella lingua che preferiscono. Ciò è particolarmente applicabile nei casi in cui l'app viene eseguita per la prima volta dopo l'upgrade del dispositivo ad Android 13. In questo caso, puoi fornire le impostazioni internazionali preesistenti richieste dall'utente recuperandole dallo spazio di archiviazione personalizzato e passandole a AppCompatDelegate.setApplicationLocales.

Implementa utilizzando le API del framework Android

Sebbene ti consigliamo vivamente di utilizzare la libreria di supporto AndroidX per implementare i selettori di lingua in-app, puoi anche utilizzare i metodi setApplicationLocales e getApplicationLocales nel framework Android per i dispositivi con Android 13.

Il seguente snippet di codice mostra come impostare e ottenere la lingua preferita dell'utente utilizzando il servizio di sistema LocaleManager:

import android.app.LocaleManager
import android.content.Context
import android.os.Build
import android.os.LocaleList
import androidx.annotation.RequiresApi
import java.util.Locale

@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun setAppLanguage(context: Context, languageTag: String) {
    // 1. Retrieve the system service
    val localeManager = context.getSystemService(LocaleManager::class.java)

    // 2. Create a LocaleList from the language tag (e.g., "es-ES" or "ja")
    val localeList = LocaleList(Locale.forLanguageTag(languageTag))

    // 3. Set the locale. The system automatically updates the locale and
    // restarts the app, including any necessary configuration updates.
    localeManager.applicationLocales = localeList
}

@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun getAppLanguage(context: Context): String {
    val localeManager = context.getSystemService(LocaleManager::class.java)
    val currentLocales = localeManager.applicationLocales

    // Return the primary app locale, or fall back to the system default
    return if (!currentLocales.isEmpty) {
        currentLocales.get(0).toLanguageTag()
    } else {
        Locale.getDefault().toLanguageTag()
    }
}

Best practice aggiuntive

Tieni presente le seguenti best practice.

Considerare la lingua quando richiami un intent in un'altra app

Gli intent incentrati sulla lingua potrebbero consentirti di specificare la lingua in cui vuoi che sia l'app richiamata. Un esempio è la funzionalità EXTRA_LANGUAGE dell'API Speech Recognizer.

Considera l'intestazione Accept-Language per la scheda personalizzata di Chrome

Valuta la possibilità di aggiungere l'intestazione Accept-Language tramite Browser.EXTRA_HEADERS per aprire una pagina web nella lingua della tua app quando richiami una scheda personalizzata di Chrome.

Se rimuovi le lingua preferita nelle app nelle impostazioni di sistema, reimposta le impostazioni internazionali dell'app su quelle di sistema

Se rimuovi le preferenze della lingua della tua app dalle impostazioni di sistema (rimuovendo android:localeConfig da AndroidManifest.xml della tua app), gli utenti non possono reimpostare facilmente la lingua dell'app sul valore predefinito del sistema.

Per questo motivo, se rimuovi android:localeConfig, valuta la possibilità di reimpostare le impostazioni internazionali dell'app su quelle di sistema utilizzando LocaleListCompat.getEmptyLocaleList o LocaleList.getEmptyLocaleList, come mostrato nel seguente snippet di codice:

// Use the AndroidX APIs to reset to the system locale for backward and forward compatibility
AppCompatDelegate.setApplicationLocales(
  LocaleListCompat.getEmptyLocaleList()
)

// Or use the Framework APIs for Android 13 and above to reset to the system locale
val context = LocalContext.current
context.getSystemService(LocaleManager::class.java)
  .applicationLocales = LocaleList.getEmptyLocaleList()

File locale_config.xml di esempio

Per impostazione predefinita, Android include traduzioni a livello di sistema in Android Open Source Project (AOSP) per un insieme standard di impostazioni internazionali più utilizzate. Il file locale_config.xml di esempio incluso in questa sezione mostra il formato suggerito per ciascuna di queste impostazioni internazionali. Fai riferimento a questo file di esempio per creare il tuo file locale_config.xml per il set di lingue supportate dalla tua app.

<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
   <locale android:name="af"/> <!-- Afrikaans -->
   <locale android:name="am"/> <!-- Amharic -->
   <locale android:name="ar"/> <!-- Arabic -->
   <locale android:name="as"/> <!-- Assamese -->
   <locale android:name="az"/> <!-- Azerbaijani -->
   <locale android:name="be"/> <!-- Belarusian -->
   <locale android:name="bg"/> <!-- Bulgarian -->
   <locale android:name="bn"/> <!-- Bengali -->
   <locale android:name="bs"/> <!-- Bosnian -->
   <locale android:name="ca"/> <!-- Catalan -->
   <locale android:name="cs"/> <!-- Czech -->
   <locale android:name="da"/> <!-- Danish -->
   <locale android:name="de"/> <!-- German -->
   <locale android:name="el"/> <!-- Greek -->
   <locale android:name="en-AU"/> <!-- English (Australia) -->
   <locale android:name="en-CA"/> <!-- English (Canada) -->
   <locale android:name="en-GB"/> <!-- English (United Kingdom) -->
   <locale android:name="en-IN"/> <!-- English (India) -->
   <locale android:name="en-US"/> <!-- English (United States) -->
   <locale android:name="es"/> <!-- Spanish (Spain) -->
   <locale android:name="es-US"/> <!-- Spanish (United States) -->
   <locale android:name="et"/> <!-- Estonian -->
   <locale android:name="eu"/> <!-- Basque -->
   <locale android:name="fa"/> <!-- Farsi -->
   <locale android:name="fi"/> <!-- Finnish -->
   <locale android:name="fil"/> <!-- Filipino -->
   <locale android:name="fr"/> <!-- French (France) -->
   <locale android:name="fr-CA"/> <!-- French (Canada) -->
   <locale android:name="gl"/> <!-- Galician -->
   <locale android:name="gu"/> <!-- Gujarati -->
   <locale android:name="hi"/> <!-- Hindi -->
   <locale android:name="hr"/> <!-- Croatian -->
   <locale android:name="hu"/> <!-- Hungarian -->
   <locale android:name="hy"/> <!-- Armenian -->
   <locale android:name="in"/> <!-- Indonesian -->
   <locale android:name="is"/> <!-- Icelandic -->
   <locale android:name="it"/> <!-- Italian -->
   <locale android:name="iw"/> <!-- Hebrew -->
   <locale android:name="ja"/> <!-- Japanese -->
   <locale android:name="ka"/> <!-- Georgian -->
   <locale android:name="kk"/> <!-- Kazakh -->
   <locale android:name="km"/> <!-- Khmer -->
   <locale android:name="kn"/> <!-- Kannada -->
   <locale android:name="ko"/> <!-- Korean -->
   <locale android:name="ky"/> <!-- Kyrgyz -->
   <locale android:name="lo"/> <!-- Lao -->
   <locale android:name="lt"/> <!-- Lithuanian -->
   <locale android:name="lv"/> <!-- Latvian -->
   <locale android:name="mk"/> <!-- Macedonian -->
   <locale android:name="ml"/> <!-- Malayalam -->
   <locale android:name="mn"/> <!-- Mongolian -->
   <locale android:name="mr"/> <!-- Marathi -->
   <locale android:name="ms"/> <!-- Malay -->
   <locale android:name="my"/> <!-- Burmese -->
   <locale android:name="nb"/> <!-- Norwegian -->
   <locale android:name="ne"/> <!-- Nepali -->
   <locale android:name="nl"/> <!-- Dutch -->
   <locale android:name="or"/> <!-- Odia -->
   <locale android:name="pa"/> <!-- Punjabi -->
   <locale android:name="pl"/> <!-- Polish -->
   <locale android:name="pt-BR"/> <!-- Portuguese (Brazil) -->
   <locale android:name="pt-PT"/> <!-- Portuguese (Portugal) -->
   <locale android:name="ro"/> <!-- Romanian -->
   <locale android:name="ru"/> <!-- Russian -->
   <locale android:name="si"/> <!-- Sinhala -->
   <locale android:name="sk"/> <!-- Slovak -->
   <locale android:name="sl"/> <!-- Slovenian -->
   <locale android:name="sq"/> <!-- Albanian -->
   <locale android:name="sr"/> <!-- Serbian (Cyrillic) -->
   <locale android:name="sr-Latn"/> <!-- Serbian (Latin) -->
   <locale android:name="sv"/> <!-- Swedish -->
   <locale android:name="sw"/> <!-- Swahili -->
   <locale android:name="ta"/> <!-- Tamil -->
   <locale android:name="te"/> <!-- Telugu -->
   <locale android:name="th"/> <!-- Thai -->
   <locale android:name="tr"/> <!-- Turkish -->
   <locale android:name="uk"/> <!-- Ukrainian -->
   <locale android:name="ur"/> <!-- Urdu -->
   <locale android:name="uz"/> <!-- Uzbek -->
   <locale android:name="vi"/> <!-- Vietnamese -->
   <locale android:name="zh-Hans"/> <!-- Chinese (Simplified) -->
   <locale android:name="zh-Hant"/> <!-- Chinese (Traditional) -->
   <locale android:name="zu"/> <!-- Zulu -->
</locale-config>

Risorse aggiuntive

Per ulteriori informazioni, consulta i nostri esempi di codice, gli articoli del blog e i video.

• Lingua preferita nelle app, parte 1 blog
• Lingua preferita nelle app, parte 2
• Video Building for a multilingual world
• Risorse in Compose