Préférence linguistique par appli

Dans bien des cas, les utilisateurs multilingues choisissent une langue (telle que l'anglais) pour leur système, mais veulent être en mesure d'en sélectionner d'autres (telles que le néerlandais, le chinois ou encore l'hindi) pour des applications spécifiques. Afin d'améliorer l'expérience de ces utilisateurs, Android 13 propose maintenant les fonctionnalités suivantes pour les applications prenant en charge plusieurs langues :

• Paramètres système : emplacement centralisé où les utilisateurs peuvent sélectionner une langue préférée pour chaque application.

  Vous pouvez configurer votre application pour qu'elle génère automatiquement les fichiers nécessaires afin de prendre en charge les préférences linguistiques par appli et qu'elle s'affiche dans les paramètres système. Pour en savoir plus, consultez les instructions pour activer la prise en charge automatique des langues par application support.

• API supplémentaires : ces API publiques telles que les méthodes setApplicationLocales et getApplicationLocales dans LocaleManager permettent aux utilisateurs d'une application de définir une langue différente de celle du système au moment de l'exécution.

  Ces API se synchronisent automatiquement avec les paramètres système. Par conséquent, les applications qui utilisent ces API pour créer des outils de sélection de langue personnalisés dans l'application garantissent une expérience cohérente, quel que soit l'endroit où les utilisateurs sélectionnent leurs préférences linguistiques. Les API publiques vous aident également à réduire la quantité de code récurrent, sont compatibles avec les APK divisés et acceptent la sauvegarde automatique des applications pour stocker les paramètres linguistiques de l'utilisateur au niveau de l'application.

  Pour assurer la rétrocompatibilité avec les versions précédentes d'Android, des API équivalentes sont également disponibles sur AndroidX. Toutefois, les API rétrocompatibles fonctionnent avec le contexte AppCompatActivity, et non le contexte de l'application, pour Android 12 (niveau d'API 32) et les versions antérieures. Accédez aux API rétrocompatibles avec Appcompat 1.6.0 ou version ultérieure.

Présentation de l'implémentation de cette fonctionnalité

Le tableau suivant présente les implémentations recommandées en fonction de différents cas d'utilisation.

Paramètres système pour les utilisateurs

Pour Android 13 ou les versions ultérieures, Android inclut un emplacement centralisé dans les paramètres système, qui permet de définir les préférences linguistiques par appli. Pour vous assurer que les langues de votre application sont bien configurables dans les paramètres système des appareils équipés d'Android 13 ou version ultérieure, activez la prise en charge automatique des langues par application (recommandé) ou configurez manuellement la prise en charge.

Activer la prise en charge automatique des langues par application

Il s'agit de la méthode recommandée pour ajouter la prise en charge des langues par application, car elle ne nécessite pas de modifications XML.

À partir d'Android Studio Giraffe et d'AGP 8.1, vous pouvez configurer votre application pour qu'elle prenne automatiquement en charge les préférences linguistiques par appli. En fonction des ressources de votre projet, AGP génère le fichier LocaleConfig et ajoute une référence à celui-ci dans le fichier manifeste final. Vous n'avez donc plus à le faire manuellement. Le plug-in Android Gradle utilise les ressources des dossiers res de vos modules d'application et les dépendances des modules de la bibliothèque pour déterminer les paramètres régionaux à inclure dans le fichier LocaleConfig. Cela signifie que si vous ajoutez des ressources pour une nouvelle langue à votre application, vous n'avez pas à vous soucier de mettre à jour le fichier LocaleConfig.

Notez que la fonctionnalité de prise en charge automatique des langues par application est compatible avec les applications qui exécutent Android 13 (niveau d'API 33) ou version ultérieure. Pour utiliser cette fonctionnalité, vous devez définir compileSdkVersion sur 33 ou plus. Pour configurer les préférences linguistiques par appli pour les versions antérieures d'Android, vous devez toujours utiliser les API et les outils de sélection de langue intégrés à l'application.

Pour activer la prise en charge automatique des langues par application :

1. Pour activer cette fonctionnalité, utilisez le generateLocaleConfig paramètre dans le androidResources {} bloc du fichier build.gradle.kts au niveau du module (build.gradle fichier si vous utilisez Groovy). Cette fonctionnalité est désactivée par défaut.

    android {
      androidResources {
        generateLocaleConfig = true
      }
    }

  android {
    androidResources {
      generateLocaleConfig true
    }
  }

1. Définissez des paramètres régionaux par défaut :
   1. Dans le dossier res du module d'application, créez un fichier nommé resources.properties.
   2. Dans le fichier resources.properties, définissez les paramètres régionaux par défaut avec le libellé unqualifiedResLocale. Pour mettre en forme les noms des paramètres régionaux, consultez Former des noms de paramètres régionaux.

AGP ajoute ces paramètres régionaux par défaut et tous les autres paramètres régionaux que vous avez spécifiés, à l'aide des répertoires values-* du dossier res, au fichier LocaleConfig généré automatiquement.

Former des noms de paramètres régionaux

Pour former des noms de paramètres régionaux, combinez le code de langue avec les codes de script et de région facultatifs, en les séparant par un tiret :

• Langue : utilisez le code ISO 639-2 à deux ou trois lettres.
• Script (facultatif) : utilisez le code ISO 15924.
• Région (facultatif) : utilisez le code ISO 3166-1-alpha-2 à deux lettres ou le code UN_M.49 à trois chiffres.

Par exemple, si votre paramètre régional par défaut est l'anglais américain :

unqualifiedResLocale=en-US

Utiliser android:localeConfig pour ajouter les langues prises en charge dans les paramètres système

Vous pouvez configurer manuellement votre application pour vous assurer que ses langues sont configurables dans les paramètres système des appareils équipés d'Android 13 ou version ultérieure. Pour ce faire, créez un fichier XML locale_config et ajoutez-le au fichier manifeste de votre application à l'aide de l'attribut android:localeConfig. Si vous omettez l'entrée du fichier manifeste android:localeConfig, les utilisateurs ne pourront pas définir la langue de votre application indépendamment de la langue de leur système dans les paramètres système.

Pour ajouter manuellement les langues prises en charge par votre application dans les paramètres système d'un utilisateur :

1. Créez un fichier appelé res/xml/locale_config.xml et spécifiez les langues de votre application, y compris les paramètres régionaux de remplacement ultimes de votre application, qui sont les paramètres régionaux spécifiés dans res/values/strings.xml.

   Pour connaître les exigences concernant le format, consultez Former des noms de paramètres régionaux. Consultez également l'exemple de fichier pour obtenir la liste des paramètres régionaux les plus couramment utilisés.locale_config.xml

   Par exemple, formatez le fichier locale_config.xml comme ceci pour une application prenant en charge les langues suivantes :

   • Anglais (États-Unis) comme paramètre régional de remplacement ultime
   • Anglais (Royaume-Uni)
   • Français
   • Japonais
   • Chinois (simplifié, Macao)
   • Chinois (traditionnel, 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. Dans le fichier manifeste, ajoutez une ligne pointant vers ce nouveau fichier :

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

Vous pouvez mettre à jour de manière dynamique le localeConfig de votre application avec LocaleManager.setOverrideLocaleConfig pour personnaliser l'ensemble des langues affichées dans la liste des langues par application dans les paramètres Android. Cela vous permet de personnaliser la liste des langues par région, d'effectuer des tests A/B et de fournir des paramètres régionaux mis à jour si votre application utilise des transferts de localisation côté serveur, comme illustré dans l'exemple suivant :

//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()

De plus, les IME peuvent désormais utiliser LocaleManager.getApplicationLocales pour connaître la langue de l'interface utilisateur de l'application actuelle et mettre à jour la langue du clavier, comme illustré ci-dessous :

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

Spécifier les langues prises en charge dans Gradle

Si ce n'est pas déjà fait, spécifiez les mêmes langues à l'aide de la resourceConfigurations propriété dans le fichier build.gradle au niveau du module de l'application :

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

Lorsque la propriété resourceConfigurations est présente, le système de compilation n'inclut que des ressources linguistiques dans l'APK pour les langues spécifiées, ce qui empêche l'inclusion de chaînes traduites d'autres bibliothèques susceptibles de prendre en charge les langues que votre application ne prend pas en charge. Pour en savoir plus, consultez Spécifier les langues prises en charge par votre application.

Comment les utilisateurs sélectionnent une langue pour l'application dans les paramètres système

Les utilisateurs peuvent sélectionner la langue de leur choix pour chaque application dans les paramètres système. Ils peuvent accéder à ces paramètres de deux manières différentes :

• Accès via les paramètres du système

  Paramètres > Système > Langues et saisie > Langue des applis > (sélectionner une application)

• Accès via les paramètres des applications

  Paramètres > Applications > (sélectionner une application) > Langue

Gérer les outils de sélection de langue intégrés à l'application

Pour les applications qui disposent déjà d'un outil de sélection de langue intégré ou qui souhaitent en utiliser un, il convient d'utiliser les API publiques au lieu de la logique d'application personnalisée pour gérer les paramètres et obtenir la langue préférée de l'utilisateur pour votre application. Si vous utilisez les API publiques pour votre outil de sélection de langue intégré, les paramètres système de l'appareil seront automatiquement mis à jour pour refléter le choix réalisé par l'utilisateur dans votre application.

Implémenter à l'aide de Jetpack Compose

Pour les applications entièrement conçues avec Jetpack Compose, le système gère automatiquement les mises à jour de l'interface utilisateur lorsque les paramètres régionaux de l'application changent. L'appel de l'API pour définir une nouvelle langue déclenche une modification de la configuration. Compose réagit en recomposant votre interface utilisateur et en résolvant automatiquement tous les appels stringResource à l'aide des nouveaux paramètres régionaux.

Pour assurer la rétrocompatibilité avec Android 12 (niveau d'API 32) et les versions antérieures, nous vous recommandons vivement d'utiliser la bibliothèque Support AndroidX (AppCompatDelegate) lorsque vous implémentez un outil de sélection de langue intégré à l'application. Si vous utilisez cette approche, l'activité qui héberge votre interface utilisateur Compose doit étendre AppCompatActivity. Toutefois, vous pouvez également directement implémenter les API de framework si nécessaire.

L'extrait de code suivant montre comment lire les paramètres régionaux actuels de l'application et en définir de nouveaux dans une fonction composable :

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"
        )
    }
}

Pour définir la langue préférée d'un utilisateur, vous devez lui demander d'en sélectionner une dans l'outil de sélection de langue, puis définir cette valeur dans le système :

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

Notez que l'appel de setApplicationLocales recrée votre Activity, sauf si votre application gère elle-même les modifications de configuration des paramètres régionaux.

Utilisez AppCompatDelegate.getApplicationLocales pour récupérer les paramètres régionaux préférés de l'utilisateur. L'utilisateur a peut-être sélectionné les paramètres régionaux dans les paramètres système ou dans l'outil de sélection de langue de votre application.

Compatibilité avec Android 12 et versions antérieures

Pour assurer la compatibilité avec les appareils équipés d'Android 12 (niveau d'API 32) ou version antérieure, indiquez à AndroidX de gérer le stockage des paramètres régionaux en définissant une valeur autoStoreLocales sur true et une valeur android:enabled sur false dans l'entrée du fichier manifeste du service AppLocalesMetadataHolderService de votre application, comme indiqué dans l'extrait de code suivant :

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

