Localization

Read preferred locales and calendars, and follow system changes with React hooks

One.Localization reads the user’s language and formatting preferences. getLocales() and getCalendars() are synchronous snapshots. The named useLocales and useCalendars hooks read the same values and update when the platform reports a locale or time zone change. No permission is required.

Usage

import { Text } from 'react-native'
import { One, useCalendars, useLocales } from 'one'

const locales = One.Localization.getLocales()
const calendars = One.Localization.getCalendars()

function LocalTime({ when }: { when: Date }) {
  const [locale] = useLocales()
  const [calendar] = useCalendars()
  const label = new Intl.DateTimeFormat(locale.languageTag, {
    ...(calendar.timeZone ? { timeZone: calendar.timeZone } : {}),
    hour: 'numeric',
    minute: '2-digit',
  }).format(when)

  return <Text>{label}</Text>
}

Both reads always return at least one entry, so the first entry can be destructured directly. Hooks are imports from one; they are not methods on the namespace. Your app supplies translations; this API supplies the preferences used to choose and format them.

API reference

Unknown optional values are null. Locale preferences can differ from language preferences: on iOS, number separators, currency, measurement, and temperature follow the device’s formatting settings even when its first preferred language names a different region.

Platform differences

System settings may restart an app when its language changes. While the app is running, hooks subscribe to the platform’s change notifications and remove their listeners on unmount. Snapshot reads do not subscribe. The web hooks listen for languagechange; they do not independently watch time zone changes. During server rendering the locale falls back to en-US; the server’s Intl implementation supplies calendar data when available.

Migration from Expo

Replace Expo Localization’s getLocales() and getCalendars() with One.Localization.getLocales() and One.Localization.getCalendars(). Import useLocales and useCalendars from one; the hook names and the Locale and Calendar field names stay the same.

For the older combined asynchronous snapshot, see One.Device.getLocalizationInfo. Use Localization when you need the preferred locale list or reactive formatting preferences.