Cómo localizar tu app

Android se ejecuta en muchos dispositivos, en muchas regiones. Para llegar a la mayoría de los usuarios, asegúrate de que tu app maneje textos, archivos de audio, números, monedas y gráficos de manera apropiada a la configuración regional donde se usa.

En esta página, se describen las prácticas recomendadas para localizar apps para Android.

Debes tener conocimientos básicos sobre Kotlin y estar familiarizado con la carga de recursos de Android, las consideraciones de desarrollo como el ciclo de vida de la actividad, y los principios generales de internacionalización y localización.

Una buena práctica es usar el framework de recursos de Android para separar los aspectos localizados de tu app lo máximo posible de las funcionalidades principales de la app.

• Coloca la mayor parte o la totalidad del contenido de la interfaz de usuario de la app en los archivos de recursos, como se describe en esta página y en la descripción general de recursos de la app.
• Por otro lado, el comportamiento de la interfaz de usuario está impulsado por el código basado en Kotlin. Por ejemplo, si los usuarios ingresaran datos que se deben formatear u ordenar de manera diferente según la configuración regional, tendrás que usar Kotlin para manejar los datos de manera programática. En esta página, no se aborda cómo localizar el código basado en Kotlin.

En esta guía, se explica el sistema de localización principal de Android que se usa en todas las apps para Android. Para obtener información sobre cómo cargar estos recursos localizados en la IU de Jetpack Compose, consulta Recursos en Compose.

Si deseas obtener una guía breve para localizar cadenas en la app, consulta Cómo brindar compatibilidad con diferentes idiomas y culturas.

Descripción general: Cambio de recursos en Android

Los recursos son cadenas de texto, sonidos, gráficos y cualquier otro dato estático que necesite la app para Android. Una app puede incluir varios conjuntos de recursos, cada uno personalizado para una configuración de dispositivo diferente. Cuando un usuario ejecuta la app, Android selecciona y carga automáticamente los recursos que mejor coinciden con el dispositivo.

Esta página se enfoca en la localización y la configuración regional. Para obtener una descripción completa del cambio de recursos y todos los tipos de configuraciones que puedes especificar, como la orientación de la pantalla o el tipo de pantalla táctil, consulta Cómo proporcionar recursos alternativos.

Cuando escribes la app, creas recursos predeterminados y alternativos para que esta los use. Cuando los usuarios ejecutan tu app, el sistema Android selecciona qué recursos cargar según la configuración regional del dispositivo. Para crear recursos, coloca archivos en subdirectorios con nombres especiales del directorio res/ del proyecto.

Por qué los recursos predeterminados son importantes

Cuando la app se ejecuta en cualquier configuración regional para la que no hayas proporcionado texto específico de la configuración regional, Android carga las cadenas predeterminadas desde res/values/strings.xml. Si este archivo predeterminado no está presente o si falta alguna cadena necesaria para la app, esta no se ejecuta y muestra un error. En el siguiente ejemplo, se ilustra lo que puede suceder cuando el archivo de texto predeterminado está incompleto.

Ejemplo:

El código basado en Kotlin de una app se refiere a solo dos cadenas, text_a y text_b. La app incluye un archivo de recursos localizados (res/values-en/strings.xml) que define text_a y text_b en inglés. La app también incluye un archivo de recursos predeterminado (res/values/strings.xml) que incluye una definición para text_a, pero no para text_b.

• Cuando esta app se inicia en un dispositivo con la configuración regional establecida en inglés, es posible que se ejecute sin problemas, ya que res/values-en/strings.xml contiene las dos cadenas de texto necesarias.
• Sin embargo, cuando la app se inicia en un dispositivo configurado en un idioma que no sea inglés, el usuario ve un mensaje de error y un botón para forzar el cierre. La app no se carga.

Para evitar esta situación, asegúrate de que exista un archivo res/values/strings.xml y que defina todas las cadenas necesarias. Esta situación se aplica a todos los tipos de recursos, no solo a cadenas: debes crear un conjunto de archivos de recursos predeterminados que contengan todos los recursos a los que llama tu app, como elementos de diseño, fuentes o colores. Para obtener más información sobre las pruebas, consulta la sección Prueba los recursos predeterminados.

Cómo usar recursos para la localización

