在 React Native SDK 中使用本地化和语言代码

为什么这很重要

当 Adapty 为流程或用户引导选择本地化内容时，以及当你为自定义付费墙读取远程配置时，都会用到语言区域代码。

语言区域代码比较复杂，不同平台之间可能存在差异，因此 Adapty 在其支持的所有平台上统一采用一套内部标准。了解这套标准有助于你预测用户将获得哪种本地化内容。

Adapty 中的语言代码标准

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

语言代码匹配

在 SDK v4 中，流程和用户引导的语言代码匹配方式不同：流程由 SDK 在设备端进行本地化，用户引导则由 Adapty 服务器进行本地化。

流程与付费墙编辑工具付费墙

在 SDK v4 中，通过付费墙编辑工具构建的付费墙以流程的形式交付，因此以下规则同时适用于两者。

匹配规则为精确匹配。SDK 会逐字符地将你传入的代码与流程的本地化代码进行比较：不会转换大小写，不会将下划线（_）替换为连字符（-），也不会回退到语言子标签。对于包含 pt-br 本地化的流程，只有 pt-br 能匹配：pt-BR、pt_BR 和 pt-PT 均无法匹配。

当代码与任何本地化均不匹配时，流程会静默地以其默认语言渲染——SDK 不会返回错误，也不会记录警告。

当代码匹配时，Adapty 会将该本地化与默认本地化合并：匹配的本地化中未定义的字符串和资源将从默认本地化中获取。

省略语言区域代码并不等同于请求流程的默认本地化：SDK 会固定替换为 en。如果一个流程的默认语言区域是 de，但该流程存在 en 本地化版本，仍会以 en 渲染；只有当不存在 en 本地化版本时，才会回退到 de。

用户引导

用户引导在服务端进行本地化，服务端规则兼容多种格式。当你向 getOnboarding 传入 locale 时：

1. locale 字符串会被转换为小写，并将所有下划线（_）替换为连字符（-）
2. Adapty 查找与完整 locale 代码完全匹配的本地化版本
3. 若未找到匹配项，Adapty 取第一个连字符之前的子字符串（例如 pt-br 取 pt），再次查找匹配的本地化版本
4. 若仍未找到匹配项，Adapty 返回该用户引导默认 locale 对应的内容

这样一来，pt_BR、pt-BR 和 pt-br 都会解析到同一个用户引导的本地化内容。

实现本地化

在 SDK v4 中，获取流程时无需传入语言区域代码——getFlow 会返回包含所有本地化内容的流程，Adapty 在构建流程视图时会自动应用其中一个。

• 在编辑工具中构建的流程：SDK 不会读取设备语言环境，请在应用中自行解析并通过 createFlowView 的 locale 参数传入，或在嵌入式 AdaptyFlowView 组件的 params 属性中传入。该参数为可选项——若省略，流程将以 en 渲染；若流程没有 en 本地化版本，则以其默认语言环境渲染。

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

view.locale 会反映视图实际使用的本地化语言——如果请求的语言存在，则使用你所请求的语言；否则回退到该流程的默认语言。locale 参数和 view.locale 均需要 React Native SDK 4.0.2 或更高版本，在更早版本中 view.locale 为 undefined。

嵌入式 AdaptyFlowView 组件会自行创建视图，因此你的代码无法从中读取 locale。请改为从其 onAppeared 处理器接收到的对象中获取本地化信息：

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

onAppeared 参数需要 React Native SDK 4.0.3 或更高版本。

• 自定义（远程配置）付费墙：getFlow 会在 flow.remoteConfigs 中返回所有已配置的本地化内容。每个条目包含一个 lang 语言代码和一个 data 对象。请自行选择与用户匹配的条目，并添加你自己的回退逻辑：

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 将 lang 代码存储为 Adapty 语言代码标准 中描述的格式。SDK 不会将远程配置与语言区域自动匹配，因此具体使用哪条配置由你的应用自行决定。

为什么这很重要

有几种场景会用到语言区域代码——例如，当你需要为应用的当前语言版本获取正确的付费墙时。

由于语言区域代码较为复杂，且在不同平台之间可能存在差异，我们为所有支持的平台制定了统一的内部标准。但正因为这些代码比较复杂，了解你实际发送给服务器的内容是什么、以及后续处理流程如何，就显得尤为重要——只有这样，你才能始终获取到预期的语言版本。

Adapty 的语言代码标准

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

语言区域代码匹配

当 Adapty 收到客户端 SDK 的调用（包含语言区域代码）并开始查找对应的付费墙本地化内容时，会按以下步骤执行：

1. 传入的语言区域字符串转换为小写，并将所有下划线（_）替换为连字符（-）
2. 查找与完整语言区域代码完全匹配的本地化内容
3. 如果未找到匹配项，则截取第一个连字符前的子字符串（例如 pt-br 取 pt），再次查找匹配的本地化内容
4. 如果仍未找到匹配项，则返回该付费墙默认语言区域的内容

这样，发送 '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);
};

请注意，由于以下几个原因，我们不推荐使用这种方式：

1. 在 iOS 上，首选语言与当前区域语言环境并不相同。如果想让本地化正确匹配，要么依赖 Apple 的解析逻辑——使用推荐的本地化字符串文件方式时开箱即用——要么自行实现同样的逻辑。
2. 设备语言环境可能与你在 Adapty 中配置的任何本地化都不匹配。在这种情况下，SDK 会回退到语言标签前缀匹配，若仍无匹配则最终回退到 en——但这未必是你希望为该用户显示的默认语言。 Should you decide to use this approach anyway — make sure you’ve covered all the relevant use cases.