Lingua preferita nelle app

In molti casi, gli utenti multilingue impostano la lingua del sistema su una sola lingua, ad esempio come l'inglese, ma vuole selezionare altre lingue per app specifiche, ad esempio Olandese, cinese o hindi. Per aiutare le app a offrire un'esperienza migliore per questi agli 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 l'app in modo che generi automaticamente i file necessari supportano le preferenze relative alla lingua per app e vengono visualizzate nelle impostazioni di sistema. A scopri di più, consulta le istruzioni per abilitare il supporto automatico delle lingue per app.

• API aggiuntive: si tratta di API pubbliche, come setApplicationLocales(): e getApplicationLocales() in LocaleManager, consenti alle app impostare una lingua diversa dalla lingua di sistema in fase di runtime.

  Queste API si sincronizzano automaticamente con le impostazioni di sistema; pertanto le app che usano queste API per creare selettori di lingua in-app personalizzati garantiranno che i loro utenti devono avere un'esperienza utente coerente, indipendentemente da dove selezionano il proprio preferenze linguistiche. Le API pubbliche ti aiutano anche a ridurre la quantità il codice boilerplate, gli APK divisi e il Backup automatico per App per memorizzare la lingua dell'utente a livello di app. impostazioni.

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

Panoramica dell'implementazione di questa funzionalità

La seguente tabella mostra le implementazioni consigliate in base al diverso utilizzo d'uso diversi.

Impostazioni di sistema per gli utenti

A partire da Android 13, Android include una posizione centralizzata nel sistema impostazioni per impostare le preferenze di lingua per app. Per assicurarti che la tua app le lingue sono configurabili nelle impostazioni di sistema sui dispositivi con Android 13 o superiore, attiva il supporto automatico delle lingue per app (consigliato) o configura manualmente.

Attiva il supporto automatico delle lingue per app

A partire da Android Studio Giraffe e AGP 8.1, puoi configurare Supporto lingua per app preferenze automaticamente. In base alle risorse del tuo progetto, AGP genera il LocaleConfig e vi aggiunge un riferimento nel file manifest finale, in modo che manualmente. AGP utilizza le risorse presenti nelle cartelle res della tua app moduli ed eventuali dipendenze del modulo della libreria per determinare le impostazioni internazionali da includere nel file LocaleConfig. Ciò significa che se aggiungi risorse per un nuovo lingua dell'app, non devi preoccuparti di aggiornare LocaleConfig .

Tieni presente che la funzionalità di lingua per app supporta le app che eseguono Android 13 (livello API 33) o superiore. Per utilizzare la funzionalità, devi impostare Da compileSdkVersion a 33 o superiore. Per configurare le preferenze relative alla lingua per app le versioni precedenti di Android, devi comunque utilizza le API e i selettori lingua in-app.

Per attivare il supporto automatico delle lingue per app, procedi nel seguente modo:

1. Per attivare la funzionalità, usa generateLocaleConfig nel blocco androidResources {} della sezione a livello di modulo build.gradle.kts file (build.gradle file se utilizzando Groovy). Per impostazione predefinita, la funzionalità è disattivata.

   Kotlin

       android {
         androidResources {
           generateLocaleConfig = true
         }
       }
       

   Alla moda

       android {
         androidResources {
           generateLocaleConfig true
         }
       }
       

2. Specifica le impostazioni internazionali predefinite:
   1. Nella cartella res del modulo dell'app, crea un nuovo file denominato resources.properties.

   2. Nel file resources.properties, imposta il valore predefinito le impostazioni internazionali con l'etichetta unqualifiedResLocale. Per formattare il i nomi delle impostazioni internazionali, consulta la sezione Come creare i nomi delle impostazioni internazionali.

AGP aggiunge queste impostazioni internazionali predefinite e località alternative specificato, utilizzando values-* directory nella cartella res, generato automaticamente da LocaleConfig.

Come definire i nomi delle impostazioni internazionali

Per formare i nomi delle impostazioni internazionali, combina il codice della lingua con lo script facoltativo e codici regionali, separati da un trattino:

• Lingua: utilizza le due o tre lettere ISO 639-1 le API nel tuo codice.
• Script (facoltativo): utilizza lo script Codice ISO 15924.
• Regione (facoltativa): utilizza le due lettere ISO 3166-1-alpha-2 o il codice di tre cifre UN_M.49 le API nel tuo codice.

