expo-localization

npx expo install expo-localization

{
  "expo": {
    "plugins": ["expo-localization"]
  }
}

// src/i18n/deviceLocale.ts
import { getLocales, getCalendars } from "expo-localization";
 
export function readDeviceLocale() {
  const [locale] = getLocales();
  const [calendar] = getCalendars();
  return {
    languageTag: locale.languageTag,
    languageCode: locale.languageCode ?? "en",
    regionCode: locale.regionCode,
    textDirection: locale.textDirection,
    currencyCode: locale.currencyCode,
    currencySymbol: locale.currencySymbol,
    decimalSeparator: locale.decimalSeparator,
    digitGroupingSeparator: locale.digitGroupingSeparator,
    measurementSystem: locale.measurementSystem,
    temperatureUnit: locale.temperatureUnit,
    timeZone: calendar.timeZone,
    uses24hourClock: calendar.uses24hourClock,
    firstWeekday: calendar.firstWeekday,
  };
}

import { getLocales } from "expo-localization";
 
const [primary, ...fallbacks] = getLocales();
 
console.log(primary.languageTag); // "en-US"
console.log(primary.languageCode); // "en"
console.log(primary.regionCode); // "US"
console.log(primary.textDirection); // "ltr" | "rtl"
console.log(primary.currencyCode); // "USD"
console.log(primary.currencySymbol); // "$"

import { useLocales } from "expo-localization";
import { Text, View } from "react-native";
 
export function LocaleDebugBanner() {
  const [primary] = useLocales();
  return (
    <View>
      <Text>Tag: {primary.languageTag}</Text>
      <Text>Currency: {primary.currencyCode ?? "unknown"}</Text>
      <Text>Direction: {primary.textDirection}</Text>
    </View>
  );
}

import { getCalendars } from "expo-localization";
 
const [calendar] = getCalendars();
 
calendar.timeZone; // "America/Los_Angeles"
calendar.uses24hourClock; // true | false
calendar.firstWeekday; // 1 = Sunday … 7 = Saturday
calendar.calendar; // "gregory"

import { useCalendars } from "expo-localization";
 
export function ScheduleHeader() {
  const [cal] = useCalendars();
  const hour12 = cal.uses24hourClock ? false : true;
  const label = new Intl.DateTimeFormat(undefined, {
    hour: "numeric",
    minute: "numeric",
    hour12,
    timeZone: cal.timeZone ?? undefined,
  }).format(new Date());
  return <Text>{label}</Text>;
}

// src/i18n/formatCurrency.ts
import { getLocales } from "expo-localization";
 
export function formatCurrency(amount: number, overrideCurrency?: string) {
  const [{ languageTag, currencyCode }] = getLocales();
  const currency = overrideCurrency ?? currencyCode ?? "USD";
  return new Intl.NumberFormat(languageTag, {
    style: "currency",
    currency,
  }).format(amount);
}

<Text>{formatCurrency(1299.5)}</Text>
// en-US device → "$1,299.50"
// de-DE device → "1.299,50 €" (when EUR region)

import { getLocales } from "expo-localization";
 
export function formatDecimal(value: number, fractionDigits = 2) {
  const [{ languageTag, decimalSeparator, digitGroupingSeparator }] = getLocales();
  const formatted = new Intl.NumberFormat(languageTag, {
    minimumFractionDigits: fractionDigits,
    maximumFractionDigits: fractionDigits,
  }).format(value);
 
  // Optional: assert separators match expo-localization for custom parsers
  void decimalSeparator;
  void digitGroupingSeparator;
  return formatted;
}

// src/hooks/useDeviceLocale.ts
import { useEffect, useState } from "react";
import { AppState, type AppStateStatus } from "react-native";
import { getLocales, type Locale } from "expo-localization";
 
export function useDeviceLocale(): Locale {
  const [locale, setLocale] = useState(() => getLocales()[0]);
 
  useEffect(() => {
    const sub = AppState.addEventListener("change", (state: AppStateStatus) => {
      if (state === "active") {
        setLocale(getLocales()[0]);
      }
    });
    return () => sub.remove();
  }, []);
 
  return locale;
}

import { getLocales } from "expo-localization";
 
const [{ measurementSystem, temperatureUnit, languageTag }] = getLocales();
 
export function formatDistance(meters: number) {
  if (measurementSystem === "us" || measurementSystem === "uk") {
    const miles = meters / 1609.344;
    return `${miles.toFixed(1)} mi`;
  }
  const km = meters / 1000;
  return new Intl.NumberFormat(languageTag, { maximumFractionDigits: 1 }).format(km) + " km";
}
 
export function formatTemperature(celsius: number) {
  if (temperatureUnit === "fahrenheit") {
    const f = (celsius * 9) / 5 + 32;
    return `${Math.round(f)}°F`;
  }
  return `${Math.round(celsius)}°C`;
}

// src/i18n/mapDeviceToApp.ts
import { getLocales } from "expo-localization";
 
const SUPPORTED = ["en", "es", "fr", "ar"] as const;
type AppLocale = (typeof SUPPORTED)[number];
 
export function mapDeviceToAppLocale(): AppLocale {
  const tags = getLocales().map((l) => l.languageTag);
  for (const tag of tags) {
    const lang = tag.split("-")[0]?.toLowerCase();
    if (lang && (SUPPORTED as readonly string[]).includes(lang)) {
      return lang as AppLocale;
    }
  }
  return "en";
}

// src/i18n/i18n.ts (excerpt)
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import { getLocales } from "expo-localization";
import { mapDeviceToAppLocale } from "./mapDeviceToApp";
import en from "./locales/en.json";
import es from "./locales/es.json";
 
const deviceLang = mapDeviceToAppLocale();
const [{ languageTag }] = getLocales();
 
void i18n.use(initReactI18next).init({
  resources: { en: { translation: en }, es: { translation: es } },
  lng: deviceLang,
  fallbackLng: "en",
  interpolation: { escapeValue: false },
  // Pass full tag to Intl helpers via i18n.language or a custom formatter
});
 
export { languageTag };

// src/i18n/DeviceLocaleContext.tsx
import { createContext, useContext, type ReactNode } from "react";
import { useDeviceLocale } from "@/hooks/useDeviceLocale";
import type { Locale } from "expo-localization";
 
const DeviceLocaleContext = createContext<Locale | null>(null);
 
export function DeviceLocaleProvider({ children }: { children: ReactNode }) {
  const locale = useDeviceLocale();
  return (
    <DeviceLocaleContext.Provider value={locale}>{children}</DeviceLocaleContext.Provider>
  );
}
 
export function useDeviceLocaleContext() {
  const ctx = useContext(DeviceLocaleContext);
  if (!ctx) throw new Error("useDeviceLocaleContext requires DeviceLocaleProvider");
  return ctx;
}

expo-localization checklist:
 
✓ npx expo install expo-localization
✓ Config plugin in app.json when using CNG
✓ getLocales for boot; useLocales / AppState for live updates
✓ Intl formatters use languageTag - never hard-coded en-US
✓ textDirection consulted before RTL layout enable
✓ Currency display uses currencyCode with commerce overrides where needed