@lionrapid/react

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

Installation

npm install @lionrapid/react @lionrapid/core

Quick Start

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:

// 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:

// 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?)

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

Options: useSuspense, autoRefresh, keyPrefix

useLocale()

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

useChangeLanguage()

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

useTranslationReady(namespace?)

const ready = useTranslationReady('dashboard');

Key Prefix

Avoid repetitive key paths:

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.

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

Suspense: Wait for translations before render.

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