Preferências de idioma por app

Em muitos casos, os usuários multilíngues definem um idioma para o sistema, como o inglês, mas querem selecionar outros idiomas para apps específicos, como holandês, chinês ou hindi. A fim de ajudar os apps a oferecer uma melhor experiência a esses usuários, o Android 13 introduz os recursos abaixo para apps que oferecem suporte a vários idiomas:

• Configurações do sistema que permitem que os usuários selecionem o idioma preferido para cada app em um só lugar.

  Para informar ao sistema que ele oferece suporte para vários idiomas, o app precisa declarar o atributo android:localeConfig no manifesto. Para saber mais, consulte as instruções sobre como criar um arquivo de recursos e declará-lo no arquivo de manifesto do app.

• APIs que permitem que os apps definam um idioma diferente para ser usado na interface do usuário durante a execução.

  Apps que usam seletores de idioma personalizados precisam usar essas novas APIs para garantir que os usuários tenham uma experiência consistente, independente do local em que selecionarem as preferências de idioma. As novas APIs também ajudam a reduzir a quantidade de código boilerplate, oferecem suporte para APKs divididos e para Backup automático, permitindo que os apps armazenem as seleções de idioma do usuário.

  Para oferecer compatibilidade com versões anteriores do Android, as APIs também estão disponíveis no AndroidX. Recomendamos o uso do Appcompat 1.6.0-alpha04 ou versões mais recentes.

Os apps que não oferecem suporte a vários idiomas não são afetados por essas mudanças.

Visão geral da implementação desse recurso

A tabela a seguir mostra as implementações recomendadas de acordo com os diferentes casos de uso.

Caso de uso	Implementação recomendada
O app não tem um seletor de idioma	Use o atributo android:localeConfig no manifesto do app para adicionar os idiomas dele às configurações do smartphone. Opcionalmente, caso queira adicionar um seletor de linguagem no app, use a biblioteca do AndroidX e ative a implementação da API para oferecer compatibilidade com versões anteriores usando autoStoreLocales.
O app já tem um seletor de idioma	Use o atributo android:localeConfig no manifesto do app para adicionar os idiomas dele às configurações do smartphone. Migre a lógica personalizada do app para usar as novas APIs e garantir que os usuários tenham uma experiência consistente. É necessário processar os seguintes casos específicos: Chame AppCompatDelegate.setApplicationLocales() na primeira vez que o app for executado em um dispositivo com o Android 13. Chame AppCompatDelegate.setApplicationLocales() para fornecer as localidades já solicitadas pelo usuário ao sistema nos seguintes casos: Se o armazenamento automático estiver acionado no app para Android 12 (API de nível 32) e versões anteriores Se o app precisar migrar dados de um local de armazenamento de backup personalizado

Configurações do sistema para usuários

O Android 13 introduz um local centralizado nas configurações do smartphone para definir a seleção de idioma por app. Para garantir que os idiomas do app possam ser definidos nas configurações do sistema em dispositivos com o Android 13, crie um arquivo XML locales_config e adicione-o ao manifesto do app usando o atributo android:localeConfig. Omitir a entrada de manifesto android:localeConfig indica que os usuários não terão a opção de definir um idioma para o app de maneira independente do selecionado nas configurações do smartphone.

Importante: caso ocorra um comportamento inesperado ao testar esse recurso, tente encontrar as causas possíveis nos problemas conhecidos relacionados à IU de configurações do smartphone.

Usar android:localeConfig para adicionar os idiomas disponíveis às configurações do smartphone

Para adicionar os idiomas disponíveis para uso no app às configurações do smartphone, siga estas etapas:

1. Crie um arquivo chamado res/xml/locales_config.xml e especifique os idiomas do app da seguinte maneira:

   <?xml version="1.0" encoding="utf-8"?>
   <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
      <locale android:name="ja"/>
      <locale android:name="fr"/>
      <locale android:name="en"/>
   </locale-config>
   

2. No manifesto do app, adicione uma linha que leve a esse novo arquivo:

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

Como os usuários selecionam um idioma para o app nas configurações do sistema

