API (React)

TolgeeProvider

Provides Tolgee context and takes care of running/stopping tolgee. Accepts Tolgee instance.

import { TolgeeProvider } from '@tolgee/react';

<TolgeeProvider tolgee={tolgee} fallback="Loading...">
  <App />
</TolgeeProvider>;

You can use Tolgee without TolgeeProvider, but you'll have to run tolgee.run yourself and handle initial loading.

Prop fallback?

React.Node - it is rendered when Tolgee is loading translations instead of provided content.

Prop options?

{
  useSuspense?: boolean
}

• useSuspense: boolean - TolgeeProvider and useTranslate will use suspense pattern (default: true)

T component

import { T } from '@tolgee/react';

<T keyName="..." params={{ param: '...' }}>
  default value ...
</T>;

Prop keyName?

String - translation key.

Prop defaultValue?

String - default value if translation is not present.

Prop params?

Record<string, string | number | ReactElement | (val) => ReactNode> - variable parameters, which can be used in translation value (read more about ICU message format).

Prop ns?

string - translation namespace

Prop noWrap?

Boolean (default: false)

• false - in development mode translation will be wrapped
• true - use when wrapping in dev mode causes problems, in this case in-context translation won't work

Prop language?

String - override current Tolgee language. This way you can switch to different language for separate translation. Load the language manually with tolgee.loadRecord.

Children defaultValue? | keyName?

String - If keyName property is not defined, child is taken as keyName. If it is present child can be used as defaultValue.

Hook useTranslate

Use this hook to get t function for translating. It also serves for loading namespaces.

function useTranslate(ns?: string | string[]): {
  t: TFnType;
  isLoading: boolean;
};

This hook triggers suspense if specified namespace(s) are not yet available. Use it for loading namespaces for specific components/pages (returned t function uses first namespace from the list automatically).

Parameter ns

• string | string[] - namespace(s) which will be loaded

Property isLoading

• boolean - is true if any of listed namespaces is not loaded yet

Use this property if you manually disable useSuspense, to make sure you won't display translation keys.

Function t

Returns requested translation and also subscribes component to translation/language changes, so component will be re-rendered every time translation changes. If you use namespaces, t function will automatically use first of the namespaces given to useTranslate function. You can override this by ns option.

t('key', 'Default value', <options>);

t function has the same API as tolgee.t.

Hook useTolgee

function useTolgee(events?: TolgeeEvent[]): TolgeeInstance;

Returns tolgee instance. Allows subscription to different events, which will trigger re-render.

const RenderingLanguage = () => {
  // will update the component on "language" event
  const tolgee = useTolgee(['language']);

  return <div>Language: {tolgee.getLanguage()}</div>
};

const JustGettingTolgeeInstance = () => {
  // won't trigger rerender
  const tolgee = useTolgee();

  ...
};

const WorksAlsoWithOtherEvents = () => {
  const tolgee = useTolgee(['loading']);

  return <div>Tolgee is loading: {tolgee.isLoading()}</div>
};

Hook useTolgeeSSR

function useTolgeeSSR(
  tolgee: TolgeeInstance,
  language?: string,
  staticData?: TolgeeStaticData
): TolgeeInstance;

Safely syncs tolgee language and adds static data to tolgee cache for the initial SSR render.

It returns a "shallow copy" of tolgee instance which will ensure the first render is the same on server and client. So make sure you pass this copy to TolgeeProvider.

info

staticData need to be in tolgee format which is accepted by tolgee.addStaticData

Usage:

const tolgee = ...

function App() {
  const locale = // server provided locale
  const staticData = // server provided static data

  const ssrTolgee = useTolgeeSSR(tolgee, locale, staticData);

  return (
    <TolgeePrivider tolgee={ssrTolgee}>
      ...
    </TolgeeProvider>
  )
}