En esta sección, se explica cómo crear recursos predeterminados y alternativos. También se explica cómo se asigna prioridad a los recursos y cómo se hace referencia a ellos en el código.

Crea recursos predeterminados

Coloca el texto predeterminado de la app en res/values/strings.xml. Para estas cadenas, usa el idioma predeterminado, es decir, el idioma que esperas que hablen la mayoría de los usuarios de tu app.

El conjunto de recursos predeterminados también incluye cualquier elemento de diseño predeterminado y puede incluir otros tipos de recursos, como íconos o cadenas. Estos recursos se encuentran en los siguientes directorios:

• res/drawable/: Es un directorio obligatorio que contiene al menos un archivo gráfico para el ícono de la app en Google Play.
• res/xml/: Es obligatorio si tienes carpetas res/xml-<qualifiers>.
• res/raw/: Es obligatorio si tienes carpetas res/raw-<qualifiers>.

Crea recursos alternativos

Una gran parte de la localización de una app es proporcionar texto alternativo para diferentes idiomas. En algunos casos, también proporcionas gráficos, sonidos y otros recursos alternativos específicos de la configuración regional.

Una app puede especificar muchos res/<qualifiers>/ directorios, cada uno con diferentes calificadores. Para crear un recurso alternativo para una configuración regional diferente, usa un calificador que especifique un idioma o una combinación de idioma y región. El nombre de un directorio de recursos tiene que cumplir con el esquema de nombres que se describe en Cómo proporcionar recursos alternativos, o de lo contrario la app no podrá compilar.

Ejemplo:

Supongamos que el idioma predeterminado de tu app es el inglés y que quieres localizar todo el texto de la app al francés y todo el texto, excepto el título de la app, al japonés. En este caso, crea tres archivos strings.xml, cada uno almacenado en un directorio de recursos específico de la configuración regional:

1. res/values/strings.xml
   Contiene texto en inglés para todas las cadenas que usa la app, incluido el texto de una cadena llamada title.
2. res/values-fr/strings.xml
   Contiene texto en francés para todas las cadenas, incluido title.
3. res/values-ja/strings.xml
   Contiene texto en japonés para todas las cadenas, excepto title.

Si el código basado en Kotlin hace referencia a R.string.title, esto es lo que sucede en el entorno de ejecución:

• Si el dispositivo está configurado en cualquier idioma que no sea francés, Android carga title desde el archivo res/values/strings.xml.
• Si el dispositivo está configurado en francés, Android carga title desde el archivo res/values-fr/strings.xml.

Si el dispositivo está configurado en japonés, Android busca title en el archivo res/values-ja/strings.xml. Sin embargo, como no se incluye ninguna cadena de ese tipo en ese archivo, Android recurre al valor predeterminado y carga el title en inglés desde el archivo res/values/strings.xml.

¿Qué recursos tienen prioridad?

Si varios archivos de recursos coinciden con la configuración de un dispositivo, Android sigue un conjunto de reglas para decidir qué archivo usar. Entre los calificadores que se pueden especificar en un nombre de directorio de recursos, la configuración regional casi siempre tiene prioridad.

Ejemplo:

Supongamos que una app incluye un conjunto predeterminado de gráficos y otros dos conjuntos de gráficos, cada uno optimizado para una configuración de dispositivo diferente:

• res/drawable/
  Contiene gráficos predeterminados.
• res/drawable-small-land-stylus/
  Contiene gráficos optimizados para usar con un dispositivo que espera la entrada de una pluma stylus y tiene una pantalla de baja densidad QVGA en orientación horizontal.
• res/drawable-ja/
  Contiene gráficos optimizados para usar con japonés.

Si la app se ejecuta en un dispositivo configurado para usar japonés, Android carga gráficos desde res/drawable-ja/, incluso si el dispositivo es el que espera la entrada de una pluma stylus y tiene una pantalla QVGA de baja densidad en orientación horizontal.

Excepción: Los únicos calificadores que tienen prioridad sobre la configuración regional en el proceso de selección son el código móvil de país (MCC) y el código de red móvil (MNC).

Ejemplo:

Supongamos que tienes la siguiente situación:

• El código de la app llama a R.string.text_a.
• Hay dos archivos de recursos relevantes disponibles:
  • res/values-mcc404/strings.xml, que incluye text_a en el idioma predeterminado de la app, en este caso, inglés.
  • res/values-hi/strings.xml, que incluye text_a en hindi.
