Skip to content

API Overview ​

SymbolPurposeExecution modeCommon gotcha
createTranslator()Compile one immutable locale catalogSyncNo fallback locales
createI18n()Create mutable locale and catalog storeSyncProvide eager catalogs, a loader, or both
createFormatter()Create a cached Intl facade from /formatSyncPass a locale getter for dynamic locale changes
createReactiveI18n()Mirror an i18n instance into ripple readables from /rippleSyncOptional @vielzeug/ripple peer; import from subpath
catalogKeys()Enumerate message keys as dotted pathsSyncTakes a catalog (or subtree) only; for an i18n instance pass state.catalogs[state.locale]
validateCatalog()Check explicit plural forms from /validateSyncImport from subpath
compareCatalogs()Compare key parity across locales from /validateSyncFirst locale is the base; import from subpath
LinguaErrorBase class for Lingua errorsSyncUse instanceof LinguaError for broad narrowing

Package Entry Point ​

ImportPurpose
@vielzeug/linguaTranslation factories, state types, and Lingua errors
@vielzeug/lingua/formatStandalone cached Intl formatter factory
@vielzeug/lingua/ripplecreateReactiveI18n(): reactive locale/translate bridge (optional @vielzeug/ripple peer)
@vielzeug/lingua/validatevalidateCatalog(), compareCatalogs(), and ValidationIssue

Translation Factories ​

createTranslator ​

ts
function createTranslator<C extends Catalog>(catalog: C, options?: TranslatorOptions): Translator<C>;

Compiles one catalog and returns an immutable fixed-locale translator. Locale defaults to en and controls plural selection and diagnostics.

ParameterTypeDescription
catalogCOne catalog containing only messages and grouping objects
optionsTranslatorOptionsLocale and missing-message strategy

Returns: Translator<C>.

Example:

ts
import { createTranslator } from '@vielzeug/lingua';

const translator = createTranslator({ save: 'Enregistrer' }, { locale: 'fr' });

translator.translate('save');
MethodSignatureReturns
translate(textKey, options?) or (pluralKey, { count, ordinal?, values? })Rendered string
translateUnkeyed(key: string, options?)Rendered string
parts(textKey, { values? }) or (pluralKey, { count, ordinal?, values? })Render-order Segment<V>[]
partsUnkeyed(key: string, options?)Render-order Segment<V>[]
localeLocaleResolved active locale

createI18n ​

ts
function createI18n<C extends Catalog>(options: I18nOptions<C>): I18n<C>;

Creates the catalog store, current locale state, and the active translator.

ParameterTypeDescription
options.catalogsCatalogs<C>Eager locale catalogs
options.localeLocaleInitial locale; defaults to en
options.loadCatalog(locale) => Promise<C> | CLoader for catalogs not supplied eagerly
options.fallbackLocale | readonly Locale[]Fallback locales loaded with the selected locale
options.missingMissingStrategyMissing-key/value strategy

Provide at least one of catalogs or loadCatalog; you may combine eager catalogs with loadCatalog for later locales.

Returns: I18n<C>, with every Translator<C> method plus lifecycle methods.

Example:

ts
import { createI18n } from '@vielzeug/lingua';

const i18n = createI18n({
  catalogs: { en: { title: 'Home' } },
  locale: 'en',
});
i18n.translate('title');
Method or propertySignatureReturns
translateTranslator methodRendered string
translateUnkeyedTranslator methodRendered string for a runtime key outside the typed key set
partsTranslator methodRender-order Segment<V>[] for the committed locale
partsUnkeyedTranslator methodRender-order Segment<V>[] for a runtime key
load({ locale? })Promise<void> after the locale and configured fallbacks load
setLocale(locale)Promise<void> after an atomic loaded-locale commit
isLoaded({ locale? })boolean
getSnapshot()Current locale, referentially stable until it changes
subscribe(listener, { immediate?, signal? })Unsubscribe function; listener receives the new locale
serialize()Loader-free SerializedI18n<C> for SSR transfer
dispose()void
localeLocaleCurrent canonical locale
disposedbooleanDisposal state
disposalSignalAbortSignalAborts on disposal
[Symbol.dispose]()Delegates to dispose()

Memoization rule: translate and parts have a deliberately stable function identity across setLocale() — they read the committed engine at call time, while getSnapshot() returns the locale string whose identity changes exactly when the locale does. Memoize derived translations on the locale, never on the function's identity (useMemo(..., [i18n.translate]) keeps the previous language).


Rich content (parts) ​

parts() resolves a message exactly like translate() — same plural selection, locale fallback, and missing strategy — but returns the message as render-order segments, so framework nodes can enter a sentence without ever being stringified.

