Usar localizaciones y códigos de idioma en el SDK de Android

Por qué esto es importante

Los códigos de idioma entran en juego cuando Adapty elige la localización para un flow y cuando lees un Remote Config para un paywall personalizado.

Los códigos de idioma son complejos y pueden variar de una plataforma a otra, por lo que Adapty utiliza un estándar interno único para todas las plataformas que admite. Entender ese estándar te ayuda a predecir qué localización recibirá un usuario.

Estándar de códigos de idioma en Adapty

Para los códigos de idioma, Adapty utiliza una versión ligeramente modificada del estándar BCP 47: cada código se compone de subetiquetas en minúsculas separadas por guiones. Algunos ejemplos: en (inglés), pt-br (portugués de Brasil), zh (chino simplificado), zh-hant (chino tradicional).

Coincidencia de códigos de idioma

Cuando Adapty busca la localización que coincide con el idioma del usuario, ocurre lo siguiente:

1. La cadena de idioma se convierte a minúsculas y todos los guiones bajos (_) se reemplazan por guiones (-)
2. Adapty busca la localización con el código de idioma que coincida exactamente
3. Si no encuentra coincidencia, Adapty toma la subcadena antes del primer guión (pt para pt-br) y busca la localización correspondiente
4. Si tampoco encuentra coincidencia, Adapty devuelve el contenido del idioma predeterminado del flow

Esta forma hace que 'pt_BR', pt-BR y pt-br se resuelvan a la misma localización.

Implementación de localizaciones

En SDK v4, no necesitas pasar un código de idioma al obtener un flow — getFlow devuelve el flow con todas sus localizaciones.

• Flows creados en el builder: el SDK no lee el idioma del dispositivo, así que resuélvelo en tu app y pásalo como argumento locale de AdaptyUI.getFlowConfiguration. El argumento es opcional — omítelo y el flow se renderizará en en, o en su idioma predeterminado si el flow no tiene localización en en. Si solicitas una localización que el flow no tiene, la vista usa el idioma predeterminado del flow sin mostrar ningún error, y las cadenas que falten en la localización elegida se tomarán de la predeterminada.

Rendering en en por defecto requiere Android SDK 4.0.1. En 4.0.0, omitir locale renderiza la localización predeterminada del flow.

• Paywalls personalizados (Remote Config): getFlow devuelve todas las localizaciones configuradas en flow.remoteConfigs. Cada entrada tiene un código locale y el contenido de la configuración (jsonString o el dataMap parseado). Selecciona la entrada que corresponda al usuario, con tu propio fallback:

Adapty.getFlow("YOUR_PLACEMENT_ID") { result ->
    when (result) {
        is AdaptyResult.Success -> {
            val flow = result.value
            val config = flow.remoteConfigs.firstOrNull { it.locale == "en" }
                ?: flow.remoteConfigs.firstOrNull()
            // read your values from config?.dataMap
        }
        is AdaptyResult.Error -> {
            // handle the error
        }
    }
}

Las reglas de coincidencia de códigos de idioma descritas arriba explican cómo Adapty normaliza los códigos locale almacenados en cada Remote Config.

Por qué esto es importante

Hay algunos escenarios en los que los códigos de idioma entran en juego; por ejemplo, cuando intentas obtener el paywall correcto para la localización actual de tu app.

Como los códigos de idioma son complejos y pueden variar de una plataforma a otra, nos basamos en un estándar interno para todas las plataformas que soportamos. Sin embargo, precisamente por esa complejidad, es muy importante que entiendas qué estás enviando exactamente a nuestro servidor para obtener la localización correcta y qué ocurre después, para que siempre recibas lo que esperas.

Estándar de códigos de idioma en Adapty

Para los códigos de idioma, Adapty utiliza una versión ligeramente modificada del estándar BCP 47: cada código se compone de subetiquetas en minúsculas separadas por guiones. Algunos ejemplos: en (inglés), pt-br (portugués (Brasil)), zh (chino simplificado), zh-hant (chino tradicional).

Coincidencia de código de idioma

Cuando Adapty recibe una llamada del SDK con el código de idioma y comienza a buscar la localización correspondiente de un paywall, ocurre lo siguiente:

1. La cadena de idioma entrante se convierte a minúsculas y todos los guiones bajos (_) se reemplazan por guiones (-)
2. A continuación, buscamos la localización con el código de idioma que coincida exactamente
3. Si no se encuentra ninguna coincidencia, tomamos la subcadena antes del primer guión (pt para pt-br) y buscamos la localización correspondiente
4. Si tampoco se encuentra ninguna coincidencia, devolvemos el contenido del idioma predeterminado del paywall

De este modo, un dispositivo iOS que envíe 'pt_BR', un dispositivo Android que envíe pt-BR y otro dispositivo que envíe pt-br obtendrán el mismo resultado.

Implementar localizaciones: la forma recomendada

Si te estás preguntando sobre las localizaciones, probablemente ya estés trabajando con los archivos de cadenas localizadas de tu proyecto. En ese caso, te recomendamos añadir un par clave-valor con el código de idioma de Adapty correspondiente en cada uno de esos archivos. Luego, extrae el valor de esa clave al llamar a nuestro SDK, así:

// 1. Modify your strings.xml files

/*
strings.xml - Spanish
*/
<string name="adapty_paywalls_locale">es</string>

/*
strings.xml - Portuguese (Brazil)
*/
<string name="adapty_paywalls_locale">pt-br</string>

// 2. Extract and use the locale code

val localeCode = context.getString(R.string.adapty_paywalls_locale)
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

Así te aseguras de tener un control total sobre qué localización se recuperará para cada usuario de tu app.

Implementar localizaciones: la otra forma

Puedes obtener resultados similares (aunque no idénticos) sin definir explícitamente códigos de idioma para cada localización. Esto implica extraer el código de idioma de otros objetos que proporciona tu plataforma, así:

val locale = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N)
    context.resources.configuration.locales[0]
else
    context.resources.configuration.locale

val localeCode = locale.toLanguageTag()
// pass locale code to AdaptyUI.getViewConfiguration or Adapty.getPaywall method

Ten en cuenta que no recomendamos este enfoque, ya que es difícil predecir exactamente qué recibirá el servidor de Adapty.

Si decides utilizarlo de todas formas, asegúrate de haber cubierto todos los casos de uso relevantes.