• La app se ejecuta en un dispositivo que tiene la siguiente configuración:
  • La tarjeta SIM está conectada a una red móvil en India (MCC 404).
  • El idioma está configurado en hindi (hi).

Android carga text_a desde res/values-mcc404/strings.xml (en inglés), incluso si el dispositivo está configurado para hindi. Esto se debe a que, en el proceso de selección de recursos, Android prefiere una coincidencia de MCC a una coincidencia de idioma.

El proceso de selección no siempre es tan sencillo como sugieren estos ejemplos. Para obtener una descripción más detallada del proceso, consulta Cómo Android encuentra el recurso que mejor coincide. Todos los calificadores se describen y se enumeran en orden de prioridad en la Descripción general de recursos de la app.

Consulta los recursos del código

En el código de la app basado en Kotlin, te referirás a los recursos con la sintaxis R.resource_type.resource_name o android.R.resource_type.resource_name. Para obtener más información, consulta Cómo acceder a los recursos de tu app.

Cómo administrar cadenas para la localización

En esta sección, se describen las prácticas recomendadas para administrar tus cadenas relacionadas con la localización.

Mueve todas las strings a strings.xml

Cuando compiles tus apps, no codifiques ninguna cadena. En su lugar, declara todas tus cadenas como recursos en un archivo strings.xml predeterminado, lo que facilita su actualización y localización. Las cadenas del archivo strings.xml se pueden extraer, traducir y volver a integrar fácilmente en tu app, con los calificadores adecuados, sin ningún cambio en el código compilado.

Por ejemplo, con Compose, puedes cargar una cadena como esta:

// In the res/values/strings.xml file
// <string name="compose">Jetpack Compose</string>

// In your Compose code
Text(
    text = stringResource(R.string.compose)
)
ResourcesSnippets.kt

Si generas imágenes con texto, coloca esas cadenas también en strings.xml y vuelve a generar las imágenes después de la traducción.

Sigue los lineamientos de Android para las cadenas de IU

A medida que diseñes y desarrolles tus IUs, presta mucha atención a cómo te diriges al usuario. En general, usa un estilo sucinto que sea amigable pero breve, y usa un estilo coherente en todas tus IUs.

Asegúrate de leer y seguir las recomendaciones de Material Design para el estilo de escritura y la elección de palabras. Si lo haces, tus apps se verán más pulidas para el usuario y lo ayudarán a comprender la IU más rápido.

Además, siempre que sea posible, usa la terminología estándar de Android, como para elementos de la IU como la barra de la app, el menú de opciones, la barra del sistema y las notificaciones. Usar los términos de Android de forma correcta y coherente facilita la traducción y da como resultado un mejor producto final para los usuarios.

Proporciona contexto suficiente para las strings declaradas

Cuando declares cadenas en tu archivo strings.xml, asegúrate de describir el contexto en el que se usa la cadena. Esta información es invaluable para el traductor y da como resultado una traducción de mejor calidad. También te ayuda a administrar tus cadenas de manera más eficaz.

A continuación, se muestra un ejemplo:

<!-- The action for submitting a form. This text is on a button that can fit 30 chars -->
<string name="login_submit_button">Sign in</string>

Considera proporcionar información de contexto como la siguiente:

• ¿Para qué sirve esta cadena? ¿Cuándo y dónde se presenta al usuario?
• ¿Dónde está esto en la IU? Por ejemplo, las traducciones son menos flexibles en los botones que en los cuadros de texto.

Marca las partes del mensaje que no deben traducirse

A menudo, las cadenas contienen texto que no está destinado a traducirse a otros idiomas. Algunos ejemplos comunes son un fragmento de código, un marcador de posición para un valor, un símbolo especial o un nombre. Cuando prepares tus cadenas para la traducción, busca y marca el texto que debe permanecer tal como está, sin traducción, para que el traductor no lo cambie.

Para marcar el texto que no se debe traducir, usa una etiqueta de marcador de posición <xliff:g>. Esta es una etiqueta de ejemplo que indica que el texto "%1$s" no se debe cambiar durante la traducción para evitar interrumpir el mensaje:

<string name="countdown">
  <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday
