![](https://developer.android.google.cn/static/images/about/versions/13/app-languages.png?authuser=0000&hl=it)
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()
: egetApplicationLocales()
inLocaleManager
, 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.
Caso d'uso | Implementazione consigliata |
---|---|
La tua app non dispone di un selettore lingua in-app |
|
La tua app dispone già di un selettore lingua in-app |
|
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:
- Per attivare la funzionalità, usa
generateLocaleConfig
nel bloccoandroidResources {}
della sezione a livello di modulobuild.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 } }
- Specifica le impostazioni internazionali predefinite:
- Nella cartella
res
del modulo dell'app, crea un nuovo file denominatoresources.properties
. Nel file
resources.properties
, imposta il valore predefinito le impostazioni internazionali con l'etichettaunqualifiedResLocale
. Per formattare il i nomi delle impostazioni internazionali, consulta la sezione Come creare i nomi delle impostazioni internazionali.
- Nella cartella
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:
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 inres/values/strings.xml
.Per i requisiti di formato, consulta la sezione Come specificare i nomi delle impostazioni internazionali. Vedi anche il file
locale_config.xml
di 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>
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:
Kotlin
//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()
Java
//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:
Kotlin
val currentAppLocales: LocaleList = applicationContext.getSystemService(LocaleManager::class.java).getApplicationLocales(appPackageName)
Java
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:
Kotlin
val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY") // Call this on the main thread as it may require Activity.restart() AppCompatDelegate.setApplicationLocales(appLocale)
Java
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:
Kotlin
// 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()
Java
// 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>