React

@transglot/react-i18n connects @transglot/runtime to React. Components that translate re-render when the locale changes or a new publish lands for the active locale.

InstallCopy Anchor Link

npm install @transglot/react-i18n

React 18 or 19 is a peer dependency. @transglot/runtime is installed with the package, and the package re-exports createClient, RuntimeError and the RuntimeClient and ClientOptions types, so one import is enough.

Minimal setupCopy Anchor Link

Wrap your app in TransglotProvider and pass the runtime client options:

import { TransglotProvider } from '@transglot/react-i18n';
import { createRoot } from 'react-dom/client';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <TransglotProvider
    options={{
      baseUrl: 'https://api.transglot.ai',
      project: 42,
      cdnKey: 'taicdn_your_key',
      locale: 'en',
      authIn: 'query',
    }}
  >
    <App />
  </TransglotProvider>,
);

Then translate in any component below it:

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

export function Header() {
  const { t, locale, setLocale } = useTranslations();

  return (
    <header>
      <h1>{t('home.title')}</h1>
      <p>{t('cart.items', { count: 3 })}</p>
      <T keypath="home.greeting" params={{ name: 'Ada' }} />
      <button onClick={() => setLocale(locale === 'en' ? 'fr' : 'en')}>{locale}</button>
    </header>
  );
}

The provider starts loading the initial locale when it mounts. Until the bundle arrives, t returns keys; the tree re-renders with translations when it lands.

APICopy Anchor Link

TransglotProviderCopy Anchor Link

Pass exactly one of options or client.

The provider reads options or client once, on its first render. To switch to a different client, remount the provider (for example with a React key). On unmount it stops listening to the client; it does not call client.stop(), so stop a client you created yourself.

useTranslations()Copy Anchor Link

Returns { t, locale, setLocale, client }. Throws [transglot] useTranslations() must be used inside <TransglotProvider>. when there is no provider above the component.

TCopy Anchor Link

Renders a translation as a bare text node. Wrap it in an element yourself if you need one.

Other exportsCopy Anchor Link

• TransglotContext: the React context the provider fills. Its value is a TransglotStore ({ client, subscribe, getSnapshot }) shaped for useSyncExternalStore, or null outside a provider.
• Types: TransglotProviderProps, UseTranslations, TProps, TransglotStore.

Handling load errorsCopy Anchor Link

The provider starts the first load and does not catch its failure. To handle a RuntimeError yourself, create the client, load the locale, and pass the client in:

import { createClient, RuntimeError, TransglotProvider } from '@transglot/react-i18n';
import { createRoot } from 'react-dom/client';
import { App } from './App';

const client = createClient({
  baseUrl: 'https://api.transglot.ai',
  project: 42,
  cdnKey: 'taicdn_your_key',
  locale: 'en',
  authIn: 'query',
});

try {
  await client.loadLocale('en');
} catch (error) {
  if (!(error instanceof RuntimeError)) throw error;
  console.error(error.slug, error.hint);
}

createRoot(document.getElementById('root')!).render(
  <TransglotProvider client={client}>
    <App />
  </TransglotProvider>,
);

setLocale from the hook rejects with a RuntimeError in the same way, so catch it where you call it. The error slugs are listed on the JavaScript runtime page.

Server renderingCopy Anchor Link

TransglotProvider loads translations after mount, so server-rendered HTML contains keys, not translations. For server rendering with React, use @transglot/next or @transglot/astro, which fetch the bundle on the server and seed the client before the first render.

RelatedCopy Anchor Link

• JavaScript runtime
• Next.js
• react-intl