</string>

Cuando declares una etiqueta de marcador de posición, agrega un atributo de ID que explique para qué sirve el marcador de posición. Si tu app reemplaza más tarde el valor del marcador de posición, asegúrate de proporcionar un atributo de ejemplo para aclarar el uso esperado.

Estos son algunos ejemplos más de etiquetas de marcador de posición:

<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
<!-- Example placeholder for a special Unicode symbol -->
<string name="star_rating">Check out our 5
    <xliff:g id="star">\u2605</xliff:g>
</string>
<!-- Example placeholder for a URL -->
<string name="app_homeurl">
    Visit us at <xliff:g
    id="application_homepage">http://my/app/home.html</xliff:g>
</string>
<!-- Example placeholder for a name -->
<string name="prod_name">
    Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g>
</string>
<!-- Example placeholder for a literal -->
<string name="promo_message">
    Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount.
</string>
...
</resources>

Lista de tareas para la localización

Para obtener una descripción general completa del proceso de localización y distribución de una app para Android, consulta Traduce y localiza tu app.

Sugerencias de localización

Sigue estas sugerencias mientras localizas tu app.

Diseña tu app para que funcione con cualquier configuración regional

No des por sentado nada sobre el dispositivo en el que un usuario ejecuta tu app. Es posible que el dispositivo tenga hardware que no esperabas o que se haya establecido en una configuración regional que no tenías pensada o que no puedes probar. Diseña tu app para que funcione con normalidad o falle sin mayores molestias, independientemente del dispositivo en el que se ejecute.

Importante: Asegúrate de que la app incluya un conjunto completo de recursos predeterminados: incluye las carpetas res/drawable/ y res/values/, sin ningún modificador adicional en su nombre, que contengan todas las imágenes y el texto que la app necesita.

La app no se ejecutará en un dispositivo con una configuración regional incompatible si le falta aunque sea un solo recurso predeterminado. Por ejemplo, si al archivo predeterminado res/values/strings.xml le falta una cadena necesaria para la app, cuando esta se ejecute en una configuración regional incompatible e intente cargar res/values/strings.xml, el usuario verá un mensaje de error y un botón para forzar el cierre.

Para obtener más información, consulta la sección Prueba los recursos predeterminados.

Evita crear más archivos de recursos y cadenas de texto de los que necesitas

Es probable que no necesites crear una alternativa específica de la configuración regional para cada recurso de tu app. Por ejemplo, un logotipo de la app definido en el directorio res/drawable/ podría funcionar en cualquier configuración regional, en cuyo caso no es necesario crear archivos gráficos alternativos.

Además, es posible que no tengas que crear texto alternativo para cada cadena. Por ejemplo, supongamos lo siguiente:

• El idioma predeterminado de la app es el inglés norteamericano. Cada cadena que usa la app se define con la ortografía del inglés norteamericano en res/values/strings.xml.
• Para algunas frases importantes, quieres que la ortografía sea la del inglés británico. Quieres que se usen estas cadenas alternativas cuando tu app se ejecute en un dispositivo en el Reino Unido.

Para ello, crea un archivo pequeño llamado res/values-en-rGB/strings.xml que incluya solo las cadenas que son diferentes cuando la app se ejecuta en el Reino Unido. Para el resto de las cadenas, la app recurre a los valores predeterminados y usa lo que se define en res/values/strings.xml.

Usa LocalConfiguration para la búsqueda manual de la configuración regional

Puedes buscar la configuración regional con LocalConfiguration que Android pone a disposición, como se muestra en el siguiente ejemplo:

val locale = LocalConfiguration.current.locales[0]

Usa el servicio de traducción de apps

El servicio de traducción de apps está integrado en Play Console. Te permite obtener una cotización instantánea y hacer un pedido a una empresa de traducción. Puedes pedir traducciones a uno o más idiomas para cadenas de la IU de la app, texto de la ficha de Play Store, nombres de IAP y texto de la campaña publicitaria.

Usa Gemini para traducir cadenas de apps

Puedes usar Gemini en Android Studio para traducir los recursos de cadenas de tu app directamente en tu proyecto. Para obtener más información, consulta Traduce y localiza tu app.

Cómo probar apps localizadas