Notez que si vous définissez une valeur autoStoreLocales sur true, cela provoque une lecture des blocages sur le thread principal et peut entraîner une violation StrictMode diskRead et diskWrite si vous effectuez une journalisation des violations de thread. Consultez la section sur AppCompatDelegate.setApplicationLocales pour en savoir plus.

Gestion du stockage personnalisé

L'omission de l'entrée du fichier manifeste ou la définition de autoStoreLocales sur false indique que vous gérez votre propre espace de stockage. Dans ce cas, vous devez fournir les paramètres régionaux stockés avant onCreate dans le cycle de vie de l'activité et émettre des appels vers AppCompatDelegate.setApplicationLocales dans Android 12 (niveau d'API 32) ou version antérieure.

Si votre application dispose d'un emplacement de stockage régional personnalisé, nous vous recommandons de faire un transfert ponctuel entre votre solution de stockage des paramètres régionaux personnalisés et autoStoreLocales, afin que les utilisateurs puissent continuer à profiter de votre application dans la langue de leur choix. Cela est particulièrement utile lorsque vous exécutez votre application pour la première fois après la mise à niveau d'un appareil vers Android 13. Dans ce cas, vous pouvez fournir des paramètres régionaux préexistants demandés par l'utilisateur en les récupérant dans votre espace de stockage personnalisé et en les transmettant à AppCompatDelegate.setApplicationLocales.

