setupTerai

Main function to be called to configure runtime options for Terai in React Native. It should be called only once (ideally, at the entry point of your application).

import { setupTerai } from '@terai/react-native'

setupTerai({
  // Configuration options
})

Setup options

defaultLocale

• Type: Locale | (() => Locale)
• Default: ''

The default locale to be used by the library. It can be a string or a function that returns a string.

{
  defaultLocale: 'en-US'
}

loader

Function to load the locale data. It must return a promise that resolves to a dictionary.

• Type: (locale: string, chunkId: string) => Promise<Dictionary>
• Default: undefined

{
  loader: (locale: string, chunkId: string) =>
    import(`./locales/${locale}/${chunkId}.json`).then(
      (mod) => mod.default
    )
}

suspense

• Type: boolean | undefined
• Default: false

Enable React Suspense for dictionary loading.

When true: Component suspends while dictionary loads (requires Suspense boundary) When false: Returns empty dictionary while loading, re-renders when ready

{
  suspense: true
}

format

• Type: format?: { number?: FormatNumberOptions date?: FormatDateOptions list?: FormatListOptions displayName?: FormatDisplayNameOptions relativeTime?: FormatRelativeTimeOptions } | undefined
• Default: undefined

Global format options to be used by the library.

format: {
  number: {
		style: 'currency',
    currency: 'USD'
	},
  date: {
    dateStyle: 'long'
  }
}

Return Value

Returns a Promise that resolves to the configuration object. You don't need to await it.

Example

import { setupTerai } from '@terai/react-native'

setupTerai({
  defaultLocale: 'en',
  suspense: false,
  loader: (locale, chunkId) =>
    import(`../locale-system/${locale}/${chunkId}.json`).then(
      (mod) => mod.default
    ),
  format: {
    number: {
      style: 'decimal',
      minimumFractionDigits: 2,
    },
    date: {
      dateStyle: 'medium',
    },
  },
})

Persistence

Unlike the React web version, React Native uses AsyncStorage for persistence. The persistence happens automatically:

• Locale is saved to AsyncStorage when changed via setLocale
• Dictionaries are cached in AsyncStorage after loading
• Data is restored on app startup for instant experience
• Storage keys are versioned to prevent conflicts on updates

Platform Differences

• React Web: Uses localStorage (synchronous)
• React Native: Uses AsyncStorage (asynchronous, requires @react-native-async-storage/async-storage)

The API remains the same across platforms for consistency.