Datasheet · React i18n · DX & Type-Safety

Type Safety, Extraction & Tooling Six React i18n libraries, measured on typed keys, extraction CLIs & IDE support

Document control

Rev.: 2026-07-15
Class: Survey
Parts: 6
Refs: 26 cited
Read: 6 min

One architectural fault line sets every downstream property: whether type safety is generated by the build or hand-wired after the fact. This sheet reads that split as a feature matrix, not prose.

§0

Description & recommended part

DX lens

For type safety you don't maintain, pick a compile-first part: Paraglide or typesafe-i18n emit typed message artifacts where a renamed or missing key is a compile error by design^[8]^[20]. On Next.js, next-intl ships typed keys + typed navigation from a single generated declaration^[12]. Lingui wins catalog-management DX (co-located macros + lingui extract)^[4]. i18next and react-intl are type-safe only after you bolt on declaration files / CLI extraction — the mature-but-manual option^[3].

§1

The core split — two architectures

bin classification

Bin A · pass by construction

Type-safe by design

A generator or compiler reads the source catalog and emits typed artifacts — message functions or .d.ts. Keys, params and plural args are typed as a build side-effect. You cannot ship an app that references a key that doesn't exist^[9]^[10].

Paraglide

typesafe-i18n

Lingui

Bin B · pass after setup

Bolted-on (runtime + augmentation)

The library ships a generic t() / formatMessage(); you opt in to type safety by hand-writing or generating a declaration file that augments the library's types. Works well — but it's setup you own and maintain^[8]^[3].

i18next

react-intl

◈ next-intl straddles both: runtime hooks, but a first-class codegen step (createMessagesDeclaration) makes typing a one-liner rather than a hand-rolled augmentation^[12].

§2

Feature matrix

✓ present · ◑ partial · ✗ absent

Part	Typed keys	Typed args / plurals	Missing key = build error	First-party extractor	i18n Ally support	Zero manual type setup
i18nextmodule augmentation	◑opt-in .d.ts	✗	◑once typed	✗community scanner	✓	✗
react-intlFormatjsIntl override	◑weak / manual	✗	✗	✓@formatjs/cli	✓	✗
Linguimacros + catalog types	✓	✓	◑at macro site	✓extract + merge	✓+ ESLint	◑needs plugin
next-intlcreateMessagesDeclaration	✓	✓ICU	✓	✗hand-authored JSON	✓+ official	✓one codegen
Paraglidecompiler → message fns	✓	✓	✓	◑inlang catalog	◑inlang tooling	✓
typesafe-i18ngenerator from base locale	✓	✓best-in-class	✓	◑watcher (dev)	◑editor-agnostic	✓

✓ present / strong ◑ partial / with caveat ✗ absent by design or unshipped

§3

Electrical characteristics — per part

mechanism · extraction · IDE

i18next / react-i18next⭐ 8.6k

Bolted-on

Type mech.: Module augmentation of CustomTypeOptions; add an i18next.d.ts with a resources type^[1]^[2]. Generate it with i18next-resources-for-ts for large catalogs^[25].
Extraction: No first-party extractor; community i18next-scanner reads t() calls^[3].
Perf note: v25.4+ adds enableSelector to fix TS/IDE lag on big resource unions^[1].

Mature, flexible — most boilerplate.

react-intl / FormatJS⭐ 14.7k

Bolted-on

Type mech.: defineMessages() returns Record<string, MessageDescriptor>; key typing via a global FormatjsIntl namespace override^[18]. Better defineMessages typings are a years-old open ask^[26].
Extraction: @formatjs/cli extract + babel-plugin-formatjs; you merge output yourself^[19].
Verify: formatjs verify with --missing-keys / --extra-keys^[19].

Canonical ICU tooling — verbose, manual merge.

Lingui⭐ 5.8k

By design

Type mech.: Inline t/<Trans> macros compiled by the SWC/Babel plugin; type-safe at the component call site via macros + generated catalog types — rated "excellent"^[21].
Extraction: lingui extract extracts and merges into PO catalogs; experimental dep-tree crawl for per-page catalogs^[4]^[5].
Constraint: Requires the compiler plugin — no plugin, macros throw^[3].

Best catalog DX; needs the compiler plugin.

next-intl⭐ 4.3k

Hybrid

Type mech.: Point createMessagesDeclaration at the default-locale JSON; it emits a .d.json.ts and every t('…') becomes typed — no manual augmentation^[12].
Navigation: v4 declares a Locale type in AppConfig; useLocale() and createNavigation() are locale-typed end to end^[13].
Extraction: None — JSON hand-authored; missing keys are compile errors once typed^[12].

Top-tier on Next.js, fast setup.

Paraglide⭐ 567

By design

Type mech.: Compiler turns each message into a typed ESM function (m.greeting({ name })). Keys + params typed by default; unused messages tree-shake out (up to ~70% smaller bundles)^[8].
Extraction: Messages live in the inlang catalog; the compiler regenerates functions on change^[9]. No provider/context — one Vite plugin.
Extra: LocalizedString branded type distinguishes a translated string from a raw one at the type level^[7].

Exceptional; tree-shaking, no context. Youngest ecosystem.

typesafe-i18n⭐ 2.5k

By design

Type mech.: Watcher/generator reads the base locale, emits .ts definitions + React adapter wrappers. Types keys and args/formatters; other locales are diffed against the base type^[10]^[11].
Strength: Best-in-class parameter-level checking (plural forms, message args); zero runtime deps^[20].
Trade-off: Custom (non-ICU) message syntax.

Strongest arg-level types; custom syntax.

§4

Shared IDE layer

editor tooling

⌘VS Code

i18n Ally ⭐ 4.9k — the common VS Code layer

Supports i18next, react-intl and Lingui among others^[15]. Compile-first libraries lean less on the editor extension because the compiler is the source of truth.

Inline translation annotations after each key^[16]
One-click translate of missing / stale keys
Stale-translation detection
Regex-based usage matching
next-intl documents its own official VS Code integration^[14]

§5

Selection guide

use-case → part

Requirement profile	Recommended part	Why
Greenfield; care about type safety + bundle size	Paraglide	Typed message functions, compile-error safety, tree-shaking, minimal setup. Youngest ecosystem (⭐ 567) is the main risk^[8]^[7].
Next.js App Router	next-intl	Typed keys + typed navigation for near-zero effort^[12].
Strongest argument / plural typing, without ICU	typesafe-i18n	Best-in-class parameter-level checking of plural forms and message args^[20].
Translator-heavy workflow / prize catalog DX	Lingui	Co-located macros + one-command `extract`-and-merge; PO catalogs translators expect^[4]^[5].
Maximum ecosystem maturity; willing to wire types yourself	i18next	Augmentation + `i18next-resources-for-ts`^[1]^[25].
Need canonical ICU tooling + `verify` completeness checks	react-intl	Full ICU message syntax plus the `formatjs verify` missing/extra-key checks^[19].