Prueba tu app localizada en un dispositivo o en Android Emulator. En particular, prueba tu app para asegurarte de que se incluyan todos los recursos predeterminados necesarios.

Prueba en un dispositivo

Ten en cuenta que el dispositivo en el que estás probando puede ser muy diferente de los dispositivos disponibles para los consumidores en otros lugares. Las configuraciones regionales disponibles en tu dispositivo pueden ser diferentes de aquellas disponibles en otros dispositivos. Además, la resolución y la densidad de la pantalla del dispositivo pueden diferir, lo que podría afectar la visualización de cadenas y de elementos de diseño de la IU.

Para cambiar la configuración regional o el idioma en un dispositivo, usa la app de configuración.

Prueba con vistas previas componibles

Antes de realizar pruebas en un dispositivo, puedes usar vistas previas componibles en Android Studio para probar IUs localizadas sin implementarlas en un emulador. Para obtener una vista previa de la IU en diferentes idiomas, usa la @Preview anotación (como @Preview(locale = "fr")). También puedes probar diseños de derecha a izquierda (RTL) especificando una configuración regional RTL como @Preview(locale = "ar").

Prueba en un emulador

Para obtener detalles sobre el uso del emulador, consulta Cómo ejecutar apps en Android Emulator.

Crea y usa una configuración regional personalizada

Una configuración regional "personalizada" es una combinación de idioma o región que la imagen del sistema Android no admite explícitamente. Para probar cómo se ejecuta tu app en una configuración regional personalizada, crea una configuración regional personalizada en el emulador. Existen dos maneras de hacerlo.

• Usa la app de configuración regional personalizada, a la que se puede acceder desde la pestaña de la app. Después de crear una configuración regional personalizada, cambia a ella manteniendo presionado el nombre de la configuración regional.
• Cambia a una configuración regional personalizada desde el shell adb, como se describe en la siguiente sección.

Cuando configuras el emulador con una configuración regional que no está disponible en la imagen del sistema Android, el sistema se muestra en el idioma predeterminado. Sin embargo, tu app se localiza de manera correcta.

Cambia la configuración regional del emulador desde el shell adb

Para cambiar la configuración regional en el emulador mediante el shell adb, haz lo siguiente:

1. Elige la configuración regional que quieres probar y determina su etiqueta de idioma BCP-47, como fr-CA para el francés canadiense.
2. Inicia un emulador.
3. Desde un shell de línea de comandos en la computadora host, ejecuta el siguiente comando:
   adb shell
   o, si tienes un dispositivo conectado, especifica que quieres el emulador agregando la opción -e:
   adb -e shell
4. En el símbolo del sistema del shell adb (#), ejecuta este comando:
   setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
   Reemplaza las secciones entre corchetes con los códigos correspondientes del paso 1.
   
   Por ejemplo, para probar en francés canadiense:
   setprop persist.sys.locale fr-CA;stop;sleep 5;start

Esto hace que el emulador se reinicie. Una vez que vuelva a aparecer la pantalla principal, vuelve a iniciar la app, y esta se iniciará con la nueva configuración regional.

Prueba los recursos predeterminados

Para probar si una app incluye todos los recursos de cadenas que necesita, haz lo siguiente:

1. Configura el emulador o el dispositivo en un idioma que tu app no admita. Por ejemplo, si la app tiene cadenas en francés en res/values-fr/, pero no tiene cadenas en español en res/values-es/, establece la configuración regional del emulador en español. Puedes usar la app de configuración regional personalizada para configurar el emulador en una configuración regional no admitida.
2. Ejecuta la app.
3. Si la app muestra un mensaje de error y el botón Forzar cierre, se podría deber a que busca una string que no está disponible. Asegúrate de que tu archivo res/values/strings.xml incluya una definición para cada cadena que use la app.

Si la prueba resulta satisfactoria, repítela para otros tipos de configuraciones. Por ejemplo, si la app tiene un archivo de cadenas llamado res/values-land/strings.xml, pero no contiene un archivo llamado res/values-port/strings.xml, configura el emulador o el dispositivo en orientación vertical y comprueba si se ejecuta la app.

Recursos adicionales

Para obtener más información sobre la localización, consulta los siguientes recursos adicionales:

Documentación

• Descripción general de los recursos de las apps
• Traduce y localiza tu app

Contenido de Views

• Localiza tu app (Views)