Cómo brindar compatibilidad con diferentes idiomas y culturas

Las apps incluyen recursos que pueden ser específicos de una cultura en particular. Por ejemplo, una app puede incluir strings específicas de una cultura que se traducen al idioma de la configuración regional actual. Se recomienda mantener los recursos específicos de una cultura separados del resto de la app. Android resuelve los recursos específicos del idioma y de la cultura en función de la configuración regional del sistema. Puedes proporcionar compatibilidad con diferentes configuraciones regionales mediante el directorio de recursos en tu proyecto de Android.

Puedes especificar recursos adaptados a la cultura de las personas que usan tu app y proporcionar cualquier tipo de recurso que sea adecuado para el idioma y la cultura de tus usuarios. Por ejemplo, en la siguiente captura de pantalla, verás una app en la que se muestran una string y recursos de elementos de diseño en la configuración regional predeterminada (en_US) del dispositivo y en la configuración regional en español (es_ES).

Figura 1: App que usa diferentes recursos según la configuración regional actual

Si compilaste tu proyecto con las herramientas del SDK de Android (consulta Cómo crear un proyecto de Android), estas crean un directorio res/ en el nivel superior del proyecto. El directorio res/ contiene subdirectorios para distintos tipos de recursos. También incluye algunos archivos predeterminados, como res/values/strings.xml, que contiene los valores de tu string.

La compatibilidad con varios idiomas va más allá del uso de recursos específicos de la configuración regional. Algunos usuarios eligen un idioma que usa escritura de derecha a izquierda (RTL), como el árabe o el hebreo, para la configuración regional de su IU. Otros ven o generan contenido en un idioma que utiliza un alfabeto de derecha a izquierda, aunque hayan establecido un idioma con alfabeto de izquierda a derecha (por ejemplo, inglés) como configuración regional de la IU. Para brindar compatibilidad a ambos tipos de usuarios, tu app debe realizar lo siguiente:

• Debe usar un diseño de IU de derecha a izquierda para configuraciones regionales con escritura de derecha a izquierda.
• Debe detectar y declarar la dirección de los datos de texto que se muestran en los mensajes con formato. Por lo general, solo necesitas llamar a un método que determine la dirección de los datos de texto por ti.

Cómo crear archivos de recursos y directorios de configuraciones regionales

Para agregar compatibilidad con más configuraciones regionales, crea directorios adicionales dentro de res/. El nombre de cada directorio debe tener el siguiente formato:

<resource type>-b+<language code>[+<country code>]

Por ejemplo, values-b+es/ contiene recursos de string para configuraciones regionales con el código de idioma es. De manera similar, mipmap-b+es+ES/ contiene íconos para configuraciones regionales con el código de idioma es y el código de país ES. Android carga los recursos correspondientes según la configuración regional del dispositivo durante el tiempo de ejecución. Para obtener más información, consulta Cómo proporcionar recursos alternativos.

Una vez que hayas decidido qué configuraciones regionales quieres admitir, crea los archivos y subdirectorios de recursos. Por ejemplo:

MyProject/
    res/
       values/
           strings.xml
       values-b+es/
           strings.xml
       mipmap/
           country_flag.png
       mipmap-b+es+ES/
           country_flag.png

Por ejemplo, a continuación, se muestran diferentes archivos de recursos para distintos idiomas:

Strings en inglés (configuración local predeterminada), /values/strings.xml:

<resources>
    <string name="hello_world">Hello World!</string>
</resources>

Strings en español (configuración regional es), /values-es/strings.xml:

<resources>
    <string name="hello_world">¡Hola Mundo!</string>
</resources>

Ícono de la bandera de Estados Unidos (configuración regional predeterminada), /mipmap/country_flag.png:

Figura 2: Ícono que se usa para la configuración regional predeterminada (en_US)

Ícono de la bandera de España (configuración regional es_ES), /mipmap-b+es+ES/country_flag.png:

Figura 3: Ícono que se usa para la configuración regional es_ES

Nota: Puedes usar el calificador de configuración regional (o cualquier calificador de configuración) en cualquier tipo de recurso, como lo harías si quisieras ofrecer versiones localizadas de elementos de diseño de tu mapa de bits. Para obtener más información, consulta Localización.

