@transglot/react-i18n

A thin React 18 / 19 runtime i18n adapter over @transglot/runtime. It gives you a <TransglotProvider>, a useTranslations() hook, and a reactive <T> component. Switching the locale re-renders every t(...) call site (via useSyncExternalStore over the runtime client's onChange). React is a peer dependency; it is never bundled.

Not the in-context editor. This package delivers your project's published translations to end users. If you want the ALT+click reviewer overlay, that is a different package: @transglot/react.

Install

npm install @transglot/react-i18n @transglot/runtime react

Quickstart

Wrap your app with the provider, passing the runtime CDN options:

import { TransglotProvider } from '@transglot/react-i18n';

export function Root() {
  return (
    <TransglotProvider
      options={{
        baseUrl: 'https://app.example.com',
        project: 42,
        cdnKey: 'taicdn_…',
        locale: 'en',
      }}
    >
      <App />
    </TransglotProvider>
  );
}

Translate anywhere with the hook:

import { T, useTranslations } from '@transglot/react-i18n';

function Header() {
  const { t, locale, setLocale } = useTranslations();
  return (
    <header>
      <h1>{t('home.title')}</h1>
      <p>{t('cart.items', { count: 3 })}</p>

      {/* The <T> component renders a translation as a text node */}
      <T keypath="home.greeting" params={{ name: 'Ada' }} />

      <button onClick={() => setLocale(locale === 'en' ? 'fr' : 'en')}>{locale}</button>
    </header>
  );
}

Already have a runtime client? Adopt it instead of options:

import { createClient } from '@transglot/runtime';
import { TransglotProvider } from '@transglot/react-i18n';

const client = createClient({ baseUrl, project, cdnKey, locale: 'en' });

<TransglotProvider client={client}>
  <App />
</TransglotProvider>;

API

• <TransglotProvider client|options>: pass EITHER a pre-built runtime client or the runtime ClientOptions as options (the provider builds the client). It warms the initial locale and provides the store to the tree. The client is created once; changing client/options requires a remount.
• useTranslations() → { t, locale, setLocale, client }. t(key, params?) re-renders its component on a locale switch or background bundle refresh; locale is the active locale string; setLocale(locale) loads then switches. Throws if used outside the provider.
• <T keypath params>: renders a translation as a bare text node.

Missing keys return the key (never throw); network/HTTP errors surface as the runtime's typed RuntimeError.