@lionrapid/react

@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> renders translation HTML through @lionrapid/core's allowlist sanitizer in both modes, so an attacker-influenced translation cannot inject script. Non-allowlisted elements (<script>, <iframe>, form/block tags), on* event handlers, and dangerous-scheme URLs (javascript:, data:, vbscript:) are stripped; a hostile wrapper degrades to its inner text. Interpolated values are coerced to their declared string | number type and rendered as text. Caller-supplied JSX children (the component-map branch) are trusted by contract — only server/translation-supplied markup is sanitized.

Requires @lionrapid/core >= 0.5.x (the sanitizer). <Trans> throws at import time against an older core rather than silently rendering unsafe HTML.

Migration from react-i18next

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

License

MIT