Setting a Locale

Override the default device locale when using the Expo SDK so you can preview localized paywalls and targeting.

Overview

The Expo SDK automatically uses the device's locale to localize paywalls and evaluate campaign rules. Override the locale with the localeIdentifier option when you need to:

preview translations without changing the simulator or device settings
QA rules that gate content by market or language
capture store screenshots or marketing assets in a specific language

localeIdentifier accepts standard BCP‑47 identifiers such as en_US, en_GB, or fr_CA. You can reference Apple's complete locale list if you need the exact identifier for a region.

Set the locale before Superwall config

<SuperwallProvider /> configures the native SDK only once, so be sure the locale you want to test is decided before the provider mounts.

import { SuperwallProvider, type PartialSuperwallOptions } from "expo-superwall";

const localeOptions: PartialSuperwallOptions = {
  localeIdentifier: "fr_FR",
};

export default function App() {
  return (
    <SuperwallProvider
      apiKeys={{
        ios: process.env.EXPO_PUBLIC_SUPERWALL_IOS_KEY!,
        android: process.env.EXPO_PUBLIC_SUPERWALL_ANDROID_KEY!,
      }}
      options={localeOptions}
    >
      <RootNavigator />
    </SuperwallProvider>
  );
}

Verify the active locale

Use useSuperwall() and getDeviceAttributes() to confirm which locale the native SDK currently sees. This is helpful when debugging targeting issues.

import { useEffect } from "react";
import { useSuperwall } from "expo-superwall";

export function LocaleDebug() {
  const superwall = useSuperwall();

  useEffect(() => {
    superwall.getDeviceAttributes().then((attrs) => {
      console.log("[Superwall] localeIdentifier:", attrs.localeIdentifier);
    });
  }, [superwall]);

  return null;
}

Change the locale at runtime

After configuration, use setLocaleIdentifier() to change the locale without configuring Superwall again. Pass null to restore the device locale.

With the hooks API:

import { Button } from "react-native";
import { useSuperwall } from "expo-superwall";

function LocaleControls() {
  const { setLocaleIdentifier } = useSuperwall();

  return (
    <>
      <Button title="Show Spanish" onPress={() => setLocaleIdentifier("es_ES")} />
      <Button title="Use device locale" onPress={() => setLocaleIdentifier(null)} />
    </>
  );
}

With the compat API, call the method on the instance returned by Superwall.configure():

import Superwall from "expo-superwall/compat";

const superwall = await Superwall.configure({ apiKey: "YOUR_API_KEY" });
await superwall.setLocaleIdentifier("es_ES");
await superwall.setLocaleIdentifier(null);

Overview

Set the locale before Superwall config

Verify the active locale

Change the locale at runtime

Related resources

On this page