ts
const segments = i18n.parts('link', { values: { label: <Link href="/sync">Sync</Link> } });
// [ { type: 'text', value: 'Go to ' }, { type: 'value', name: 'label', value: <Link/> }, { type: 'text', value: ' now.' } ]
ContractBehavior
OrderSegments are in render order; a value used twice produces two value segments; unreferenced values are ignored
TextText segments are never empty — adjacent placeholders yield adjacent value segments
ValuesPassed through untouched with identity preserved; never String()-ified, escaped, or merged with neighbors
Missing valueBecomes a text segment holding the missing strategy's output (null/undefined count as missing; '' is a real value)
Missing keyOne text segment holding the strategy's output; 'throw' still throws
Pluralparts(key, { count, ordinal?, values? }); count is interpolated into the selected form and can be overridden by an explicit count in values
EquivalenceJoining segments with String() reproduces translate() exactly, so parts is safe as your single resolution path

The interpolation contract shared by translate() and parts(): string values are inserted verbatim (no HTML or entity escaping), non-string values are String(value)-ified, and nullish values follow the missing strategy. Rich UIs should render parts segments instead of smuggling placeholders through a translated string: because values never enter the concatenated string, user data cannot reach an HTML sink through it.

V defaults to string; pass your node type to keep rendering type-safe: i18n.parts<ReactNode>('link', { values: { label: <Link/> } }).


Reactive bridge (@vielzeug/lingua/ripple) ​

createReactiveI18n ​

ts
function createReactiveI18n<C extends Catalog>(i18n: I18n<C>): ReactiveI18n<C>;

Bridges a lingua instance into @vielzeug/ripple so translated strings are reactive. i18n.translate() is not ripple-reactive on its own: reading it inside a computed() computes once and never re-runs, since it registers no tracked dependency. The bridge's translate, translateUnkeyed, parts, and partsUnkeyed first read the reactive locale readable, so any binding built on them re-evaluates the instant setLocale() resolves. For runtime-assembled keys inside reactive bindings use the bridge's translateUnkeyed/partsUnkeyed: calling i18n.translateUnkeyed directly skips the reactive locale and caches the first result.

@vielzeug/ripple is an optional peer dependency: install it only when you use this subpath.

ts
import { createI18n } from '@vielzeug/lingua';
import { createReactiveI18n } from '@vielzeug/lingua/ripple';
import { computed } from '@vielzeug/ripple';

const reactive = createReactiveI18n(createI18n({ catalogs, locale: 'en' }));

const heading = computed(() => reactive.translate('title')); // re-computes on setLocale()
await reactive.i18n.setLocale('fr');
Property or methodSignatureReturns
i18nI18n<C>The underlying instance for imperative work (setLocale, load, disposal)
localeReadable<Locale>Reactive locale: reading it inside a computed/template registers the dependency
translate(key, options?)Rendered string; re-evaluates whenever the locale changes
translateUnkeyed(key, options?)Rendered string for a runtime key; re-evaluates whenever the locale changes
parts(key, options?)Render-order Segment<V>[]; re-evaluates whenever the locale changes
partsUnkeyed(key, options?)Segment<V>[] for a runtime key; re-evaluates whenever the locale changes

Catalog Utilities ​

catalogKeys ​

ts
function catalogKeys<C extends Catalog>(catalog: C): ReadonlyArray<MessageKey<C>>;

Enumerates every message key as a dotted path. Traverses nested grouping objects and explicit { plural: ... } messages, producing the same paths that TextKey<C> represents at the type level. Pass any catalog object or subtree; for an I18n instance, read its current locale catalog first.

ParameterTypeDescription
catalogC extends CatalogRaw catalog object or any catalog subtree

Returns: ReadonlyArray<MessageKey<C>>: dotted paths to every text and plural message.

ts
import { catalogKeys, createI18n } from '@vielzeug/lingua';

const i18n = createI18n({
  catalogs: { en: { nav: { home: 'Home', settings: 'Settings' } } },
  locale: 'en',
});

const state = i18n.serialize();
const allKeys = catalogKeys(state.catalogs[state.locale]); // ['nav.home', 'nav.settings']
const navKeys = catalogKeys(state.catalogs.en.nav); // ['home', 'settings']

Intl formatting ​

createFormatter ​

ts
import { createFormatter } from '@vielzeug/lingua/format';

const format = createFormatter(() => i18n.locale);
format.number(1_234.5);
format.currency(19.99, 'USD');
format.date(new Date(), { dateStyle: 'medium' });

The formatter caches bounded Intl instances and resolves a locale getter for every call.

Validation ​

validateCatalog ​

ts
function validateCatalog(catalog: Catalog, locale: Locale): ValidationIssue[];

Validates explicit plural messages against locale plural categories after catalog structural validation.

ParameterTypeDescription
catalogCatalogExplicit catalog to validate
localeLocaleBCP 47 locale tag

Returns: ValidationIssue[].

Example:

ts
import { validateCatalog } from '@vielzeug/lingua/validate';

validateCatalog({ inbox: { plural: { one: 'One message' } } }, 'en');

compareCatalogs ​

ts
function compareCatalogs<C extends Catalog>(catalogs: Catalogs<C>): CatalogComparison;

Compares key sets across locales. First locale is the base: reports keys missing in each target and keys present in targets but absent from base. Validates each catalog structurally.

ParameterTypeDescription
catalogsCatalogs<C>Locale-keyed catalogs to compare

Returns: CatalogComparison with missing and extra arrays.

