Search documentation

Search all pages, headings and text, in the current package or topic or in all documentation.

active-i18n

A translation runtime over dictionaries your application supplies - interpolation, CLDR plurals, a React provider and an optional server integration for Next.

@workspace/active-i18n 1.1.0Developmentunreleased, in development in Foundationbaseline ce081dc3

@workspace/active-i18n translates keys into text from dictionaries your application supplies: {{name}} interpolation, plurals by Intl.PluralRules, a React provider with hooks that also hand the reader's presentation to your components, and an optional server integration for Next that loads your resources. Formatting and parsing come from active-format, its one workspace dependency.

Interpolation, plurals and a missing keyClient

Hello Ada

2 new messages

inbox.archived

count = 2

Missing keys reported: inbox.archived

What it owns#

  • The translation contract TranslationCapability and the runtime createTranslateFunction: key paths, interpolation, plural selection, and callbacks for a missing key, a warning or an error.
  • The client provider <I18nProvider> with useTranslations, useLocale and the one language switch, setLocale.
  • The server integration createServerTranslations (Next, React Server Components).
  • Language, currency and region names from the runtime's CLDR data.
  • The React distribution of a presentation: usePresentation, useFormatters, the time-zone providers, <RecencyTime> and <ViewerDateTime>.

What your application owns#

  • The dictionaries, their files and namespaces. The package knows no key of yours.
  • The language set and the fallback, and which language a reader gets (a cookie, a profile, Accept-Language). The package resolves nothing on its own and reads no cookie.
  • Where a choice is kept (persistLocale) and the logger (a factory you pass in). Without them the package touches no storage and reports nothing.
  • The reading direction of each language and the dir attribute; see Direction.

Entry points#

ImportRuns inContents
@workspace/active-i18nany JavaScript runtimecreateTranslateFunction, types, language and currency names
@workspace/active-i18n/reactReact client components<I18nProvider>, hooks, presentation and time-zone providers
@workspace/active-i18n/servera React Server Components server, such as NextcreateServerTranslations
@workspace/active-i18n/server/get-localea request of the Next App RoutergetAcceptLanguageCandidates

The two server entries mark themselves server-only: they throw in plain Node and in a browser bundle. The root and /react never reach them, so a site without Next uses those two only; see Without Next.

Dependencies#

@workspace/active-format, date-fns, @date-fns/tz and server-only. react (19) and next (15 or 16) are optional peers.

Next#

This page as Markdown