localize-react

React i18n, without the weight.

Tiny, type-safe React i18n built on Context and hooks.
~1.1 kB brotli · 0 runtime deps · dual ESM + CJS · React 19 ready.

Docs · Quickstart · API · Recipes · Migration v1 → v2

---

import { LocalizationProvider, useLocalize } from 'localize-react';

const translations = {
  en: { hello: 'Hi {{name}}!' },
  es: { hello: '¡Hola {{name}}!' },
  ja: { hello: '{{name}}さん、こんにちは!' },
};

function Greeting() {
  const { translate } = useLocalize();
  return <h1>{translate('hello', { name: 'Alex' })}</h1>;
}

export default function App() {
  return (
    <LocalizationProvider locale="en" translations={translations}>
      <Greeting />
    </LocalizationProvider>
  );
}

That's the whole API. Three exports, no plugins, no extraction toolchain. Ship it.

---

✨ Why?

Most React i18n libraries are 30–80 kB and bring opinions about plural rules, ICU MessageFormat, async loading, and TMS workflows. localize-react is the smallest thing that works.

It does exactly what a frontend most often needs:

• A nested translations tree, keyed by locale.
• Dot-path lookups ('cart.summary').
• {{name}}-style interpolation.
• A graceful fallback when keys are missing.

For everything else (plurals, currency, dates) — reach for the platform: Intl.PluralRules, Intl.NumberFormat, Intl.DateTimeFormat. Free, fast, already in the browser. See the Intl formatters recipe.

📦 Specs

Property	Value
Bundle (brotli)	1.13 kB ESM · 1.22 kB CJS
Runtime dependencies	0
Source	Strict TypeScript 6
Module formats	ESM + CJS with proper exports/types conditions
Tree-shaking	sideEffects: false
Peer range	React >= 16.8 < 20 (tested in CI through React 19)
Node	>= 20.19 (CI on 20, 22, 24 × Linux/macOS/Windows)
Test coverage	100 % statements · 100 % functions · 98 % branches
Type-checked exports	Validated by publint + @arethetypeswrong/cli in CI

🚀 Install

npm install localize-react
# or: pnpm add localize-react · yarn add localize-react · bun add localize-react

⚡️ Quickstart

1. Define translations

export const translations = {
  en: {
    greeting: { hello: 'Hi {{name}}!' },
    cart: { summary: '{{count}} items, {{total}} total' },
  },
  es: {
    greeting: { hello: '¡Hola {{name}}!' },
    cart: { summary: '{{count}} artículos, {{total}} total' },
  },
} as const;

2. Mount the provider

import { LocalizationProvider } from 'localize-react';
import { translations } from './i18n/translations';

export function App() {
  return (
    <LocalizationProvider locale="en" translations={translations}>
      <Shell />
    </LocalizationProvider>
  );
}

3. Translate, two ways

import { Message, useLocalize } from 'localize-react';

// Hook
function Cart() {
  const { translate } = useLocalize();
  return <p>{translate('cart.summary', { count: 3, total: '$42.00' })}</p>;
}

// Component
function CartHeader() {
  return (
    <h1>
      <Message descriptor="greeting.hello" values={{ name: 'Alex' }} />
    </h1>
  );
}

That's the whole story. Full docs at yankouskia.github.io/localize-react.

🛡 Fully type-safe with createLocalization()

Want the compiler to catch missing keys, typo'd descriptors, and forgotten {{tokens}}? Wrap your translations once and use the typed bindings:

import { createLocalization } from 'localize-react';

const translations = {
  en: { greeting: 'Hi {{name}}!', cart: { checkout: 'Checkout' } },
  es: { greeting: '¡Hola {{name}}!', cart: { checkout: 'Pagar' } },
} as const;

export const { LocalizationProvider, useLocalize, Message } =
  createLocalization(translations);