Implémenter à l'aide des API du framework Android

Bien que nous recommandions vivement d'utiliser la bibliothèque Support AndroidX pour implémenter les outils de sélection de langue intégrés à l'application, vous pouvez également utiliser les méthodes setApplicationLocales et getApplicationLocales dans le framework Android pour les appareils équipés d'Android 13.

L'extrait de code suivant montre comment définir et obtenir la langue préférée de l'utilisateur à l'aide du service système 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()
    }
}

Autres bonnes pratiques

Tenez compte des bonnes pratiques suivantes.

Tenir compte de la langue lorsque vous appelez un intent dans une autre application

Les intents axés sur la langue peuvent vous permettre de spécifier la langue dans laquelle vous souhaitez appeler l'application. C'est par exemple le cas de la fonctionnalité EXTRA_LANGUAGE de l' API Speech Recognizer.

Envisager d'utiliser l'en-tête Accept-Language de l'onglet Chrome personnalisé

Envisagez d'ajouter l'en-tête Accept-Language via le Browser.EXTRA_HEADERS pour ouvrir une page Web dans la langue de votre application lorsque vous appelez un onglet personnalisé Chrome.

Rétablir les paramètres régionaux du système pour l'application si vous supprimez les préférences linguistiques par appli dans les paramètres système

