npm package: @lionrapid/react
Description: React integration for LionRapid localization library
Author: Janrau B
Latest version: 0.1.0

# @lionrapid/react

React bindings for LionRapid. Provider, hooks, and `<Trans>` component with JSX interpolation and ICU MessageFormat.

## Installation

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

## Quick Start

```tsx
import { LionRapidProvider, useLionRapid } from '@lionrapid/react';
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();

function App() {
  return (
    <LionRapidProvider instance={lionRapid}>
      <MyComponent />
    </LionRapidProvider>
  );
}

function MyComponent() {
  const { t, locale, changeLanguage } = useLionRapid();

  return (
    <div>
      <h1>{t('welcome', { name: 'User' }, 'Welcome!')}</h1>
      <p>Current: {locale}</p>
      <button onClick={() => changeLanguage('es')}>Español</button>
    </div>
  );
}
```

## `<Trans>` Component

Embed React components in translations using indexed tags:

```tsx
// Translation: "Click <1>here</1> to <2>read more</2>"
<Trans i18nKey="clickHere">
  <a href="/info" />
  <strong />
</Trans>
// Renders: Click <a href="/info">here</a> to <strong>read more</strong>
```

With ICU plurals:

```tsx
// Translation: "You have <1>{count, plural, one {# message} other {# messages}}</1>"
<Trans i18nKey="messageCount" values={{ count: 5 }}>
  <span className="badge" />
</Trans>
```

### Props

| Prop | Type | Description |
|------|------|-------------|
| `i18nKey` | `string` | Translation key (required) |
| `children` | `ReactNode` | Components to interpolate |
| `values` | `object` | ICU variable values |
| `defaultValue` | `string` | Fallback text |
| `namespace` | `string` | Override namespace |

## Hooks

### `useLionRapid(namespace?, options?)`

```tsx
const { t, locale, changeLanguage, ready } = useLionRapid('common');
```

Options: `useSuspense`, `autoRefresh`, `keyPrefix`

### `useLocale()`

```tsx
const locale = useLocale(); // 'en'
```

### `useChangeLanguage()`

```tsx
const changeLanguage = useChangeLanguage();
await changeLanguage('es');
```

### `useTranslationReady(namespace?)`

```tsx
const ready = useTranslationReady('dashboard');
```

## Key Prefix

Avoid repetitive key paths:

```tsx
const { t } = useLionRapid('common', { keyPrefix: 'user.settings' });
t('title');       // looks up 'user.settings.title'
t('description'); // looks up 'user.settings.description'
```

## Loading Patterns

**Immediate (default):** Render with fallback, auto-update when loaded.

```tsx
const { t, ready } = useLionRapid();
return <h1>{t('title', 'Default')}</h1>;
```

**Suspense:** Wait for translations before render.

```tsx
const { t } = useLionRapid('common', { useSuspense: true });
// Wrap with <Suspense fallback={<Loading />}>
```

## Security

`<Trans>` automatically validates against XSS: script injection, event handlers, javascript: protocols, and unbalanced tags.

## Migration from react-i18next

| react-i18next | LionRapid |
|---------------|-----------|
| `{{name}}` | `{name}` |
| Custom formatters | ICU MessageFormat |
| Same `<Trans>` API | Same indexed tags |

## License

MIT