Current maturity: pico-intl v1 is stable for the core runtime, framework adapters, and file-based CLI workflows covered by the release gates and published npm adoption fixtures. The TypeScript plugin remains experimental editor tooling, and provider-backed machine translation plus advanced storage helpers remain non-stable until broader real-app validation lands.

Why pico-intl?

pico-intl is built for teams that want:

• Plain JSON translation catalogs.
• A small framework-independent core runtime.
• Strict CLI workflows for extraction, validation, generated types, migration, pruning, stats, and CI gates.
• The same translation model across React, Next.js, Vue, Svelte, Solid, Astro, Angular, Node, workers, and React Native-style runtimes, with framework-specific behavior normalized through tested adapters.
• A verified adapter contract for translation, locale reads, locale switching where supported, fallback behavior, key existence, and LTR/RTL direction metadata.
• Migration tooling to import/export common catalog formats.
• Honest benchmark and readiness documentation instead of vague "faster and smaller than everything" claims.

It is not trying to be a complete FormatJS clone, and it does not yet claim the ecosystem maturity of i18next. See message formatting for practical syntax examples and ICU strategy for the exact support boundary.

The strategic bet is workflow quality. Runtime lookup speed and bundle size are measured and guarded, but the bigger i18n pain for real teams is keeping translations extracted, typed, complete, reviewed, migrated, and enforced in CI. See localization workflows for the product boundary and roadmap.

Framework-Agnostic Contract

pico-intl does not pretend every framework has the same internals. Next App Router, Astro middleware, Angular DI, Svelte stores, Solid signals, and React hooks have real platform boundaries.

The v1 claim is narrower and testable: one translation model, one config/catalog workflow, and one behavioral contract across adapters. The contract is enforced by npm run test:adapter-contract and covers:

• t() behavior for interpolation, plural, and select messages.
• Base fallback behavior.
• Key existence checks where the adapter exposes the raw instance or an equivalent helper.
• Locale reads and locale switching where the framework adapter supports client-side switching.
• dir and isRTL metadata derived from the active locale.

See Framework-agnostic contract for the exact promise and boundaries.

Install

npm install @pico-intl-dev/core

With CLI tooling:

npm install --save-dev @pico-intl-dev/cli
npx pico-intl init

Quick Start

import { createI18n } from '@pico-intl-dev/core';

const i18n = createI18n({
  base: 'en',
  locale: 'en',
  messages: {
    greeting: 'Hello, {{name}}!',
    items: '{{count}} item | {{count}} items',
  },
});

i18n.t('greeting', { name: 'Ana' });
i18n.t('items', { count: 3 });

Formatting cheatsheet:

See message formatting for the full guide.

Async locale detection:

import { createI18nAsync, createLocalStorageAdapter } from '@pico-intl-dev/core';
import en from './locales/en.json';

export const i18n = await createI18nAsync({
  base: 'en',
  locale: 'auto',
  messages: en,
  supported: ['en', 'es'],
  storage: createLocalStorageAdapter('app-locale'),
  loader: (locale) => import(`./locales/${locale}.json`),
});

Packages

See production readiness for the current package-by-package matrix.

Releases

Real npm releases are published from GitHub tags through the Release & Publish workflow. The workflow builds every package, runs the package/browser/editor readiness gates, publishes with npm provenance, and creates a GitHub Release.

• Latest release: v1.0.2
• npm scope: @pico-intl-dev
• Release process: release checklist

Normal releases use the npm latest dist-tag. Prereleases use the next dist-tag.

Core Entry Points

import { createI18n } from '@pico-intl-dev/core/runtime';
import { detectLocale } from '@pico-intl-dev/core/detect';
import { formatDate } from '@pico-intl-dev/core/format';
import { createHttpBackend } from '@pico-intl-dev/core/http';
import { createNamespace } from '@pico-intl-dev/core/namespace';
import { getTextDirection } from '@pico-intl-dev/core/rtl';
import { createLocalStorageAdapter } from '@pico-intl-dev/core/storage';

Subpath exports are verified by npm run test:package-readiness.

Framework Examples

React:

import { PicoIntlProvider, useLocale, useT } from '@pico-intl-dev/react';

function Page() {
  const t = useT();
  const { dir, locale } = useLocale();
  return <h1 dir={dir} lang={locale}>{t('greeting', { name: 'Ana' })}</h1>;
}

export function App() {
  return (
    <PicoIntlProvider i18n={i18n}>
      <Page />
    </PicoIntlProvider>
  );
}

Next.js App Router:

import { createServerI18n } from '@pico-intl-dev/next';

export const { getT, getLocales, resolveLocale } = createServerI18n({
  base: 'en',
  supported: ['en', 'es'],
  loadMessages: async (locale) => (await import(`./locales/${locale}.json`)).default,
});

Svelte:

import { createI18nStore } from '@pico-intl-dev/svelte';

export const { t, locale, dir, isRTL, setLocale } = createI18nStore(i18n);

Angular:

import { providePicoIntl } from '@pico-intl-dev/angular';

export const appConfig = {
  providers: [providePicoIntl(i18n)],
};

Each adapter has a package README with fuller setup notes.

CLI

pico-intl's CLI is the main surface for production localization workflows:

npx pico-intl init --base en --targets es,fr
npx pico-intl validate --strict
npx pico-intl generate --output ./src/generated
npx pico-intl extract --src ./src --dry-run
npx pico-intl check --src ./src --strict --complete
npx pico-intl doctor --src ./src --ci
npx pico-intl stats --json
npx pico-intl prune --src ./src --dry-run

Migration helpers:

npx pico-intl import --from i18next --input ./src/locales --output ./locales
npx pico-intl import --from react-intl --input ./translations --output ./locales --report
npx pico-intl export --to react-intl --output ./translations

Import/export commands are helpers for plain JSON-style catalogs. import --report writes ICU-lite compatibility warnings for risky conversions, but complex message syntax and app conventions should still be reviewed after migration.

Provider-backed AI translation is available as a beta draft workflow, not a replacement for translator review:

npx pico-intl translate --to es,fr --provider openai --dry-run
npx pico-intl translate --to es --provider openai --context "B2B billing dashboard" --glossary "workspace=espacio de trabajo" --cache

translate validates placeholder preservation before writing, rejects providers that return the wrong batch size, and records generated output in .pico-intl/translation-review.json as draft. doctor --ci blocks while provider-generated drafts remain unreviewed.

Benchmarks

Benchmarks are local, repeat-based measurements with JSON report output. They cover runtime lookup, interpolation, plural/select, catalog load, cold start, SSR render, extraction speed, locale negotiation, and bundle size.

Latest local snapshot:

Comparative snapshot from the same harness:

These numbers are evidence for this harness, not a claim of universal superiority. Lingui commonly uses a compile-time catalog workflow, so its runtime bundle profile is not the same operating model as a plain JSON runtime.

Reproduce locally:

npm run build:all
npm run bench
npm run bench:compare
npm run bench -- --out bench-results/pico-intl.json
npm run bench:compare -- --out bench-results/compare.json

Read benchmark methodology before publishing comparison numbers. The old 0.9 KB full feature claim is not used here because it is not true for the full feature set.

Comparisons

• pico-intl vs i18next
• pico-intl vs react-intl
• pico-intl vs Lingui
• Message formatting
• ICU strategy
• Strict CI mode
• Localization workflows
• Framework-agnostic contract
• Release checklist
• v1 API stability
• Node.js support policy
• Ecosystem guides
• Migration: i18next to pico-intl
• Migration: react-intl to pico-intl
• Migration: Lingui to pico-intl

Review Reality Check

Development

npm install
npm run build:all
npm run lint
npm test
npm run test:cli-snapshots
npm run test:integration
npm run test:adapter-contract
npm run test:hydration
npm run test:ts-plugin
npm run test:package-readiness
npm run test:coverage:release
npm run bench
npm run bench:compare
npm run bench:threshold
npm audit

npm run test:all runs the full build/lint/test package-readiness path. For merge-blocking translation checks, see Strict CI mode.

Repository Layout

packages/
  core/        runtime engine
  cli/         locale workflow CLI
  react/       React adapter
  next/        Next.js App Router adapter
  vue/         Vue 3 adapter
  svelte/      Svelte store adapter
  solid/       SolidJS adapter
  astro/       Astro integration and middleware helpers
  angular/     Angular standalone DI, service, and pipes
  ts-plugin/   TypeScript Language Service plugin
bench/
  bench.mts    pico-intl runtime and entrypoint benchmark
  compare.mts  same-machine benchmark against real dependencies
docs/
  production-readiness.md
  benchmark-methodology.md
  release-checklist.md
  v1-readiness.md
  comparisons/
  guides/
  migrations/
test/
  e2e.mts
  adapter-contract.mts
  integration*.mts
  hydration.mts
  ts-plugin.mts
  package-readiness.mts

License

MIT (c) 2026 pico-intl contributors.