Ad esempio, se la tua lingua predefinita è Inglese americano:

unqualifiedResLocale=en-US

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

Puoi configurare manualmente l'app per assicurarti che le lingue siano configurabili in impostazioni di sistema su dispositivi con Android 13 o versioni successive. Per farlo, crea un locales_config e aggiungilo al file manifest dell'app utilizzando Attributo android:localeConfig. Manifest di android:localeConfig omesso indicatori di ingresso che indicano 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/locales_config.xml e specifica lingue diverse, incluse le app ultima versione locale di riserva, che corrisponde alle impostazioni internazionali specificate in res/values/strings.xml.

   Per i requisiti di formato, consulta la sezione Come specificare i nomi delle impostazioni internazionali. Vedi anche il file locale_config.xmldi esempio per un elenco di le impostazioni internazionali più utilizzate.

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

   • Inglese (Stati Uniti) come lingua di riserva definitiva
   • 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 file manifest, aggiungi una riga che rimandi a questo nuovo file:

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

Puoi aggiornare dinamicamente localeConfig dell'app con LocaleManager.setOverrideLocaleConfig per personalizzare il gruppo di lingue visualizzato nell'elenco delle lingue dell'app nelle Impostazioni di Android. Questo consente di personalizzare l'elenco di lingue per regione, eseguire esperimenti A/B e fornire aggiornamenti se la tua app utilizza i push della localizzazione lato server come mostrato nelle 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()

//For setOverrideLocaleConfig
mContext.getSystemService(LocaleManager.class).setOverrideLocaleConfig(new LocaleConfig(LocaleList.forLanguageTags("en-US,ja-JP,zh-Hans-SG")));

//For getOverrideLocaleConfig
// The app calls the API to get the override LocaleConfig
LocaleConfig overrideLocaleConfig = mContext.getSystemService(LocaleManager.class).getOverrideLocaleConfig();
// If the returned overrideLocaleConfig isn't equal to NULL, then the app calls the API to get the supported Locales
LocaleList supportedLocales = overrideLocaleConfig.getSupportedLocales();

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

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

LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).getApplicationLocales(appPackageName);

Specifica le lingue supportate in Gradle

Se non è già presente, specifica le stesse lingue utilizzando il metodo 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 la proprietà resourceConfigurations è presente, il sistema di compilazione include solo lingua nell'APK per le lingue specificate, impedendo le stringhe tradotte non vengano incluse da altre librerie che potrebbero supportare lingue non supportate dalla tua app. Per ulteriori informazioni, vedi specifica le lingue supportate dalla tua app.

In che modo gli utenti selezionano la lingua dell'app nelle impostazioni di sistema

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

• Accedi tramite le impostazioni di Sistema

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

• Accesso tramite le impostazioni App

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

Gestire i selettori della lingua in-app

Per le app che hanno già un selettore lingua in-app o vuoi utilizzarne uno, usa il le API pubbliche anziché la logica personalizzata dell'app per gestire le impostazioni e lingua preferita per l'app. Se utilizzi le API pubbliche per la tua app selettore lingua, le impostazioni di sistema del dispositivo vengono Deve corrispondere alla lingua selezionata dall'utente durante la tua esperienza in-app.

Per la compatibilità con le versioni precedenti di Android, ti consigliamo vivamente usando la libreria di supporto AndroidX durante l'implementazione di un selettore lingua in-app. Tuttavia, puoi anche implementare le API del framework direttamente se necessario.

Implementazione mediante la libreria di supporto AndroidX

Utilizza setApplicationLocales() e getApplicationLocales() in Appcompat 1.6.0 o superiore. Tieni presente che le API compatibili con le versioni precedenti funzionano con il contesto AppCompatActivity, e non il contesto dell'applicazione, per Android 12 (livello API 32) e versioni precedenti.

Ad esempio, per impostare la lingua preferita di un utente, gli chiedi di seleziona un'impostazione internazionale nel selettore della lingua, quindi imposta quel 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)

LocaleListCompat appLocale = 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 il tuo Activity, a meno che l'app gestisce la configurazione regionale modifiche da sola.

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 della lingua nell'app.

Supporto per Android 12 e versioni precedenti

