Lingui

@lingui/core is the runtime engine behind Lingui, an internationalization (i18n) toolkit for JavaScript applications. It provides the I18n class and setupI18n() factory that load compiled message catalogs, activate locales, and translate message IDs through ICU MessageFormat rules for plurals, ordinals, and number/date formatting, all in a package small enough to stay under 2kb minified and gzipped.

Rather than being a standalone framework, @lingui/core sits at the center of the wider Lingui ecosystem: @lingui/react adds React bindings (including React Server Components support), @lingui/cli extracts and compiles message catalogs from source code, and companion packages provide Babel/Vite plugins, ESLint rules, and format loaders for PO, JSON, and CSV catalogs. Messages are written as plain, readable strings with optional explicit IDs, keeping source code free of translation-key noise while still supporting rich-text interpolation and comments for translators.

What You Get

• The I18n class and setupI18n() factory for loading, activating, and switching between locale message catalogs at runtime
• Built-in ICU MessageFormat support for plurals, ordinals, select statements, and number/date interpolation via the message compiler
• An event emitter (change, missing) so UI layers can react to locale switches or log missing-translation events
• A formats module wrapping Intl.DateTimeFormat/Intl.NumberFormat with locale-aware memoized formatters
• First-class TypeScript types, including a Register interface for module augmentation that narrows message IDs to a generated union
• Escape-sequence handling and a pluggable MessageCompiler so catalogs can be precompiled at build time or compiled on the fly in development

Common Use Cases

• Powering translation calls (i18n._() / i18n.t()) in a React app via @lingui/react, with catalogs extracted and compiled by @lingui/cli
• Server-side or Node.js internationalization where message catalogs are loaded per-request and locale is activated per user session
• Formatting locale-aware dates, times, and numbers consistently across a multi-language product without hand-rolling Intl calls
• Migrating from react-intl, since Lingui’s low-level API and ICU message format are intentionally compatible with it
• Building framework-agnostic i18n for React Native, SolidJS, or vanilla JS apps that only need the core translation runtime

Under The Hood

Architecture — The runtime centers on the I18n class in packages/core/src/i18n.ts, which extends a minimal typed EventEmitter and holds locale, message catalogs (AllMessages), and an optional MessageCompiler. setupI18n() is a thin factory wrapping the constructor, and a module-level singleton i18n is exported from index.ts for convenience. Translation flows through the _()/t() method: it resolves the message for the active locale, falls back to a missing handler or the raw ID if absent, compiles uncompiled string messages via the registered MessageCompiler (backed by @lingui/message-utils/compileMessage), and finally runs the compiled AST through interpolate.ts to resolve ICU plural/select/number placeholders against caller-supplied values. A separate formats.ts module wraps Intl.DateTimeFormat/Intl.NumberFormat with a small memoization cache keyed by locale and options.

Tech Stack — Written entirely in TypeScript and published as ESM-only (type: module, exports map with .mjs/.d.mts outputs), built with unbuild and tested with vitest. The package lives inside the js-lingui Yarn/Lerna monorepo alongside @lingui/react, @lingui/cli, @lingui/solid, Babel/Vite/ESLint plugins, and format loaders, with internal dependencies resolved via workspace:* and shared devDependency versions pinned through a Yarn catalog:. babel-plugin-macros is an optional peer dependency used only when the macro transform is invoked. Bundle size is enforced in CI via size-limit.

Code Quality — The core package ships colocated *.test.ts files for every module (i18n.test.ts alone is 665 lines), covering locale activation, message loading/merging, missing-message handling, and the event emitter, run with Vitest and tracked via a Codecov coverage badge. The monorepo enforces ESLint (flat config, TypeScript-aware, import-order rules) and Prettier formatting repo-wide, plus a dedicated tstyche type-testing suite (test:types) to catch regressions in the exported generic types like MessageId/Register.

API Design — The public surface is intentionally small: setupI18n(), i18n.activate(), i18n._()/i18n.t(), and a formats namespace, with deprecated date()/number() instance methods clearly marked in favor of using Intl directly. TypeScript module augmentation (declare module "@lingui/core" { interface Register { messageIds: ... } }) lets consumers opt into a strictly-typed union of message IDs without any extra runtime cost, and the class-based I18n instance is easy to mock or scope per-request in server environments. Documentation for the package itself is minimal by design — it links out to the full reference and tutorials at lingui.dev rather than duplicating them in the README.