Si vous supprimez les préférences linguistiques de votre application dans les paramètres système (en supprimant android:localeConfig du fichier AndroidManifest.xml de votre application), les utilisateurs ne pourront pas rétablir facilement les paramètres régionaux du système par défaut pour l'application.

Si vous supprimez android:localeConfig, envisagez donc de rétablir les paramètres régionaux du système pour l'application en utilisant LocaleListCompat.getEmptyLocaleList ou LocaleList.getEmptyLocaleList, comme dans l'extrait de code suivant :

// 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()

Exemple de fichier locale_config.xml

Par défaut, Android inclut des traductions au niveau du système dans le projet Android Open Source (AOSP) pour un ensemble standard des paramètres régionaux les plus communément utilisés. L'exemple de fichier locale_config.xml inclus dans cette section indique le format suggéré pour chacun de ces paramètres régionaux. Reportez-vous à cet exemple de fichier pour créer votre propre fichier locale_config.xml pour l'ensemble des langues prises en charge dans votre application.

<?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>

Ressources supplémentaires

Pour en savoir plus, consultez nos exemples de code, nos articles de blog et nos vidéos.

• Préférences linguistiques par appli, Blog partie 1
• Préférences linguistiques par appli, partie 2 blog
• Vidéo Créer un monde multilingue
• Ressources disponibles dans Compose