Cómo usar los recursos en tu app

Puedes hacer referencia a los recursos en el código fuente y otros archivos en formato XML mediante el atributo name de cada recurso.

En el código fuente, puedes hacer referencia a un recurso con la sintaxis R.<resource type>.<resource name>. Hay varios métodos que aceptan un recurso de esta manera.

Por ejemplo:

// Get a string resource from your app's Resources
val hello = resources.getString(R.string.hello_world)

// Or supply a string resource to a method that requires a string
TextView(this).apply {
    setText(R.string.hello_world)
}

// Get a string resource from your app's Resources
String hello = getResources().getString(R.string.hello_world);

// Or supply a string resource to a method that requires a string
TextView textView = new TextView(this);
textView.setText(R.string.hello_world);

En otros archivos en formato XML, puedes hacer referencia a un recurso con la sintaxis @<resource type>/<resource name> siempre que el atributo XML acepte un valor compatible.

Por ejemplo:

<ImageView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:src="@mipmap/country_flag" />

Importante: Para garantizar que la configuración de idioma del usuario tenga prioridad correcta, especifica los idiomas que admite tu app con la propiedad resConfigs. Para obtener más información, consulta Cómo especificar los idiomas que admite tu app.

Cómo dar formato al texto en mensajes

Una de las tareas más comunes que se llevan a cabo en una app es dar formato al texto. Para brindar un formato a los mensajes localizados, debes insertar los datos numéricos y de texto en las posiciones correspondientes. Cuando trabajas con una IU de derecha a izquierda o con datos de ese tipo, el formato simple puede mostrar una salida de texto incorrecta o incluso ilegible.

En general, los idiomas como el árabe, el hebreo, el persa y el urdú se escriben en dirección de derecha a izquierda. Sin embargo, algunos elementos de su alfabeto, como los números y el texto de izquierda a derecha incorporado, se escriben en dirección de izquierda a derecha dentro del texto configurado de derecha a izquierda. Los idiomas que usan alfabetos de izquierda a derecha, como el inglés, también son bidireccionales porque pueden contener escritura de derecha a izquierda incorporada que debe mostrarse en esa dirección.

La mayoría de las veces, las mismas apps generan esas instancias de texto incorporado en dirección opuesta. Estas insertan datos de texto de un idioma aleatorio (y en una dirección de texto aleatoria) en mensajes localizados. La mezcla de direcciones no suele indicar con claridad dónde empieza y termina el texto en la dirección opuesta. Por lo tanto, estas características del texto generado por la app a menudo son las más problemáticas.

Si bien el control predeterminado de texto bidireccional del sistema suele procesar el texto de la forma esperada, es posible que no suceda cuando tu app lo inserte en un mensaje localizado. A continuación, se presentan ejemplos de casos en los que es más probable que el texto no se muestre correctamente:

• Cuando se inserta al principio del mensaje:

  PERSON_NAME te está llamando

• Cuando comienza con un número, como las direcciones o los números de teléfono:

  987 654-3210

• Cuando comienza con signos de puntuación, como en un número de teléfono:

  +19876543210

• Cuando finaliza con signos de puntuación:

  ¿Seguro?

• Cuando ya incluye ambas direcciones:

  La palabra בננה significa banana en hebreo.

Ejemplo

Por ejemplo, supongamos que una app a veces necesita mostrar el mensaje "¿Quisiste decir %s?" con una dirección insertada en el lugar de %s durante el tiempo de ejecución. Como la app admite diferentes configuraciones regionales de IU, el mensaje surge de un recurso específico de la configuración regional y usa la dirección de derecha a izquierda cuando se usa una configuración regional de ese tipo. En el caso de una IU en hebreo, debería mostrarse de la siguiente manera:

האם התכוונת ל %s?

Sin embargo, es posible que la sugerencia provenga de una base de datos que no incluye texto en el idioma de la configuración regional. Por ejemplo, si la dirección en cuestión es para un lugar en California, esta aparece en la base de datos con texto en inglés. Si insertas la dirección "15 Bay Street, Laurel, CA" en el mensaje de derecha a izquierda sin proporcionar información sobre la dirección del texto, el resultado será incorrecto o inesperado:

האם התכוונת ל 15 Bay Street, Laurel, CA?

Observa que el número de la casa aparece del lado derecho de la dirección y no del izquierdo como se pretendía. Por lo tanto, parece un número de código postal extraño. Es posible que se produzca el mismo problema si incluyes texto de derecha a izquierda en un mensaje que usa la dirección de texto de izquierda a derecha.

Explicación y solución

El problema del ejemplo anterior se produce porque el formateador de texto no especifica que "15" forma parte de la dirección, de manera que el sistema no puede determinar si "15" es parte del texto de derecha a izquierda que lo precede o del texto de izquierda a derecha que lo sucede.

Para resolver este problema, usa el método unicodeWrap(), que se encuentra en la clase BidiFormatter, en cada fragmento de texto que insertes en el mensaje localizado. Estos son algunos casos en los que no debes usar unicodeWrap():

• Cuando el texto se inserta en una string legible por máquina, como un URI o una consulta de SQL.
• Cuando sabes que ese fragmento de texto ya está unido correctamente.

El método unicodeWrap() detecta la dirección de una string y la une en caracteres con formato Unicode que declaran esa dirección. Como "15" ahora aparece dentro del texto que se declaró como de izquierda a derecha, se muestra en la posición correcta:

האם התכוונת ל 15 Bay Street, Laurel, CA?

En el siguiente fragmento de código, se muestra cómo usar unicodeWrap():

val mySuggestion = "15 Bay Street, Laurel, CA"
val myBidiFormatter: BidiFormatter = BidiFormatter.getInstance()

// The "did_you_mean" localized string resource includes
// a "%s" placeholder for the suggestion.
String.format(getString(R.string.did_you_mean), myBidiFormatter.unicodeWrap(mySuggestion))

String mySuggestion = "15 Bay Street, Laurel, CA";
BidiFormatter myBidiFormatter = BidiFormatter.getInstance();

// The "did_you_mean" localized string resource includes
// a "%s" placeholder for the suggestion.
String.format(getString(R.string.did_you_mean),
        myBidiFormatter.unicodeWrap(mySuggestion));

Nota: Si tu app se orienta a Android 4.3 (nivel de API 18) o versiones posteriores, usa la versión de BidiFormatter que se encuentra en el framework de Android. De lo contrario, usa la versión de BidiFormatter que se encuentra en la biblioteca de compatibilidad.

Cómo dar formato a los números

Para convertir los números en strings en la lógica de tu app, usa strings de formato y no llamadas a métodos:

var myIntAsString = "$myInt"

String myIntAsString = String.format("%d", myInt);

De esta manera, se asignará el formato correcto a los números para tu configuración regional, lo que podría implicar el uso de un conjunto de dígitos diferente.

Cuando usas String.format() para crear una consulta en SQL en un dispositivo cuya configuración regional usa su propio conjunto de dígitos (como la configuración regional del persa y la mayoría de las del árabe), podrías tener problemas si alguno de los parámetros de la consulta consiste en números. Esto se debe a que a los números se les asigna el formato de los dígitos de la configuración regional, que no son válidos en SQL.

Para mantener los números con formato ASCII y que la consulta de SQL siga siendo válida, debes usar la versión sobrecargada de String.format() que incluye una configuración regional como primer parámetro. El argumento de configuración regional debe ser Locale.US.

Compatibilidad con duplicación de diseño

Los usuarios que usan el alfabeto de derecha a izquierda prefieren una interfaz de usuario de ese tipo, que incluye texto y menús alineados a la derecha, y flechas para avanzar que apuntan hacia la izquierda.

En la figura 4, se muestra la comparación entre la versión de izquierda a derecha de una pantalla en la app de Configuración y su equivalente de derecha a izquierda.

Cuando agregas compatibilidad con la escritura de derecha a izquierda en tu app, es importante que tengas en cuenta lo siguiente:

• La duplicación de texto de derecha a izquierda solo se admite en apps que se ejecutan en dispositivos con Android 4.2 (nivel de API 17) o versiones posteriores. Para obtener más información sobre cómo agregar compatibilidad con la duplicación de texto en dispositivos anteriores, consulta Cómo proporcionar compatibilidad con apps heredadas.
• A fin de probar si tu app admite una dirección de texto de derecha a izquierda, utiliza las Opciones para desarrolladores e invita a usuarios que usan alfabetos de derecha a izquierda a que usen tu app.

Nota: Para ver lineamientos de diseño adicionales relacionados con la duplicación de diseño, incluida una lista de los elementos que deben duplicarse y los que no, consulta los lineamientos de material design sobre el diseño bidireccional.

Para duplicar el diseño de la IU en tu app de manera que aparezca la escritura de derecha a izquierda en una configuración regional de ese tipo, completa los pasos de las siguientes secciones.

Cómo modificar los archivos de manifiesto y de compilación

Puedes modificar el archivo build.gradle del módulo de tu app y el archivo de manifiesto de la app de la siguiente manera:

build.gradle (módulo: app)

android {
    ...
    defaultConfig {
        targetSdkVersion 17 // Or higher
        ...
    }
}

android {
    ...
    defaultConfig {
        targetSdkVersion(17) // Or higher
        ...
    }
}

AndroidManifest.xml

<manifest ... >
    ...
    <application ...
        android:supportsRtl="true">
    </application>
</manifest>

Nota: Si tu app se orienta a Android 4.1.1 (nivel de API 16) o versiones anteriores, se omite el atributo android:supportsRtl junto con cualquier otro valor de atributo start y end que aparezca en los archivos de diseño de la app. En este caso, la duplicación de diseño de derecha a izquierda no se realiza automáticamente.

Cómo actualizar recursos existentes

Convierte left y right en start y end, respectivamente, en cada uno de los archivos de recursos de diseño existentes. Al hacerlo, permites que el framework alinee los elementos de la IU de tu app en función de la configuración de idioma del usuario.

Nota: Antes de actualizar tus recursos, obtén más información para proporcionar compatibilidad con apps heredadas o apps que se orientan a Android 4.1.1 (nivel de API 16) y versiones anteriores.

Para usar las capacidades de alineación de derecha a izquierda del framework, cambia los atributos en los archivos de diseño que aparecen en la tabla 1.

Tabla 1: Atributos para usar cuando tu app sea compatible con varias direcciones de texto

En la tabla 2, se muestra cómo el sistema procesa los atributos de alineación de IU en función de la versión del SDK de destino y de si se definieron los atributos left y right, así como start y end.

Tabla 2: Comportamiento de la alineación de elementos de la IU en función de la versión del SDK de destino y los atributos definidos

Cómo agregar recursos específicos de idioma y dirección

Este paso consiste en agregar versiones específicas del diseño, los elementos de diseño y los archivos de recursos de valores que contienen valores personalizados para diferentes idiomas y direcciones de texto.

En Android 4.2 (nivel de API 17) y versiones posteriores, puedes usar los calificadores de recursos -ldrtl (dirección-de-diseño-de-derecha-a-izquierda) y -ldltr (dirección-de-diseño-de-izquierda-a-derecha). Para conservar la retrocompatibilidad con la carga de recursos existentes, las versiones anteriores de Android usan los calificadores idioma de un recurso a fin de inferir la dirección de texto correcta.

Supongamos que quieres agregar un archivo de diseño específico para admitir alfabetos de derecha a izquierda, como los idiomas hebreo, árabe y persa. Para ello, agregas un directorio layout-ldrtl/ en res/, como se muestra en el siguiente ejemplo:

res/
    layout/
        main.xml This layout file is loaded by default.
    layout-ldrtl/
        main.xml This layout file is loaded for languages using an
                 RTL text direction, including Arabic, Persian, and Hebrew.

Si quieres agregar una versión específica del diseño creada únicamente para texto en árabe, la estructura de tu directorio se verá de la siguiente manera:

