@lionrapid/core

Core translation engine for LionRapid. TypeScript-first i18n with multi-layer caching, server sync, and browser auto-translation.

Installation

npm install @lionrapid/core

Usage

Developer mode (npm)

import {
  LionRapidBuilder,
  MemoryRepository,
  NetworkRepository,
} from '@lionrapid/core';

const lionRapid = await LionRapidBuilder.init({
  defaultLocale: 'en',
  namespace: 'app',
})
  .use(new MemoryRepository({ enabled: true }))
  .use(
    new NetworkRepository({
      enabled: true,
      options: { baseUrl: 'https://app.lionrapid.com' },
    })
  )
  .build();

// Translate
const text = lionRapid.t('welcome', 'Welcome!');

// With parameters (ICU MessageFormat)
const greeting = lionRapid.t('greeting', { name: 'John' });

// Change language
await lionRapid.changeLanguage('es');

// Get current locale
const locale = lionRapid.getCurrentLocale(); // 'es'

Auto-init mode (script tag)

No build step required. Add to any HTML page:

<script
  src="https://cdn.lionrapid.com/lionrapid.auto.min.js"
  data-api-key="pk_eng_xxx"
  data-base-url="https://app.lionrapid.com"
  data-default-locale="en"
  data-languages="en,es,fr"
  data-mode="full"
  async
></script>

Auto-init scans the DOM, extracts text blocks, fetches translations, and applies them in-place. Includes a floating language switcher.

Features

• Multi-layer cache: Memory (sync) -> LocalStorage -> Cache API -> Network
• Auto-sync missing keys: Batched POST of untranslated content to your backend
• ICU MessageFormat: Plurals, select, date/time, number formatting (via @lionrapid/formatters plugin)
• Event-driven: Subscribe to language:change:success, repo:set:success, and more
• Block-level translation: ContentUnit format preserves inline styles (<1>bold</1>)
• Visual editor: Built-in editor activated via ?__lr_editor=grant_xxx query param
• Tree-shakable: Import only what you use

When translation changes reach a visitor

Translations are cached in the browser and served instantly, so a change you approve does not appear on an open page immediately. There is no way for us to reach a visitor's browser — nothing can push an update into it — so the snippet refreshes itself instead:

• On tab focus, if the cached copy is more than 60 seconds old, it revalidates in the background and re-applies the page.
• After a sync, it retries at 2s, 8s and 30s to pick up translations for text it just reported as missing.

In practice an approved change reaches a visitor on their next page load or tab focus, give or take a minute. It does not appear on a page they are already staring at.

options.ttl is not this window. It is the hard expiry of the stored copy — 24 hours in localStorage, 7 days in the Cache API by default. Its job is to keep your site translated while our servers are unreachable, so set it long. Setting it short does not make updates arrive sooner; it only shortens how long you survive an outage.

If you need a change to appear faster than a page load, the surface has to be one we can reach: a site behind the LionRapid edge proxy is purged on approval, and the WordPress plugin is notified directly.

API

// Translation
t(key: string, fallback?: string): string
t(key: string, params: Record<string, unknown>, fallback?: string): string

// Language
await lionRapid.changeLanguage('fr');
lionRapid.getCurrentLocale(); // 'fr'

// Events
lionRapid.bus.on('language:change:success', (envelope) => {
  console.log(envelope.payload.newLocale);
});

Browser Bundles

| Bundle | Use case | | ------------------------- | --------------------------- | | lionrapid.auto.min.js | Script tag auto-translation | | lionrapid.iife.min.js | Script tag (developer mode) | | lionrapid.esm.min.js | ES modules | | lionrapid.umd.min.js | Universal (CommonJS + AMD) | | lionrapid.editor.min.js | Visual editor (lazy-loaded) |

Related Packages

• @lionrapid/react - React hooks and <Trans> component
• @lionrapid/formatters - ICU MessageFormat plugin
• @lionrapid/storage - LocalStorage and Cache API adapters
• @lionrapid/types - TypeScript type generation CLI

License

MIT