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.

• 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, et sont compatibles avec les APK divisés ainsi que 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

À 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 paramètre generateLocaleConfig dans le bloc androidResources {} du fichier build.gradle.kts au niveau du module (fichier build.gradle si vous utilisez Groovy). Cette fonctionnalité est désactivée par défaut.

   Kotlin

       android {
         androidResources {
           generateLocaleConfig = true
         }
       }
       

   Groovy

       android {
         androidResources {
           generateLocaleConfig true
         }
       }
       

2. 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-1 à 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 locales_config et ajoutez-le au fichier manifeste de votre application à l'aide de l'attribut android:localeConfig. Si vous omettez l'entrée android:localeConfig du fichier manifeste, 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/locales_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 locale_config.xml pour obtenir la liste des paramètres régionaux les plus couramment utilisés.

   Par exemple, formatez le fichier locales_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/locales_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 personnaliser la liste des langues par région, effectuer des tests A/B et fournir si votre application utilise des transferts de localisation côté serveur, comme indiqué 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()

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

De plus, les IME peuvent désormais utiliser LocaleManager.getApplicationLocales de connaître la langue de l'interface utilisateur de l'application actuelle afin de mettre à jour la langue du clavier affiché:

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

LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).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 propriété resourceConfigurations 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.

Pour assurer la rétrocompatibilité avec les versions précédentes d'Android, nous vous recommandons vivement d'utiliser la bibliothèque Support AndroidX lorsque vous implémentez un outil de sélection de langue intégré à l'application. Toutefois, vous pouvez également directement implémenter les API de framework si nécessaire.

Implémenter à l'aide de la bibliothèque Support AndroidX

Utilisez les méthodes setApplicationLocales() et getApplicationLocales() dans Appcompat 1.6.0 ou version ultérieure. Notez que 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.

Par exemple, 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 correspondant, 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)

LocaleListCompat appLocale = 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 le sélecteur 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. Pour en savoir plus, consultez AppCompatDelegate.setApplicationLocales().

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.

Par exemple, 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 correspondant, puis définir cette valeur dans le système :

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

Pour que la langue préférée d'un utilisateur s'affiche dans l'outil de sélection de langue, votre application peut récupérer cette valeur auprès du système :

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

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 Browser.EXTRA_HEADERS pour ouvrir une page Web dans la langue de votre application lorsque vous appelez un onglet Chrome personnalisé.

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

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

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, Blog partie 2
• Applications exemples
• Vidéo Créer un monde multilingue

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>