En muchos casos, los usuarios multilingües establecen un idioma para su sistema, como el inglés, pero desean seleccionar otros para apps específicas, como el chino, el hindi o el holandés. Con el fin de ayudar a que las apps brinden una mejor experiencia para estos usuarios, Android 13 presenta las siguientes funciones en las apps que admiten varios idiomas:
Parámetros de configuración del sistema que permiten que los usuarios seleccionen un idioma preferido para cada app en una ubicación centralizada.
La app debe declarar el atributo
android:localeConfigen el manifiesto de tu app para indicarle al sistema que admite varios idiomas. Si deseas obtener más información, consulta las instrucciones para crear un archivo de recursos y declararlo en el archivo de manifiesto de tu app.APIs que permiten que las apps configuren un idioma diferente en el tiempo de ejecución para utilizar en su interfaz de usuario.
Las apps que usan selectores de idioma integrados en la app deben usar estas nuevas APIs para garantizar que los usuarios tengan una experiencia coherente, sin importar dónde seleccionen sus preferencias de idioma. Las nuevas APIs también ayudan a reducir la cantidad de código estándar, admiten APK divididos y copias de seguridad automáticas para apps a fin de almacenar los parámetros de configuración de idiomas del usuario en el nivel de app.
Para ofrecer retrocompatibilidad con versiones anteriores de Android, las APIs también están disponibles en AndroidX. Te recomendamos que uses Appcompat 1.6.0-alpha04 o versiones posteriores.
Estos cambios no afectan a las apps que no admiten varios idiomas.
Descripción general de la implementación de esta función
En la siguiente tabla, se muestran implementaciones recomendadas, según diferentes casos de uso.
| Caso de uso | Implementación recomendada |
|---|---|
| Tu app no tiene un selector de idioma integrado |
|
| Tu app ya incluye un selector de idioma integrado |
|
Configuración del sistema para usuarios
En Android 13, se agrega una ubicación centralizada en la configuración del teléfono para establecer las preferencias de idioma de las apps. Para asegurarte de que se puedan configurar los idiomas en los parámetros de configuración del sistema en dispositivos que ejecutan Android 13, crea un archivo en formato XML locales_config y agrégalo al manifiesto de la app con el atributo android:localeConfig. Si omites los indicadores de entrada del manifiesto android:localeConfig, los usuarios no deberían poder configurar el idioma de tu app, independientemente del idioma del sistema en la configuración del teléfono.
Usa android:localeConfig para agregar los idiomas compatibles a la configuración del teléfono
Para agregar los idiomas compatibles de la app a la configuración del teléfono del usuario, haz lo siguiente:
Crea un archivo con el nombre
res/xml/locales_config.xmly especifica los idiomas de tu app de la siguiente manera:<?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>En el manifiesto, agrega una línea que dirija a este archivo nuevo:
<manifest ... <application ... android:localeConfig="@xml/locales_config"> </application> </manifest>
Cómo los usuarios seleccionan el idioma de una app en la configuración del sistema
Los usuarios pueden seleccionar el idioma de su preferencia para cada app mediante la nueva configuración del sistema. Pueden acceder a esta configuración de dos maneras diferentes:
Accede a través de la configuración del sistema
Configuración > Sistema > Idiomas y entradas > Idiomas de las apps > (selecciona una app)
Accede a través de la configuración de Apps
Configuración > Apps > (selecciona una app) > Idioma
Errores conocidos
Hay algunos problemas conocidos que debes tener en cuenta mientras pruebas tu app.
- Existe un problema conocido con AGP 7.3.0-alpha07 que puede provocar que la vinculación de recursos falle con
android:localeConfig. Para solucionar este problema, usa una versión anterior de AGP. Este problema debería resolverse en una próxima versión.
Controla los selectores de idiomas integrados en la app
En el caso de las apps que ya tienen un selector de idioma integrado en la app o que quieren utilizar uno, usa las APIs nuevas en lugar de la lógica personalizada de la app a fin de controlar la configuración y obtener el idioma preferido del usuario para tu app.
Para ofrecer retrocompatibilidad con versiones anteriores de Android, recomendamos que uses la biblioteca de compatibilidad de AndroidX cuando implementes un selector de idioma integrado en la app. Sin embargo, también puedes implementar las APIs del framework directamente si es necesario.
Implementación con la biblioteca de compatibilidad de AndroidX
Usa el método setApplicationLocales() en Appcompat 1.6.0-alpha04 o versiones posteriores.
Por ejemplo, para configurar el idioma de preferencia de un usuario, le pides a este que seleccione una configuración regional en el selector de idioma y que, luego, establezca ese valor en el 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);
Compatibilidad con Android 12 y versiones anteriores
Para admitir dispositivos que ejecutan Android 12 (nivel de API 32) y versiones anteriores, indícale a AndroidX que controle el almacenamiento de la configuración regional mediante la configuración de un valor autoStoreLocales en true y android:enabled en false en la entrada de manifiesto del servicio AppLocalesMetadataHolderService de la app, como se muestra en el siguiente fragmento de código:
<application
...
<service
android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
android:enabled="false"
android:exported="false">
<meta-data
android:name="autoStoreLocales"
android:value="true" />
</service>
...
</application>
Ten en cuenta que establecer un valor autoStoreLocales en true provoca un bloqueo de lectura en el subproceso principal y puede causar un incumplimiento de StrictMode diskRead y diskWrite si registras incumplimientos de subprocesos. Consulta AppCompatDelegate.setApplicationLocales() para obtener más información.
Control de almacenamiento personalizado
Omitir la entrada del manifiesto o la configuración de autoStoreLocales en false indica que controlas tu propio almacenamiento. En este caso, debes proporcionar los parámetros de configuración regional almacenados antes de onCreate en el ciclo de vida de la actividad y las llamadas de puerta a AppCompatDelegate.setApplicationLocales() en Android 12 (nivel de API 32) o versiones anteriores.
Si tu app tiene una ubicación de almacenamiento de configuración regional personalizada, te recomendamos que uses una transferencia única entre la solución de almacenamiento de configuración regional personalizada y autoStoreLocales, para que los usuarios continúen disfrutando de tu app en el idioma que prefieran; en especial, cuando la app se ejecuta por primera vez después de que un dispositivo se actualizó a Android 13. En este caso, puedes proporcionar parámetros preexistentes de configuración regional que solicitó el usuario. Para ello, debes recuperar estos parámetros de tu almacenamiento personalizado y pasarlos a AppCompatDelegate.setApplicationLocales().
Implementación con las APIs del framework de Android
Si bien te recomendamos que uses la biblioteca de compatibilidad de AndroidX a fin de implementar selectores de idiomas integrados en la app, también puedes usar los métodos setApplicationLocales() y getApplicationLocales() en el framework de Android para dispositivos que ejecutan Android 13.
Por ejemplo, para configurar el idioma de preferencia de un usuario, le pides a este que seleccione una configuración regional en el selector de idioma y que, luego, establezca ese valor en el 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 el idioma actual de preferencia de un usuario se muestre en el selector de idioma, tu app puede recuperar el valor del 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ácticas recomendadas adicionales
Toma nota de las siguientes prácticas recomendadas.
Ten en cuenta el idioma cuando invoques un intent en otra app
Es posible que los intents centrados en el idioma te permitan especificar el idioma en el que deseas que esté la app invocada. Un ejemplo es la función EXTRA_LANGUAGE de la API de Speech Recognizer.
Ten en cuenta el encabezado Accept-Language para la pestaña personalizada de Chrome
Te recomendamos que agregues el encabezado Accept-Language a través de Browser.EXTRA_HEADERS para abrir una página web en el idioma de tu app cuando invoques una pestaña personalizada de Chrome.