@playstack/i18n

Portable locale policy, typed flat message catalogs, fallback metadata and native Intl formatting.

Free. MIT licensed. Check preview availability before installing. See package access.

Localization is an implemented preview. Its subscription tier is not assigned in this catalog. It provides locale and catalog contracts, not a translation service, locale router or ICU compiler.

playstack add i18n --dry-run

Select --web for the React binding or --api for Nest. Integration manifests declare decisions and required tests; these recipes do not generate application wiring or select a database/ICU runtime.

import { createCatalogStore, createLocalePolicy, createLocaleFormatters } from '@playstack/i18n'

const policy = createLocalePolicy({
  locales: ['en', 'fr'],
  source: 'en',
  directions: { en: 'ltr', fr: 'ltr' },
})
const catalogs = createCatalogStore({
  policy,
  source: { common: { files: '{count, plural, one {# file} other {# files}}' } },
  translations: { fr: { common: { files: '{count, plural, one {# fichier} other {# fichiers}}' } } },
})
const locale = policy.resolveWeb({ cookieLocale: 'fr' })
const message = catalogs.get(locale, 'common', 'files')
// Format message.message with message.locale using your chosen ICU runtime.
const formatters = createLocaleFormatters(locale, { timeZone: 'UTC' })
formatters.currencyMinor(1299, 'USD')

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/i18n@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Resolution and ownership

Context	Precedence
Web	URL locale, cookie, user preference, Accept-Language, source default.
API	Accept-Language, authorized account preference, source default.
Delivery	Recipient preference, source default; reload it in the worker.

Policies and catalogs are copied, with no mutable global request locale. Language-header negotiation is bounded and honors weights/exclusions. negotiate() can return no acceptable match; convenience resolvers fall back, so applications own any 406 policy.

Catalog IDs are inferred from the source object. Dots are literal IDs; partial translations fall back, empty translations are valid, and unknown translation IDs fail. Each resolved message retains its effective locale: use that locale for fallback plural rules. Native Intl formatters require an explicit time zone; currency formatting is display, not accounting or conversion.

ICU parsing, parameter-type generation, extraction, file loading and native catalog compilation are not implemented. Keep complete messages intact, validate grammar with the selected ICU tooling, and never interpolate through naive string replacement or HTML injection. Verify rendering in the browsers and native runtimes your product targets.

API entry points and requirements

Reference snapshot: @playstack/i18n@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry point	Declaration file
`@playstack/i18n`	`./dist/index.d.ts`
`@playstack/i18n/errors`	`./dist/errors.d.ts`
`@playstack/i18n/package.json`	No TypeScript declaration (asset or metadata export).

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.