Per il supporto di dispositivi con Android 12 (livello API 32) e versioni precedenti, AndroidX per gestire l'archiviazione locale impostando un valore autoStoreLocales su true e android:enabled a false nella voce del file manifest del Servizio AppLocalesMetadataHolderService, come mostrato nel codice seguente snippet:

<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 provoca una lettura di blocco sul thread principale e potrebbe causare StrictMode diskRead e diskWrite se stai registrando violazioni dei thread. Consulta AppCompatDelegate.setApplicationLocales() per ulteriori informazioni.

Gestione dello spazio di archiviazione personalizzato

Omissione della voce del file manifest o impostazione di autoStoreLocales su false indicatori che si gestisce il proprio spazio di archiviazione. In questo caso, devi fornire il parametro impostazioni internazionali archiviate prima del giorno onCreate nel ciclo di vita dell'attività e limitare le chiamate a AppCompatDelegate.setApplicationLocales() in Android 12 (livello API 32) oppure in basso.

Se la tua app ha una posizione di archiviazione locale personalizzata, ti consigliamo di usare una posizione passaggio tra la tua soluzione di archiviazione locale personalizzata e autoStoreLocales, quindi gli utenti continuano a utilizzare l'app nella lingua che preferiscono. In particolare applicabile nei casi in cui l'app viene eseguita per la prima volta dopo l'upgrade del dispositivo a Android 13. In questo caso, puoi fornire impostazioni internazionali preesistenti richieste dall'utente recuperando le impostazioni internazionali dallo spazio di archiviazione personalizzato e passandole a AppCompatDelegate.setApplicationLocales().

Esegui l'implementazione utilizzando le API del framework Android

Anche se consigliamo vivamente di utilizzare la libreria di supporto AndroidX per a implementare i selettori lingua in-app, puoi anche setApplicationLocales() e getApplicationLocales() nel framework Android per i dispositivi con Android 13.

Ad esempio, per impostare la lingua preferita di un utente, gli chiedi di seleziona un'impostazione internazionale nel selettore della lingua, quindi imposta quel valore nel sistema:

// 1. Inside an activity, in-app language picker gets an input locale "xx-YY"
// 2. App calls the API to set its locale
mContext.getSystemService(LocaleManager.class
    ).setApplicationLocales(new LocaleList(Locale.forLanguageTag("xx-YY")));
// 3. The system updates the locale and restarts the app, including any configuration updates
// 4. The app is now displayed in "xx-YY" language

Per visualizzare l'attuale lingua preferita dell'utente nel selettore della lingua, l'app può recuperare il valore dal sistema:

// 1. App calls the API to get the preferred locale
LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).getApplicationLocales();
// 2. App uses the returned LocaleList to display languages to the user

Best practice aggiuntive

Prendi nota delle seguenti best practice.

Prendi in considerazione il linguaggio quando richiami un intent in un'altra app

Gli intent incentrati sul linguaggio potrebbero consentirti di specificare la lingua l'app richiamata. Un esempio è la EXTRA_LANGUAGE dell'API Speech Recognition.

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

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

Se rimuovi le preferenze della lingua per app nelle impostazioni di sistema, ripristina le impostazioni internazionali dell'app su quelle di sistema.

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

Per questo motivo, se rimuovi android:localeConfig, valuta la possibilità di reimpostare le impostazioni internazionali dell'app alle impostazioni internazionali di sistema utilizzando LocaleListCompat.getEmptyLocaleList() o LocaleList.getEmptyLocaleList() come illustrato 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()

// 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
mContext.getSystemService(LocaleManager.class)
  .setApplicationLocales(LocaleList.getEmptyLocaleList());

Risorse aggiuntive

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

• Blog sulle impostazioni di lingua per app - Parte 1
• Blog sulle impostazioni di lingua per app - Parte 2
• App di esempio
• Video sulla realizzazione di un mondo multilingue

File locale_config.xml di esempio

Per impostazione predefinita, Android include le traduzioni a livello di sistema nell'Android Open Progetto di origine (AOSP) per un insieme standard delle impostazioni internazionali più comuni. Il file locale_config.xml di esempio incluso in questa sezione mostra le consigliato per ognuna di queste lingue. Fai riferimento a questo file di esempio per aiutarti crei il tuo file locale_config.xml per l'insieme di lingue supportati 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>