Cómo localizar tu app

Android se ejecuta en muchos dispositivos, en muchas regiones. Para llegar a la mayoría de los usuarios, tu app debe manejar texto, archivos de audio, números, moneda 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.

Ya deberías contar con conocimientos básicos acerca de 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 interfaz de usuario en XML, 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 la funcionalidad principal de la app.

• Puedes colocar 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 este tema y en Cómo proveer recursos.
• 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ías que usar Kotlin o el lenguaje de programación Java para manejar los datos de manera programática. En este tema, no se aborda cómo localizar el código basado en Kotlin o en Java.

Para obtener una guía breve acerca de cómo localizar strings en la app, consulta Cómo brindar compatibilidad con diferentes idiomas.

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.

Este tema 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 (la orientación de la pantalla, el tipo de pantalla táctil, etc.), 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

Cada vez que la app se ejecuta en una configuración regional para la que no hayas proporcionado texto específico de la configuración regional, Android carga las strings predeterminadas desde res/values/strings.xml. Si este archivo predeterminado no está presente o si falta alguna string necesaria para la app, esta no se ejecuta y muestra un error. El ejemplo siguiente ilustra 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 strings, 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 strings de texto necesarias.
• Sin embargo, el usuario ve un mensaje de error y un botón Forzar cierre cuando la app se inicia en un dispositivo configurado en un idioma distinto del inglés. La app no se carga.

Para evitar esta situación, asegúrate de que exista un archivo res/values/strings.xml que defina cada string necesaria. La situación se aplica a todos los tipos de recursos, no solo a strings: tienes que crear un conjunto de archivos de recursos predeterminados que contengan todos los recursos a los que recurre la app (diseños, elementos de diseño, animaciones, etc.). Para obtener información sobre pruebas, consulta Prueba de recursos predeterminados.

Cómo usar recursos para la localización

Cómo crear recursos predeterminados

Coloca el texto predeterminado de la app en res/values/strings.xml.

Las strings de texto en res/values/strings.xml deberían usar 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 tiene que incluir todos los diseños y elementos de diseño predeterminados, y puede incluir otros tipos de recursos, como las animaciones:

• 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 string predeterminado esté completo: un archivo de string localizado puede contener un subconjunto de strings, pero el archivo de string predeterminado tiene que contenerlos todos.

Cómo crear 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. A fin de 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 la app es el inglés. Supongamos también que quieres localizar todo el texto de la app en francés y la mayor parte del texto de la app (todo excepto el título) en japonés. En este caso, podrías crear tres archivos strings.xml alternativos, 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 strings que usa la app, incluido el texto para una string 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.

Ten en cuenta que, si el dispositivo está configurado en japonés, Android busca title en el archivo res/values-ja/strings.xml. Sin embargo, dado que esa string 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 MCC y MNC (código móvil de país y código de red móvil).

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. Consulta Cómo Android busca el recurso que mejor coincide para obtener una descripción más matizada del proceso. Todos los calificadores se describen y se enumeran en orden de prioridad en la tabla 2 de Proporciona recursos alternativos.

Cómo hacer referencia a 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 Acceso a recursos.

Cómo administrar strings para la localización

Mover todas las strings a strings.xml

A medida que crees tus apps, no codifiques ninguna string. En cambio, declara todas las strings como recursos en un archivo predeterminado strings.xml, lo que facilita la actualización y la localización. Las strings 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 strings en strings.xml y vuelve a generarlas después de la traducción.

Sigue los lineamientos de Android para las strings de IU

Cuando diseñes y desarrolles las IU, asegúrate de prestar 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 IU.

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.

Otra recomendación es usar la terminología estándar de Android siempre que sea posible, como elementos de la interfaz de usuario, por ejemplo, la barra de acciones, el menú de opciones, la barra del sistema, las notificaciones, etc. 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 strings declaradas

Si declaras strings en el archivo strings.xml, asegúrate de describir el contexto en el que se usa la string. 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 strings 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, que puede incluir:

• ¿Para qué sirve esta string? ¿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 strings contienen texto que no se debe traducir a otros idiomas. Algunos ejemplos habituales pueden ser un fragmento de código, un marcador de posición para un valor, un símbolo especial o un nombre. Mientras preparas las strings 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 debe traducir, usa una etiqueta de marcador de posición <xliff:g>. Esta es una etiqueta de ejemplo que garantiza que el texto "%1$s" no se modifique durante la traducción (de lo contrario, se podría 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 siempre un atributo de ID que explique para qué sirve el marcador de posición. Si las apps reemplazan 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 el documento Lista de tareas para la localización.

Sugerencias de localización

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

No puedes tener suposiciones sobre el dispositivo en el que un usuario ejecuta la app. El dispositivo podría tener hardware que no esperabas o podría tener 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.

Asegúrate de incluir las carpetas res/drawable/ y res/values/ (sin ningún modificador adicional en los nombres de las carpetas) 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, al archivo predeterminado res/values/strings.xml le podría faltar una string necesaria para la app, y cuando la app se ejecuta con una configuración regional incompatible e intenta cargar res/values/strings.xml, el usuario recibe un mensaje de error y se muestra el botón Forzar cierre.

Para obtener más información, consulta Prueba de recursos predeterminados.

Elabora un diseño flexible

Si necesitas reorganizar el diseño a fin de adaptarlo a un idioma determinado (por ejemplo, el alemán), puedes crear un diseño alternativo para ese idioma (por ejemplo, res/layout-de/main.xml). Sin embargo, esto puede dificultar el mantenimiento de la 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 deba incluir 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 strings 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 sería necesario crear ningún archivo de diseño alternativo.

Además, es posible que no tengas que crear texto alternativo para cada string. 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 strings alternativas cuando la app se ejecute en un dispositivo en el Reino Unido.

Para hacerlo, puedes crear un pequeño archivo llamado res/values-en-rGB/strings.xml que incluya solo las strings que deberían ser diferentes cuando la app se ejecute en el Reino Unido. Para el resto de las strings, la app recurre a los valores predeterminados y usa lo que está definido 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:

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 la Play Console y también se puede acceder a él desde Android Studio. Es una forma rápida y sencilla de 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 strings 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 en un dispositivo

Ten en cuenta que el dispositivo que estás probando puede ser completamente diferente de los dispositivos disponibles para los consumidores en otras ubicaciones geográficas. 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 strings 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 Android Emulator.

Cómo crear y usar 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 el nombre de la configuración regional).
• Cambia a una configuración regional personalizada desde el shell adb, según se describe a continuació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 debe localizar correctamente.

Cómo cambiar la configuración regional del emulador desde el shell adb

Para cambiar la configuración regional en el emulador mediante el shell adb.

1. Elige la configuración regional que quieres probar y determina la etiqueta de idioma BCP-47; por ejemplo, el francés canadiense sería fr-CA.
   
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, agrega la opción-e:
   adb -e shell para especificar que quieres el emulador.
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 paréntesis 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 vuelve a aparecer la pantalla principal, reinicia la app, y podrás observar que esta lo hará con la nueva configuración regional.

Prueba de recursos predeterminados

A continuación, te indicamos cómo probar si una app incluye todos los recursos de strings que necesita:

1. Configura el emulador o dispositivo en un idioma que la app no admita. Por ejemplo, si la app tiene strings en francés en res/values-fr/, pero no tiene strings 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.