@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://api.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://api.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

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