# @lionrapid/core

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

## Installation

```bash
npm install @lionrapid/core
```

## Usage

### Developer mode (npm)

```typescript
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:

```html
<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

```typescript
// 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](https://www.npmjs.com/package/@lionrapid/react) - React hooks and `<Trans>` component
- [@lionrapid/formatters](https://www.npmjs.com/package/@lionrapid/formatters) - ICU MessageFormat plugin
- [@lionrapid/storage](https://www.npmjs.com/package/@lionrapid/storage) - LocalStorage and Cache API adapters
- [@lionrapid/types](https://www.npmjs.com/package/@lionrapid/types) - TypeScript type generation CLI

## License

MIT