res/
    layout/
        main.xml This layout file is loaded by default.
    layout-ar/
        main.xml This layout file is loaded for Arabic text.
    layout-ldrtl/
        main.xml This layout file is loaded only for non-Arabic
                 languages that use an RTL text direction.

Nota: Los recursos específicos de idioma prevalecen sobre los recursos específicos de la dirección del diseño, los cuales prevalecen sobre los recursos predeterminados.

Cómo usar widgets compatibles

A partir de Android 4.2 (nivel de API 17), la mayoría de los elementos de la IU del framework admiten automáticamente la dirección de texto de derecha a izquierda. Sin embargo, muchos elementos del framework, como ViewPager, no la admiten.

Los widgets de la pantalla principal admiten la dirección de texto de derecha a izquierda siempre y cuando sus archivos de manifiesto correspondientes incluyan la asignación de atributo android:supportsRtl="true".

Cómo proporcionar compatibilidad con apps heredadas

Si tu app se orienta a Android 4.1.1 (nivel de API 16) o versiones anteriores, también debes incluir los atributos left y right, además de start y end.

Para comprobar si tu diseño debe usar la dirección de texto de derecha a izquierda, usa la siguiente lógica:

private fun shouldUseLayoutRtl(): Boolean {
    return if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.JELLY_BEAN_MR1) {
        View.LAYOUT_DIRECTION_RTL == layoutDirection
    } else {
        false
    }
}

private boolean shouldUseLayoutRtl() {
    if (android.os.Build.VERSION.SDK_INT >=
            android.os.Build.VERSION_CODES.JELLY_BEAN_MR1) {
        return View.LAYOUT_DIRECTION_RTL == getLayoutDirection();
    } else {
        return false;
    }
}

Nota: Para evitar problemas de compatibilidad, usa la versión 23.0.1 o versiones posteriores de las Herramientas de desarrollo del SDK de Android.

Cómo realizar pruebas con las Opciones para desarrolladores

En dispositivos que ejecutan Android 4.4 (nivel de API 19) o versiones posteriores, puedes habilitar la función Forzar diseño der. a izq. en las Opciones para desarrolladores en el dispositivo. Esta configuración te permite ver el texto que usa alfabetos de izquierda a derecha (como texto en inglés) en el modo de derecha a izquierda.

Cómo actualizar la lógica de la app

En esta sección, se describen los lugares específicos de la lógica de tu app que debes actualizar cuando la adaptas para controlar varias direcciones de texto.

Cambios en las propiedades

Para controlar un cambio en una propiedad relacionada con la dirección de derecha a izquierda (como la dirección del diseño o texto, los parámetros del diseño, el padding, la alineación del texto o el posicionamiento de los elementos de diseño), puedes usar la devolución de llamada onRtlPropertiesChanged(). Esta te permite obtener la dirección de diseño actual y actualizar los objetos View de la actividad según corresponda.

Vistas

Si quieres crear un widget de IU que no es una parte directa de la jerarquía de vistas de una actividad, como un diálogo o un elemento de la IU similar a un aviso, debes establecer la dirección de diseño correcta en función del contexto. En el siguiente fragmento de código, se muestra cómo completar este proceso:

val config: Configuration = context.resources.configuration
view.layoutDirection = config.layoutDirection

final Configuration config =
    getContext().getResources().getConfiguration();
view.setLayoutDirection(config.getLayoutDirection());

Muchos métodos de la clase View requieren consideraciones adicionales:

onMeasure()

Las mediciones de vistas pueden variar en función de la dirección del texto.

onLayout()

Si creas tu propia implementación de diseño, deberás llamar a super() en tu versión de onLayout() y adaptar tu lógica personalizada para que admita alfabetos de derecha a izquierda.

onDraw()

Si quieres implementar una vista personalizada o agregar funcionalidades avanzadas a un dibujo, deberás actualizar tu código para que admita alfabetos de derecha a izquierda. Usa el siguiente código para determinar si tu widget está en modo de derecha a izquierda:

Kotlin

// On devices running Android 4.1.1 (API level 16) and lower,
// you can call the isLayoutRtl() system method directly.
fun isLayoutRtl(): Boolean = layoutDirection == LAYOUT_DIRECTION_RTL

