@molecule/app-i18n-default-react

@molecule/app-i18n-default-react — default i18n bond setup.

Bundles the 80-language fleet definitions + setupI18nDefault() helper that wires the molecule i18n provider with English bootstrap, lazy-loading for every other locale, common-bond translation merging, and locale persistence via the bonded storage provider.

Replaces the 113-line bonds/i18n-default.ts that every flagship app shipped byte-identically.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setupI18nDefault } from '@molecule/app-i18n-default-react'

// `en` is the app's eagerly-imported English UI translations —
// in your app: `import { ui as en } from '../locales/en/ui.js'`.
// The lazy loader MUST stay in the app so Vite can code-split
// each locale's ui.ts into its own chunk.
const lazyLoadUi = (code: string) => import(`../locales/${code}/ui.ts`).then((m) => m.ui)

setupI18nDefault({ enUi: en, lazyLoadUi })

Type

feature

Installation

npm install @molecule/app-i18n-default-react @molecule/app-i18n @molecule/app-locales-common @molecule/app-storage

API

Interfaces

`LanguageDefinition`

Static metadata for the 80 languages supported by the molecule flagship fleet. Each entry includes the locale code, native name, and text direction.

Lifted from the byte-identical per-app bonds/i18n-default.ts files that every fleet app used to ship.

interface LanguageDefinition {
  code: string
  name: string
  direction: 'ltr' | 'rtl'
}

`SetupI18nDefaultOptions`

Options accepted by setupI18nDefault.

enUi is the eagerly-loaded English UI translations (typically imported as import { ui as en } from '../locales/en/ui.js' in the consuming app). lazyLoadUi is a per-locale loader the app provides — it MUST remain in the app so Vite can code-split the per-language ui.ts bundles correctly.

interface SetupI18nDefaultOptions {
  /** Eagerly-imported English ui.ts translations. */
  enUi: Record<string, string>
  /**
   * Per-locale lazy loader for the app's `ui.ts`. The callback runs
   * on demand when the i18n provider switches to that locale; merging
   * with the universal common-locale bond is handled inside this
   * package, so callers only need to return the app-specific UI keys.
   */
  lazyLoadUi: (code: string) => Promise<Record<string, string>>
  /**
   * Per-package locale bonds to eagerly register with the i18n provider.
   *
   * Each entry is a star-imported `@molecule/app-locales-<name>` module.
   * Every property that LOOKS like a locale (matches `^[a-z]{2,3}(-[A-Z]{2,4})?$`
   * and resolves to a non-empty object of string values) is registered
   * via `provider.addTranslations(lang, translations)` at setup time.
   *
   * @example
   * ```ts
   * import * as authLocales from '@molecule/app-locales-auth'
   * import * as legalLocales from '@molecule/app-locales-legal-default'
   *
   * setupI18nDefault({
   *   enUi: en,
   *   lazyLoadUi,
   *   packageLocales: [authLocales, legalLocales],
   * })
   * ```
   *
   * Per-app `ui.ts` (registered via `lazyLoadUi`) still overrides
   * package-locale translations because it's merged in second.
   */
  packageLocales?: readonly PackageLocaleBond[]
  /**
   * Per-package locale bonds registered LAZILY, one language at a time.
   *
   * Each entry is that bond's `loadLocaleModule` export, imported from
   * `@molecule/app-locales-<name>/loader.js`. Nothing from these bonds is in
   * the entry bundle: the loader is called with a locale code the first time
   * that locale is selected, and only that language's dictionary is fetched.
   *
   * Prefer this over `packageLocales`: a star-import of the bond pulls
   * every one of its ~79 dictionaries into the importing chunk (several
   * megabytes across a typical app's dependencies).
   *
   * @example
   * ```ts
   * import { loadLocaleModule as authLocales } from '@molecule/app-locales-auth/loader.js'
   *
   * setupI18nDefault({ enUi: en, lazyLoadUi, packageLocaleLoaders: [authLocales] })
   * ```
   */
  packageLocaleLoaders?: readonly PackageLocaleLoader[]
  /**
   * Optional allowlist of locale codes the app actually supports.
   *
   * When provided, only these locales are registered with the i18n
   * provider — so `useTranslation().locales` (and therefore any
   * language-picker UI built on top of it) renders ONLY supported
   * choices. `'en'` is always included implicitly; the array doesn't
   * need to list it explicitly.
   *
   * When omitted, every entry in the fleet's 80-language
   * `LANGUAGE_DEFINITIONS` list is registered (back-compat).
   *
   * Typical call-site idiom uses Vite's `import.meta.glob` to
   * auto-detect which `ui.ts` files in the app's `locales/` directory
   * have non-empty translation objects:
   *
   * ```ts
   * const eager = import.meta.glob<{ ui: Record<string, string> }>(
   *   '../locales/*\/ui.ts',
   *   { eager: true },
   * )
   * const supportedLocales = Object.entries(eager)
   *   .filter(([, m]) => Object.keys(m.ui).length > 0)
   *   .map(([p]) => p.match(/locales\/([^/]+)\/ui\.ts$/)![1])
   * ```
   */
  supportedLocales?: readonly string[]
}

Types

`PackageLocaleLoader`

One companion bond's lazy per-language loader — the loadLocaleModule export of @molecule/app-locales-<name>/loader.js.

type PackageLocaleLoader = (code: string) => Promise<Record<string, string> | undefined>

code — Locale code, e.g. en, pt, zh-TW.

Returns: That bond's translations for the locale, or undefined when the bond has none.

`PackageLocaleBond`

Shape of a per-package locale bond passed via packageLocales.

Locale bond packages (@molecule/app-locales-<name>) follow a uniform layout: each <lang>.ts file exports a constant matching the locale code, and the package's src/index.ts re-exports all of them as a barrel. Consumers do import * as bond from '@molecule/app-locales-<name>' to get an object keyed by locale code (with types and a few non-locale exports also present).

This type captures the "anything except the types module is a {lang: translations} map" shape via Record<string, unknown> with a per-key runtime filter at registration time.

type PackageLocaleBond = Record<string, unknown>

Functions

`setupI18nDefault(props)`

Wire the molecule i18n provider with the fleet's 80-language list plus a default English bootstrap, then persist the user's locale selection through the bonded storage provider (if available).

Replaces the 113-line per-app bonds/i18n-default.ts that every flagship app shipped byte-identically — only the enUi import and lazyLoadUi template literal had to live in the app to preserve Vite's per-language code splitting.

function setupI18nDefault({
  enUi,
  lazyLoadUi,
  packageLocales,
  packageLocaleLoaders,
  supportedLocales,
}: SetupI18nDefaultOptions): I18nProvider

Constants

`LANGUAGE_DEFINITIONS`

Canonical 80-language definition list. The names are written in the language's own script for the language picker dropdown.

const LANGUAGE_DEFINITIONS: readonly LanguageDefinition[]

Injection Notes

Requirements

Peer dependencies:

@molecule/app-i18n ^1.0.1
@molecule/app-locales-common ^1.0.1
@molecule/app-storage ^1.0.1

Runtime Dependencies

@molecule/app-i18n
@molecule/app-locales-common
@molecule/app-storage

`@molecule/app-i18n-default-react`

How it works

Reference