Extend

Custom kinds and units, instances, core, and message packs.

Prefer the live demos? Open this section in the interactive docs.

Register custom kinds and units, define fuzzy vocab, isolate instances for SSR or multi-tenant apps, and bring your own message copy.

import { registerUnits, defineFuzzyVocab, createLingo } from "@pascal-app/lingo"

registerUnits("length", [
  { id: "smoot", symbol: "smoot", name: "smoot", factor: 1.702, system: "us" },
])

defineFuzzyVocab("mass", {
  profile: "parcels",
  unit: "kg",
  terms: { light: [0, 5], heavy: [20, 70] },
})

// Isolated instance for SSR / multi-tenant / tests — no global leaks.
const tenant = createLingo({ messages: { UNKNOWN_UNIT: "Metric units only." } })
tenant.parse("5 kg")

Custom kinds get parsing, conversion, formatting, and did-you-mean for free — like a per-order package_count kind:

import { allKinds, createLingo } from '@pascal-app/lingo'

const appLingo = createLingo({
  kinds: [
    ...allKinds,
    {
      kind: 'package_count',
      baseUnit: 'item',
      units: [
        { id: 'item', symbol: 'item', name: 'item', factor: 1, system: 'shared' },
        { id: 'case', symbol: 'case', name: 'case', factor: 24, system: 'shared' },
      ],
    },
  ],
})

appLingo.parseQuantity('3 cases', { kind: 'package_count', unit: 'item' })

For a minimal build, @pascal-app/lingo/core ships the engine with an empty registry and no English copy — register it with setDefaultMessages(englishMessages) or supply your own message pack per call. Nothing you register on a createLingo() instance leaks to the global one.