i18next / react-i18next

npx expo install expo-localization
npm install i18next react-i18next

// src/i18n/i18n.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import { mapDeviceToAppLocale } from "./mapDeviceToApp";
import enCommon from "./locales/en/common.json";
import esCommon from "./locales/es/common.json";
 
void i18n.use(initReactI18next).init({
  resources: {
    en: { common: enCommon },
    es: { common: esCommon },
  },
  lng: mapDeviceToAppLocale(),
  fallbackLng: "en",
  defaultNS: "common",
  ns: ["common"],
  interpolation: { escapeValue: false },
  react: { useSuspense: false },
  compatibilityJSON: "v4",
});
 
export default i18n;

// app/_layout.tsx (excerpt)
import "@/i18n/i18n";
import { I18nextProvider } from "react-i18next";
import i18n from "@/i18n/i18n";
 
export default function RootLayout() {
  return (
    <I18nextProvider i18n={i18n}>
      <Stack />
    </I18nextProvider>
  );
}

import { useTranslation } from "react-i18next";
 
export function SaveButton() {
  const { t } = useTranslation("common");
  return <Button title={t("actions.save")} />;
}

src/i18n/locales/
  en/
    common.json
    auth.json
    billing.json
  es/
    common.json
    auth.json
    billing.json

// en/auth.json
{
  "sign_in": "Sign in",
  "sign_out": "Sign out",
  "errors": {
    "invalid_email": "Enter a valid email address"
  }
}

// src/features/auth/SignInScreen.tsx
import { useTranslation } from "react-i18next";
 
export function SignInScreen() {
  const { t } = useTranslation("auth");
  return <Text>{t("sign_in")}</Text>;
}

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import enCommon from "./locales/en/common.json";
import enAuth from "./locales/en/auth.json";
import esCommon from "./locales/es/common.json";
import esAuth from "./locales/es/auth.json";
 
void i18n.use(initReactI18next).init({
  resources: {
    en: { common: enCommon, auth: enAuth },
    es: { common: esCommon, auth: esAuth },
  },
  lng: "en",
  fallbackLng: "en",
  defaultNS: "common",
  ns: ["common", "auth"],
  interpolation: { escapeValue: false },
  react: { useSuspense: false },
  compatibilityJSON: "v4",
});

// en/billing.json
{
  "invoice_count_one": "{{count}} invoice",
  "invoice_count_other": "{{count}} invoices"
}

const { t } = useTranslation("billing");
<Text>{t("invoice_count", { count: items.length })}</Text>

// ar/billing.json - Arabic has complex plural rules; i18next handles forms
{
  "invoice_count_zero": "لا توجد فواتير",
  "invoice_count_one": "فاتورة واحدة",
  "invoice_count_two": "فاتورتان",
  "invoice_count_few": "{{count}} فواتير",
  "invoice_count_many": "{{count}} فاتورة",
  "invoice_count_other": "{{count}} فاتورة"
}

{
  "status": "Open",
  "status_male": "Open",
  "status_female": "Open",
  "friend": "Friend",
  "friend_male": "Friend",
  "friend_female": "Friend"
}

t("friend", { context: "female" }); // resolves friend_female when present

// src/i18n/loadLanguage.ts
import i18n from "./i18n";
 
const loaders: Record<string, () => Promise<{ default: Record<string, unknown> }>> = {
  es: () => import("./locales/es/common.json"),
  ja: () => import("./locales/ja/common.json"),
  ar: () => import("./locales/ar/common.json"),
};
 
export async function ensureLanguage(lang: string) {
  if (i18n.hasResourceBundle(lang, "common")) return;
  const load = loaders[lang];
  if (!load) return;
  const bundle = await load();
  i18n.addResourceBundle(lang, "common", bundle.default, true, true);
}
 
export async function changeAppLanguage(lang: string) {
  await ensureLanguage(lang);
  await i18n.changeLanguage(lang);
}

// LanguagePicker with lazy load
import { changeAppLanguage } from "@/i18n/loadLanguage";
 
<Pressable onPress={() => void changeAppLanguage("ja")}>
  <Text>日本語</Text>
</Pressable>

import i18n from "@/i18n/i18n";
 
export async function preloadNamespaces(lang: string, namespaces: string[]) {
  await Promise.all(
    namespaces.map(async (ns) => {
      if (i18n.hasResourceBundle(lang, ns)) return;
      const mod = await import(`./locales/${lang}/${ns}.json`);
      i18n.addResourceBundle(lang, ns, mod.default, true, true);
    }),
  );
}

// src/features/billing/BillingScreen.tsx
import { useEffect, useState } from "react";
import { useTranslation } from "react-i18next";
import { preloadNamespaces } from "@/i18n/loadNamespaces";
 
export function BillingScreen() {
  const { i18n, t } = useTranslation("billing");
  const [ready, setReady] = useState(i18n.hasResourceBundle(i18n.language, "billing"));
 
  useEffect(() => {
    void preloadNamespaces(i18n.language, ["billing"]).then(() => setReady(true));
  }, [i18n.language]);
 
  if (!ready) return <ActivityIndicator />;
  return <Text>{t("title")}</Text>;
}

import AsyncStorage from "@react-native-async-storage/async-storage";
import i18n from "./i18n";
import { changeAppLanguage } from "./loadLanguage";
import { mapDeviceToAppLocale } from "./mapDeviceToApp";
 
const KEY = "user:locale:v1";
 
export async function initI18n() {
  const saved = await AsyncStorage.getItem(KEY);
  const lang = saved ?? mapDeviceToAppLocale();
  await changeAppLanguage(lang);
  await i18n.changeLanguage(lang);
}
 
export async function setAppLanguage(lang: string) {
  await changeAppLanguage(lang);
  await i18n.changeLanguage(lang);
  await AsyncStorage.setItem(KEY, lang);
}

// app/_layout.tsx
const [ready, setReady] = useState(false);
useEffect(() => {
  void initI18n().then(() => setReady(true));
}, []);
if (!ready) return null;

// src/i18n/i18next.d.ts
import "i18next";
import type common from "./locales/en/common.json";
import type auth from "./locales/en/auth.json";
 
declare module "i18next" {
  interface CustomTypeOptions {
    defaultNS: "common";
    resources: {
      common: typeof common;
      auth: typeof auth;
    };
  }
}

const { t } = useTranslation("common");
t("actions.save"); // autocomplete + typo errors

import { I18nManager } from "react-native";
import * as Updates from "expo-updates";
import { setAppLanguage } from "./persistLanguage";
 
export async function setAppLanguageWithRtl(lang: string) {
  const isRtl = lang === "ar" || lang === "he";
  if (I18nManager.isRTL !== isRtl) {
    I18nManager.allowRTL(isRtl);
    I18nManager.forceRTL(isRtl);
    await setAppLanguage(lang);
    await Updates.reloadAsync();
    return;
  }
  await setAppLanguage(lang);
}

// __tests__/SignInScreen.test.tsx
import { render, screen } from "@testing-library/react-native";
import i18n from "i18next";
import { I18nextProvider, initReactI18next } from "react-i18next";
import { SignInScreen } from "../SignInScreen";
import enAuth from "@/i18n/locales/en/auth.json";
 
beforeAll(async () => {
  await i18n.use(initReactI18next).init({
    lng: "en",
    resources: { en: { auth: enAuth } },
    interpolation: { escapeValue: false },
  });
});
 
test("renders sign in label", () => {
  render(
    <I18nextProvider i18n={i18n}>
      <SignInScreen />
    </I18nextProvider>,
  );
  expect(screen.getByText("Sign in")).toBeOnTheScreen();
});