Préférence linguistique par appli

Stay organized with collections Save and categorize content based on your preferences.
Langues par application dans les paramètres système

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.

    L'attribut android:localeConfig doit être déclaré dans le fichier manifeste de votre application pour indiquer au système qu'elle accepte plusieurs langues. Pour en savoir plus, consultez les instructions pour créer un fichier de ressources et le déclarer dans le fichier manifeste de votre 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, 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. Nous vous recommandons d'utiliser Appcompat 1.6.0-beta01 ou une version ultérieure.

Présentation de la mise en œuvre de cette fonctionnalité

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

Cas d'utilisation Implémentation recommandée
Votre application ne contient pas d'outil de sélection de langue intégré
  1. Utilisez l'attribut android:localeConfig dans le fichier manifeste de votre application pour ajouter les langues de votre application aux paramètres du téléphone.
  2. Si vous souhaitez ajouter un outil de sélection de langue intégré à l'application, vous pouvez également utiliser la bibliothèque AndroidX et activer notre implémentation d'API pour assurer la rétrocompatibilité avec autoStoreLocales.
Votre application dispose déjà d'un outil de sélection de langue intégré
  1. Utilisez l'attribut android:localeConfig dans le fichier manifeste de votre application pour ajouter les langues de votre application aux paramètres du téléphone.
  2. Migrez la logique personnalisée de votre application pour utiliser les API publiques afin de garantir aux utilisateurs une expérience cohérente.
  3. Traitez les cas de figure suivants :
    1. Appelez AppCompatDelegate.setApplicationLocales() la première fois que votre application est exécutée sur un appareil exécutant Android 13.
    2. Appelez AppCompatDelegate.setApplicationLocales() afin de fournir les paramètres régionaux préexistants demandés par l'utilisateur au système dans les cas de figure suivants :

Paramètres système pour les utilisateurs

Pour Android 13 ou les versions ultérieures, Android inclut un emplacement centralisé dans les paramètres du téléphone, 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, créez un fichier XML locales_config et ajoutez-le dans le 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 devraient pas pouvoir définir la langue de votre application indépendamment de la langue de leur système dans les paramètres de leur téléphone.

Utilisez android:localeConfig pour ajouter les langues prises en charge dans les paramètres du téléphone.

Pour ajouter les langues prises en charge par votre application dans les paramètres du téléphone 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 former les noms des 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.

    Consultez le format suggéré dans 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"/>
       <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>
    

Spécifiez 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é resConfigs dans le fichier build.gradle au niveau du module de l'application :

Groovy

  android {
      defaultConfig {
          ...
          resConfigs "en", "en-GB", "fr", "ja", "zh-Hans-MO", "zh-Hant-MO"
      }
  }
  

Kotlin

  android {
      defaultConfig {
          ...
          resConfigs("en", "en-GB", "fr", "ja", "zh-Hans-MO", "zh-Hant-MO")
      }
  }
  

Lorsque la propriété resConfigs 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 la section 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

Problèmes connus

Voici les problèmes connus à prendre en compte lorsque vous testez votre application :

  • Si vous utilisez les plug-ins Android Gradle (AGP) 7.3.0-alpha07 à 7.3.0-beta02 ou 7.4.0-alpha01 à 7.4.0-alpha03, vous pouvez rencontrer un problème qui entraîne l'échec de l'association des ressources lorsque vous déclarez android:localeConfig dans le fichier manifeste de votre application. Ce problème a été résolu dans les versions ultérieures d'AGP et du SDK Android. Si vous rencontrez ce problème, utilisez AGP 7.3.0-beta04 ou version ultérieure, ou AGP 7.4.0-alpha05 ou version ultérieure, avec la version 33 du SDK (compileSdk = 33).

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 mettre en œuvre 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-beta01 ou version ultérieure.

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 :

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

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.

Compatible 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 de sélectionner un paramètre régional dans l'outil de sélection de langue, puis de 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(newLocaleList(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 la valeur 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.

Tenez 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.

Envisagez 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é.

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="en-XA"/> <!-- English (Pseudo-Accents) -->
   <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="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="my-MM"/> <!-- Burmese (Myanmar) -->
   <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="tl"/> <!-- Filipino -->
   <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-CN"/> <!-- Chinese (Simplified) -->
   <locale android:name="zh-HK"/> <!-- Chinese (Hong Kong) -->
   <locale android:name="zh-TW"/> <!-- Chinese (Traditional) -->
   <locale android:name="zu"/> <!-- Zulu -->
</locale-config>