// inside a component — `translate` autocompletes descriptors and requires {{name}}:
function Greeting() {
  const { translate } = useLocalize();
  return <h1>{translate('greeting', { name: 'Alex' })}</h1>; // ✅
  // translate('greting');                  ❌ Type '"greting"' is not assignable
  // translate('greeting');                 ❌ Property 'name' is missing
}

A pure compile-time wrapper — no runtime cost, no second cache. Full guide: Type-safe API.

🎨 Rich content with <RichMessage />

Need a link or component inside a translated sentence? <RichMessage /> returns a ReactNode and lets values include React nodes, so a single translation can host inline rich content without splitting the sentence across JSX:

import { RichMessage } from 'localize-react';

// en: 'By signing up, you agree to our {{link}}.'
// de: 'Mit der Anmeldung stimmen Sie unseren {{link}} zu.'
function Footer() {
  return (
    <p>
      <RichMessage
        descriptor="signup.terms"
        values={{ link: <a href="/terms">Terms of Service</a> }}
      />
    </p>
  );
}

The link lands wherever the translator put {{link}} — German word order, Japanese particles, RTL flow, all handled by the translation. Strings and numbers are still accepted (and coerced) so you can mix them freely. Available as a typed export from createLocalization() too. Full recipe: Rich content.

🧠 Concept in one screen

Operation	API
Mount translations	<LocalizationProvider locale translations>
Translate (hook)	useLocalize().translate(descriptor, values?, default?)
Translate (component)	<Message descriptor values? defaultMessage? />
Translate with JSX	<RichMessage descriptor values? defaultMessage? />
Switch locale at runtime	Re-render with a new locale prop
Missing key	Renders defaultMessage ?? descriptor (never throws)
Nested lookup	translate('a.b.c') walks the tree
Interpolation	{{token}} — literal replacement, safe with regex chars
Locale normalization	En-US → en_us → en

📚 Recipes

Real-world patterns, fully documented on the site:

• Switching locales (URL / cookie / localStorage)
• Lazy-loading translation chunks with React.use()
• Next.js (App Router) — [locale] segments + middleware
• Vite + React Router — import.meta.glob
• Testing — RTL render helper, descriptor coverage
• Intl formatters — plurals, currency, dates, lists

🥊 How it compares

	localize-react	react-i18next	react-intl	lingui
Bundle (brotli)	~1.1 kB	~17 kB	~38 kB	~9 kB
Runtime deps	0	several	several	one macro
Pluralization (CLDR)	Use Intl	✅	✅ (ICU)	✅ (ICU)
Number / date format	Use Intl	Optional	✅	✅
ICU MessageFormat	❌	✅	✅	✅
Lazy locale loading	DIY	✅	✅	✅
Auto extraction	❌	✅	CLI	CLI
TypeScript-first	✅	✅	✅	✅
Learning curve	Tiny	Medium	Medium	Medium

Use localize-react when you want a hook + a tag. Reach for the others when CLDR plurals, ICU MessageFormat, or a TMS workflow matter — they're all great at what they do.

🛡 Production-ready

• Types ship inside the package — no @types/localize-react to chase.
• Provenance attestation on every published version (npm OIDC trusted publishing).
• CodeQL runs on every PR; CI matrix exercises Node 20/22/24 × Linux/macOS/Windows.
• Size budget enforced — < 2 kB ESM, < 2.5 kB CJS, checked on every PR with size-limit.
• No dynamic require, no eval, no regex from user input — interpolation is literal replaceAll.

📖 v1 → v2

The runtime API is unchanged. v2 modernizes the toolchain (strict TS 6, dual ESM+CJS, React 19 peer, GitHub Actions + Changesets). One soft TypeScript regression in exactOptionalPropertyTypes mode — see the migration guide.

🤝 Contributing

PRs welcome. See CONTRIBUTING.md for the setup + release flow. Security reports: please open a private security advisory rather than a public issue.

If you'd like to support the project, sponsoring helps a lot.

📄 License

MIT © Aliaksandr Yankouski