Com as novas configurações do sistema, os usuários podem selecionar um idioma preferido para cada app. Os usuários podem acessar essas configurações de duas maneiras:

• Acessar as configurações do sistema

  Configurações > Sistema > Idioma e entrada > Idiomas do app > (selecionar um app)

• Acessar as configurações dos apps

  Configurações > Apps > (selecionar um app) > Idioma

Problemas conhecidos

Há alguns problemas conhecidos a serem considerados ao testar o app.

• Há um problema conhecido no AGP 7.3.0-alpha07 que pode causar falha ao tentar vincular recursos com android:localeConfig. Para contorná-lo, use uma versão anterior do AGP. Esse problema será resolvido em uma versão futura.

Processar seletores de idioma no app

Em apps que têm ou querem usar um seletor de idioma, utilize as novas APIs em vez da lógica personalizada do app para processar a configuração e usar o idioma selecionado pelo usuário.

Para oferecer compatibilidade com versões anteriores do Android, recomendamos o uso da Biblioteca de Suporte do AndroidX ao implementar um seletor de idioma no app. Também é possível implementar as APIs de framework diretamente, se necessário.

Implementar usando a Biblioteca de Suporte do AndroidX

Use o método setApplicationLocales() no Appcompat 1.6.0-alpha04 ou versões mais recentes.

Por exemplo, para definir o idioma de preferência de um usuário, peça para que ele selecione uma localidade no seletor de idioma e defina esse valor no 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);

Suporte para Android 12 e versões anteriores

Para oferecer suporte para dispositivos com o Android 12 (API de nível 32) e versões anteriores, instrua o AndroidX a processar o armazenamento da localidade. Para isso, defina o valor autoStoreLocales como true e android:enabled como false na entrada do serviço AppLocalesMetadataHolderService no manifesto do app, conforme mostrado no snippet de código a seguir:

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

Definir o valor autoStoreLocales como true causa uma leitura de método de bloqueio na linha de execução principal e pode causar uma violação StrictMode, diskRead e diskWrite se o app estiver registrando violações de linha de execução. Consulte AppCompatDelegate.setApplicationLocales() para ver mais informações.

Processar armazenamento personalizado

Omitir a entrada de manifesto ou definir autoStoreLocales como false indica que o app processa um armazenamento próprio. Nesse caso, é necessário informar as localidades armazenadas antes de onCreate no ciclo de vida da atividade e bloquear chamadas para AppCompatDelegate.setApplicationLocales() no Android 12 (API de nível 32) ou versões anteriores.

Se o app tiver um local de armazenamento de localidades personalizado, recomendamos usar uma transferência única entre a solução de armazenamento de localidades personalizada e autoStoreLocales, para que os usuários possam continuar a usar o app no idioma que preferirem. Isso vale principalmente para os casos em que o app é executado pela primeira vez depois que o dispositivo foi atualizado para o Android 13. Nesse caso, é possível recuperar as localidades já solicitadas pelo usuário do armazenamento personalizado e transmiti-las para AppCompatDelegate.setApplicationLocales().

Implementar usando as APIs do framework do Android

Embora seja altamente recomendável usar a Biblioteca de Suporte do AndroidX para implementar seletores de idioma no app, também é possível usar os métodos setApplicationLocales() e getApplicationLocales() no framework do Android para dispositivos com o Android 13.

Por exemplo, para definir o idioma de preferência de um usuário, peça para que ele selecione uma localidade no seletor de idioma e defina esse valor no 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(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

Para que o idioma preferido de um usuário apareça no seletor de idioma, o app pode extrair o valor do 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

Práticas recomendadas adicionais

Veja as práticas recomendadas a seguir.

Considerar o idioma ao invocar uma intent em outro app

Intents de idioma podem permitir especificar o idioma em que você quer exibir o app invocado. Um exemplo é o recurso EXTRA_LANGUAGE da API Speech Recognizer.

Usar o cabeçalho Accept-Language para guias personalizadas do Chrome

Adicione o cabeçalho Accept-Language (link em inglês) usando Browser.EXTRA_HEADERS para abrir uma página da Web no mesmo idioma do app ao invocar uma guia personalizada do Chrome.