Usa localizaciones y códigos de idioma en el SDK de React Native

Por qué esto es importante

Los códigos de idioma entran en juego cuando Adapty elige la localización para un flow o un onboarding, 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á cada 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 está formado por 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ódigos de localización

En SDK v4, los flows y los onboardings hacen coincidir los códigos de localización de forma diferente: los flows se localizan mediante el SDK en el dispositivo, y los onboardings mediante el servidor de Adapty.

Flows y paywalls

Un paywall que Adapty renderiza se entrega como un flow en el SDK v4, por lo que la regla siguiente aplica a ambos.

La coincidencia es exacta. El SDK compara el código que pasas con los códigos de localización del flow carácter a carácter: no cambia las mayúsculas/minúsculas, no reemplaza guiones bajos (_) por guiones (-) y no recurre a la subetiqueta de idioma. Para un flow con una localización pt-br, solo pt-br coincide: pt-BR, pt_BR y pt-PT no coinciden.

Cuando el código no coincide con ninguna localización, el flow se renderiza silenciosamente en su localización predeterminada: el SDK no devuelve un error ni registra ninguna advertencia.

Cuando el código coincide, Adapty fusiona la localización con la predeterminada: las cadenas y recursos que no estén definidos en la localización encontrada se toman de la localización predeterminada.

Omitir el código de idioma no equivale a solicitar la localización predeterminada del flow: el SDK sustituye un en fijo. Un flow cuya localización predeterminada es de se seguirá renderizando en en si tiene una localización en, y solo recurrirá a de cuando no la tenga.

Onboardings

Los onboardings se localizan en el servidor, y las reglas del servidor toleran otros formatos. Cuando pasas un locale a getOnboarding:

1. La cadena de locale 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 locale que coincida exactamente
3. Si no se encuentra ninguna coincidencia, Adapty toma la subcadena anterior al primer guión (pt para pt-br) y busca la localización correspondiente
4. Si tampoco se encuentra ninguna coincidencia, Adapty devuelve el contenido para el locale predeterminado del onboarding

Esta forma, pt_BR, pt-BR y pt-br se resuelven todas en la misma localización del onboarding.

Implementación de localizaciones

En el SDK v4, no se pasa un código de idioma al obtener un flow — getFlow devuelve el flow con todas sus localizaciones, y Adapty aplica una cuando se construye la vista del flow.

• Flows creados en el builder: el SDK no lee el idioma del dispositivo, así que resuélvelo en tu app y pásalo como parámetro locale de createFlowView, o en la prop params del componente AdaptyFlowView embebido. Es opcional — si lo omites, el flow se renderiza en en, o en su idioma predeterminado cuando el flow no tiene localización en en.

  import { createFlowView } from 'react-native-adapty';
  
  const view = await createFlowView(flow, { locale: 'es' });

view.locale indica la localización con la que se construyó realmente la vista: la que pediste si esa localización existe, o la predeterminada del flow en caso contrario. Tanto el parámetro locale como view.locale requieren React Native SDK 4.0.2 o posterior, y view.locale es undefined en versiones anteriores.

El componente AdaptyFlowView integrado crea su propia vista, por lo que tu código no tiene ningún objeto del que leer locale. En su lugar, obtén la localización del objeto que recibe su manejador onAppeared:

  <AdaptyFlowView
    flow={flow}
    params={{ locale: 'es' }}
    onAppeared={(view) => setScreenLocale(view.locale)}
  />

El argumento onAppeared requiere React Native SDK 4.0.3 o posterior.

• Paywalls personalizados (remote config): getFlow devuelve todas las localizaciones configuradas en flow.remoteConfigs. Cada entrada tiene un código lang y un objeto data. Selecciona la entrada que corresponda al usuario, con tu propio fallback:

const flow = await adapty.getFlow('placement_id');
const config = flow.remoteConfigs?.find((c) => c.lang === 'en') ?? flow.remoteConfigs?.[0];
// read your values from config?.data

Adapty almacena esos códigos lang en el formato descrito en Estándar de código de idioma en Adapty. El SDK no compara los Remote Configs con un idioma, así que tu app es quien decide qué entrada aplicar.

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 exactamente qué estás enviando a nuestro servidor para obtener la localización correcta y qué ocurre a continuación, de modo 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 consiste en 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ódigos de idioma

Cuando Adapty recibe una llamada del SDK del cliente 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, se busca la localización con el código de idioma que coincida exactamente
3. Si no se encuentra ninguna coincidencia, se toma la subcadena antes del primer guión (pt para pt-br) y se busca la localización coincidente
4. Si tampoco se encuentra ninguna coincidencia, se devuelve el contenido con el 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.

Implementación de localizaciones: método recomendado

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

// 1. Modify your localization files (e.g., using react-i18next)

/*
en.json
*/
{
  "adapty_paywalls_locale": "en"
}

/*
es.json
*/
{
  "adapty_paywalls_locale": "es"
}

/*
pt-BR.json
*/
{
  "adapty_paywalls_locale": "pt-br"
}

// 2. Extract and use the locale code

const MyComponent = () => {
  const { t } = useTranslation();
  
  const fetchPaywall = async () => {
    const locale = t('adapty_paywalls_locale');
    // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
    const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
  };
};

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

Implementando localizaciones: otra alternativa

Puedes obtener resultados similares (aunque no idénticos) sin definir explícitamente los códigos de idioma para cada localización. Esto implica extraer el código de idioma del dispositivo, por ejemplo mediante react-native-localize:

const fetchPaywall = async () => {
  // getLocales() returns the user's preferred locales in BCP-47 format (e.g., 'en-US', 'pt-BR')
  const locale = RNLocalize.getLocales()[0].languageTag;
  // pass locale code to adapty.getPaywall or adapty.getPaywallForDefaultAudience method
  const paywall = await adapty.getPaywallForDefaultAudience('placement_id', locale);
};

Ten en cuenta que no recomendamos este enfoque por varias razones:

1. En iOS, los idiomas preferidos y la configuración regional actual no son idénticos. Si quieres que la localización se seleccione correctamente, tendrás que basarte en la lógica de resolución de Apple —que funciona de forma predeterminada cuando usas el enfoque recomendado con archivos de cadenas localizadas— o recrearla tú mismo.
2. La configuración regional del dispositivo puede no coincidir con ninguna localización que hayas configurado en Adapty. En ese caso, el SDK recurre a la coincidencia del primer subtag o, en última instancia, a en —que puede no ser el idioma que quieras mostrar por defecto a ese usuario.

Should you decide to use this approach anyway — make sure you’ve covered all the relevant use cases.