Java

// On devices running Android 4.1.1 (API level 16) and lower,
// you can call the isLayoutRtl() system method directly.
public boolean isLayoutRtl() {
    return (getLayoutDirection() == LAYOUT_DIRECTION_RTL);
}

Elementos de diseño

Si tienes un elemento de diseño que necesita duplicarse para un diseño de derecha a izquierda, completa uno de estos pasos en función de la versión de Android que se ejecuta en el dispositivo:

• En dispositivos que ejecutan Android 4.3 (nivel de API 18) o versiones anteriores, debes agregar y definir los archivos de recursos -ldrtl.

• En Android 4.4 (nivel de API 19) o versiones posteriores, puedes usar android:autoMirrored="true" cuando definas tu elemento de diseño, que le permitirá al sistema controlar la duplicación del diseño de derecha a izquierda por ti.

  Nota: El atributo android:autoMirrored solo funciona para elementos de diseño sencillos cuya duplicación bidireccional es simplemente una duplicación gráfica de todo el elemento de diseño. Si tu elemento de diseño contiene varios elementos o si al reflejarlo se cambia su interpretación, tendrás que realizar la duplicación por tu cuenta. Siempre que sea posible, consulta a un experto en diseño bidireccional para determinar si los usuarios pueden comprender tus elementos de diseño duplicados.

Gravedad

Si el código de tu app usa Gravity.LEFT o Gravity.RIGHT, tendrás que cambiar estos valores a Gravity.START y Gravity.END, respectivamente.

Por ejemplo, si usas el siguiente código:

when (gravity and Gravity.HORIZONTAL_GRAVITY_MASK) {
    Gravity.LEFT -> {
        // Handle objects that are left-aligned.
    }
    Gravity.RIGHT -> {
        // Handle objects that are right-aligned.
    }
}

switch (gravity & Gravity.HORIZONTAL_GRAVITY_MASK) {
    case Gravity.LEFT:
        // Handle objects that are left-aligned.
        break;
    case Gravity.RIGHT:
        // Handle objects that are right-aligned.
        break;
}

Deberás modificarlo de la siguiente manera:

val absoluteGravity: Int = Gravity.getAbsoluteGravity(gravity, layoutDirection)
when (absoluteGravity and Gravity.HORIZONTAL_GRAVITY_MASK) {
    Gravity.LEFT -> {
        // Handle objects that are left-aligned.
    }
    Gravity.RIGHT -> {
        // Handle objects that are right-aligned.
    }
}

final int layoutDirection = getLayoutDirection();
final int absoluteGravity =
        Gravity.getAbsoluteGravity(gravity, layoutDirection);
switch (absoluteGravity & Gravity.HORIZONTAL_GRAVITY_MASK) {
    case Gravity.LEFT:
        // Handle objects that are left-aligned.
        break;
    case Gravity.RIGHT:
        // Handle objects that are right-aligned.
        break;
}

De esta manera, puedes conservar el código existente que controla los valores alineados a la izquierda y a la derecha, incluso si usas start y end para tus valores de gravedad.

Nota: Cuando apliques tu configuración de gravedad, usa una versión sobrecargada de Gravity.apply() que incluya un argumento layoutDirection.

Margen y padding

Para admitir alfabetos de derecha a izquierda en tu app, sigue las prácticas recomendadas relacionadas con los valores de margen y padding:

• Usa getMarginStart() y getMarginEnd() en lugar de los equivalentes de atributos específicos de dirección leftMargin y rightMargin.
• Cuando uses setMargins(), intercambia los valores de los argumentos left y right si tu app detecta alfabetos de derecha a izquierda.
• Si la app incluye una lógica de padding personalizada, anula setPadding() y setPaddingRelative().

Consulta también

• Lista de tareas para la localización
• Localización con recursos
• Servicio de traducción de apps

Recursos adicionales

Para obtener información adicional sobre la compatibilidad con dispositivos más antiguos, consulta los siguientes recursos:

Entradas de blog

• A fin de que las apps sean accesibles, brinda compatibilidad con diferentes dispositivos
• Cómo escribir para públicos globales