在 React Native SDK 中使用本地化和区域代码

为什么这很重要

区域代码会在多种场景下发挥作用——例如，当你需要根据应用的当前本地化设置获取对应的付费墙时。

由于区域代码较为复杂，且在不同平台之间可能存在差异，我们为所有支持的平台制定了统一的内部标准。正因为这些代码比较复杂，理解你向服务器发送的具体内容以及后续处理流程就显得尤为重要——这样才能确保你始终获取到预期的本地化结果。

Adapty 的区域代码标准

Adapty 使用经过略微修改的 BCP 47 标准：每个代码由小写子标签组成，以连字符分隔。例如：en（英语）、pt-br（葡萄牙语（巴西））、zh（简体中文）、zh-hant（繁体中文）。

区域代码匹配

当 Adapty 收到客户端 SDK 发来的区域代码请求并开始查找付费墙对应本地化版本时，处理流程如下：

传入的区域字符串转换为小写，所有下划线（_）替换为连字符（-）
查找区域代码完全匹配的本地化版本
若未找到匹配，截取第一个连字符前的子字符串（如 pt-br 取 pt），再次查找
若仍未找到，返回默认的 en 本地化版本

这样一来，发送 'pt_BR' 的 iOS 设备、发送 pt-BR 的 Android 设备以及发送 pt-br 的其他设备，都会获得相同的结果。

实现本地化：推荐方式

如果你在考虑本地化问题，很可能已经在项目中使用本地化字符串文件了。在这种情况下，我们建议在每个本地化文件中加入一个键值对，用于存储对应的 Adapty 区域代码。然后在调用 SDK 时提取该键对应的值，示例如下：

// 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);
  };
};

通过这种方式，你可以完全掌控每位用户获取的本地化版本。

实现本地化：其他方式

你也可以在不为每种本地化显式定义区域代码的情况下获得类似（但并不完全相同）的效果。这需要从设备中提取区域代码，例如通过 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);
};

我们不推荐这种方式，原因如下：

在 iOS 上，首选语言与当前地区设置并不相同。如果希望正确识别本地化，你要么依赖 Apple 的解析逻辑——使用推荐的本地化字符串文件方式时这会自动生效——要么自行重新实现该逻辑。
设备区域可能与你在 Adapty 中配置的本地化版本不匹配。此时 SDK 会回退到子标签匹配，或最终回退到 en——而这可能并不是你希望该用户看到的默认语言。

如果你仍决定使用这种方式，请确保已覆盖所有相关使用场景。