ts
import { compareCatalogs } from '@vielzeug/lingua/validate';

const result = compareCatalogs({
  en: { greeting: 'Hello', farewell: 'Goodbye' },
  de: { greeting: 'Hallo' },
});
// { missing: [{ key: 'farewell', locale: 'de' }], extra: [] }

Types ​

ts
type Locale = string;
type PluralCategory = Intl.LDMLPluralRule;
type PluralMessage = { readonly plural: Partial<Record<PluralCategory, string>> };
type CatalogNode = Catalog | PluralMessage | string;
type Catalog = { readonly [key: string]: CatalogNode };
type Catalogs<C extends Catalog = Catalog> = Record<Locale, C>;

type MissingInfo = { readonly key: string; readonly locale: Locale; readonly name?: string };
type MissingHandler = (info: MissingInfo) => string;
type MissingStrategy = 'throw' | 'key' | MissingHandler;

type TranslatorOptions = { readonly locale?: Locale; readonly missing?: MissingStrategy };

type I18nOptions<C extends Catalog = Catalog> = {
  readonly fallback?: Locale | readonly Locale[];
  readonly locale?: Locale;
  readonly missing?: MissingStrategy;
} & (
  | { readonly catalogs: Catalogs<C>; readonly loadCatalog?: CatalogLoader<C> }
  | { readonly catalogs?: Catalogs<C>; readonly loadCatalog: CatalogLoader<C> }
);

type CatalogLoader<C extends Catalog> = (locale: Locale) => Promise<C> | C;

type SerializedI18n<C extends Catalog = Catalog> = {
  readonly catalogs: Catalogs<C>;
  readonly locale: Locale;
};

type I18n<C extends Catalog = Catalog> = Translator<C> & {
  readonly disposalSignal: AbortSignal;
  dispose(): void;
  readonly disposed: boolean;
  getSnapshot(): Locale;
  isLoaded(options?: { locale?: Locale }): boolean;
  load(options?: { locale?: Locale }): Promise<void>;
  serialize(): SerializedI18n<C>;
  setLocale(locale: Locale): Promise<void>;
  subscribe(listener: (locale: Locale) => void, options?: SubscribeOptions): () => void;
  [Symbol.dispose](): void;
};

type Translator<C extends Catalog = Catalog> = {
  readonly locale: Locale;
  translate(key: TextKey<C>, options?: TranslateOptions): string;
  translate(key: PluralKey<C>, options: PluralOptions): string;
  translateUnkeyed(key: string, options?: TranslateOptions | PluralOptions): string;
  parts<V = string>(key: TextKey<C>, options?: PartsOptions<V>): readonly Segment<V>[];
  parts<V = string>(key: PluralKey<C>, options: PluralPartsOptions<V>): readonly Segment<V>[];
  partsUnkeyed<V = string>(key: string, options?: PartsOptions<V> | PluralPartsOptions<V>): readonly Segment<V>[];
};
ts
type Values = Record<string, unknown>;
type TranslateOptions = { values?: Values };
type PluralOptions = TranslateOptions & { count: number; ordinal?: boolean };
type SubscribeOptions = { immediate?: boolean; signal?: AbortSignal };

type Segment<V = string> =
  | { readonly type: 'text'; readonly value: string }
  | { readonly type: 'value'; readonly name: string; readonly value: V };
type PartsOptions<V = string> = { values?: Record<string, V> };
type PluralPartsOptions<V = string> = PartsOptions<V> & { count: number; ordinal?: boolean };

type CatalogPaths<
  C,
  Leaf,
  Prefix extends string = '',
  Depth extends readonly unknown[] = readonly [1, 1, 1, 1, 1, 1],
> = Depth extends readonly [unknown, ...infer Rest]
  ? C extends Leaf
    ? Prefix
    : C extends PluralMessage
      ? never
      : C extends Catalog
        ? {
            [K in string & keyof C]: CatalogPaths<C[K], Leaf, Prefix extends '' ? K : `${Prefix}.${K}`, Rest>;
          }[string & keyof C]
        : never
  : never;

type MessageKey<C> = CatalogPaths<C, string | PluralMessage>;
type TextKey<C> = CatalogPaths<C, string>;
type PluralKey<C> = CatalogPaths<C, PluralMessage>;

type ValidationIssue = { key: string; locale: Locale; missing: Intl.LDMLPluralRule };
type CatalogComparison = {
  readonly missing: ReadonlyArray<{ key: string; locale: Locale }>;
  readonly extra: ReadonlyArray<{ key: string; locale: Locale }>;
};

Errors ​

ErrorTrigger
LinguaDisposedErrorState mutation or subscription after dispose()
LinguaInvalidCatalogErrorInvalid catalog node or reserved key
LinguaInvalidLocaleErrorInvalid BCP 47 locale tag
LinguaInvalidPluralCountErrorNon-finite plural count
LinguaMissingCatalogErrorNo loadCatalog function or catalog source unavailable
LinguaMissingKeyErrorMissing translation key when missing: 'throw'
LinguaMissingValueErrorMissing interpolation value when missing: 'throw'