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
anduseTranslate
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 wrappedtrue
- 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 astolgee.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
.
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>
)
}