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 este documento, se describen las prácticas recomendadas para localizar apps para Android.

Debes tener conocimientos básicos sobre Kotlin o el lenguaje de programación Java, y estar familiarizado con la carga de recursos de Android, la declaración de los elementos de la interfaz de usuario en XML, 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 funciones 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 o en Java. 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 o el lenguaje de programación Java para manejar los datos de manera programática. En esta página, no se aborda cómo localizar el código basado en Kotlin o en Java.

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 strings de texto, diseños, 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 los recursos que mejor coinciden con el dispositivo, todo automáticamente.

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 la app, el sistema Android selecciona los recursos que cargará en función de la configuración regional del dispositivo. Para crear recursos, coloca los archivos dentro de 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 muestra lo que puede suceder cuando el archivo de texto predeterminado está incompleto.

Ejemplo:

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

• Cuando la app se inicia en un dispositivo con configuración regional en inglés, se puede ejecutar sin problemas, ya que res/values-en/strings.xml contiene ambas 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 que defina cada cadena necesaria. 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 diseños, elementos de diseño o animaciones. 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 la 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. En esas cadenas, usa el idioma predeterminado, que es el idioma que esperas que hable la mayoría de los usuarios de la app.

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

• res/drawable/ (directorio obligatorio que contiene al menos un archivo gráfico para el ícono de la app en Google Play)
• res/layout/ (directorio obligatorio que contiene un archivo XML que define el diseño predeterminado)
• res/anim/ (obligatorio si tienes carpetas de res/anim-<qualifiers>)
• res/xml/ (obligatorio si tienes carpetas de res/xml-<qualifiers>)
• res/raw/ (obligatorio si tienes carpetas de res/raw-<qualifiers>)

Sugerencia: En el código, examina cada referencia a un recurso de Android. Asegúrate de que se defina un recurso predeterminado para cada uno. También asegúrate de que el archivo de cadena predeterminado esté completo: un archivo de cadena localizado puede contener un subconjunto de cadenas, pero el archivo de cadena predeterminado tiene que contenerlos todos.

Crea recursos alternativos

Una parte importante de localizar una app es proporcionar texto alternativo para diferentes idiomas. En algunos casos, también puedes proporcionar gráficos, sonidos, diseños y otros recursos específicos de la configuración regional.

Una app puede especificar muchos directorios de res/<qualifiers>/, cada uno con diferentes calificadores. Para crear un recurso alternativo para una configuración regional diferente, utilizas 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; 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 en francés y todo el texto, excepto el título, en japonés. En este caso, debes crear tres archivos strings.xml, cada uno almacenado en un directorio de recursos específicos 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 para una cadena llamada title.
2. res/values-fr/strings.xml
   Contiene texto en francés para todas las strings, incluso title.
3. res/values-ja/strings.xml
   Contiene texto en japonés para todas las strings, excepto title.
   

Si el código basado en Kotlin o en Java 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, dado que esa cadena no se incluye en ese archivo, Android recurre a la predeterminada y carga title en inglés del 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 el uso con un dispositivo que espera la entrada de una pluma stylus y tiene una pantalla QVGA de baja densidad 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 requiere 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 matizada del proceso, consulta Cómo Android encuentra el recurso de coincidencia óptima. 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 o en Java, 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 cadenas a strings.xml

Cuando compiles tus apps, no codifiques ninguna cadena. En cambio, declara todas las cadenas como recursos en un archivo predeterminado strings.xml, lo que facilita la actualización y la localización. Las cadenas del archivo strings.xml se pueden extraer, traducir e integrar en la app de manera sencilla, con los calificadores adecuados, sin tener que realizar cambios en el código compilado.

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

Sigue los lineamientos de Android para las cadenas de IU

Cuando diseñes y desarrolles las IUs, presta mucha atención a cómo te diriges al usuario. En general, usa un estilo conciso y resumido que sea amigable, pero breve, y procura que sea consistente en todas las 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, el usuario considerará que tus apps son más refinadas, además de ayudarlo a comprender más rápidamente la IU.

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

Proporciona contexto suficiente para las cadenas declaradas

Si declaras cadenas en el 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 el diseño? 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 se traducirá 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. Mientras preparas las cadenas para la traducción, busca y marca el texto que debe permanecer tal cual, sin traducción, para que el traductor no lo cambie.

Para marcar el texto que no se 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 romper 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 la app reemplaza el valor de 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 Cómo traducir y localizar 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.

Elabora un diseño flexible

Si necesitas reorganizar el diseño para que se ajuste a un idioma determinado, puedes crear un diseño alternativo para ese idioma, como res/layout-de/main.xml para un diseño en alemán. Sin embargo, esto puede dificultar el mantenimiento de tu app. Es mejor crear un diseño único que sea más flexible.

Otro caso típico es un idioma que requiere algo diferente en el diseño. Por ejemplo, podrías tener un formulario de contacto que incluya dos campos de nombre cuando la app se ejecute en japonés, pero tres campos de nombre cuando se ejecute en algún otro idioma. Esto se podría abordar de dos maneras:

• Crea un diseño con un campo que puedas habilitar o inhabilitar de manera programática, según el idioma.
• Haz que el diseño principal incluya otro diseño que, a su vez, incluya el campo modificable. El segundo diseño puede tener diferentes configuraciones para diferentes idiomas.

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

Es probable que no tengas que crear una alternativa local específica para cada recurso de la app. Por ejemplo, el diseño definido en el archivo res/layout/main.xml podría funcionar con cualquier configuración regional; en ese caso, no es necesario crear ningún archivo de diseño alternativo.

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 string que usa la app está definida en res/values/strings.xml con la ortografía del inglés norteamericano.
• Para algunas frases importantes, quieres que la ortografía sea la del inglés británico. Quieres que se usen estas cadenas alternativas cuando la 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 sean diferentes cuando la app se ejecute 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 el objeto de contexto de Android para la búsqueda manual de configuración regional

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

val primaryLocale: Locale = context.resources.configuration.locales[0]
val locale: String = primaryLocale.displayName

Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
String locale = primaryLocale.getDisplayName();

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 realizar un pedido en una empresa de traducción. Puedes solicitar traducciones a un idioma o varios para cadenas de IU de la app, texto de la Ficha de Play Store, nombres de IAP y texto de campañas publicitarias.

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 realizas la prueba 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 en un emulador

Para obtener detalles acerca del 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 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, puedes cambiarla si mantienes presionado su nombre.
• Cambia a una configuración regional personalizada desde la 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 la 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 adjunto, especifica que quieres el emulador agregando la opción -e:
   adb -e shell
4. En el mensaje de 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 que correspondan 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. Cuando vuelva a aparecer la pantalla principal, reinicia la app. La app 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 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 Configuración regional personalizada para configurar el emulador en una configuración regional no compatible.
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 el archivo res/values/strings.xml incluya una definición para cada string que usa la app.

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