Tolgee for React

Tolgee for React is the official React binding for Tolgee, an open-source localization platform positioned as an alternative to Crowdin, Phrase, and Lokalise. Rather than reimplementing translation logic, the package wraps the framework-agnostic @tolgee/web core in idiomatic React primitives: a TolgeeProvider component, a useTranslate hook, a <T> component for inline translation keys, and useTolgee/useTolgeeSSR for reading the live instance.

It is published from the tolgee-js monorepo alongside sibling integrations for Vue, Svelte, and Angular, and ships a dedicated /server entry point so Next.js App Router and other SSR setups can hydrate translations without a client-only round trip. A GlobalContextPlugin escape hatch also lets code outside the React tree read the active Tolgee instance, which is useful for utility functions that need to translate a string without threading props through components.

What You Get

• TolgeeProvider component that boots the Tolgee instance, tracks loading state, and supports Suspense via an options.useSuspense flag
• useTranslate(ns?, options?) hook returning a typed t() function plus isLoading, scoped to one or more namespaces
• <T> component for inlining a translation key (with an optional default value) directly in JSX
• useTolgee() and useTolgeeSSR() hooks for reading the live Tolgee instance and hydrating server-rendered language/static data
• Dedicated /server export (createServerInstance) so Next.js App Router and other SSR frameworks get a server-safe entry point
• GlobalContextPlugin for accessing the active Tolgee instance from outside the React component tree

Common Use Cases

• Adding multi-language support to a Create React App, Vite, or Next.js Pages Router project
• Server-rendering translated pages in a Next.js App Router app via the /server entry and ssr provider option
• Enabling Tolgee’s in-context visual translation editing during development while a translator or developer edits copy live
• Translating strings inside non-component utility/helper code via GlobalContextPlugin instead of prop-drilling the t function
• Migrating an app already using react-i18next to Tolgee’s hosted or self-hosted translation backend

Under The Hood

Architecture TolgeeProvider mounts a single module-level React context (created lazily via getProviderInstance()) that every hook in the package reads from through a shared useTolgeeContext helper, so useTranslate, useTolgee, and the <T> component are all thin consumers of one instance rather than independent state machines. A module-level LAST_TOLGEE_INSTANCE reference lets the provider avoid restarting the Tolgee core on every re-render, only restarting when the instance identity actually changes (e.g. hot reload), and it explicitly catches and logs a failed .run() rather than swallowing it. SSR gets its own code path: useTolgeeSSR merges a hard-set language/staticData pair into the instance for the first render, and a separate /server package export (createServerInstance, server.ts) keeps that logic out of the client bundle. GlobalContextPlugin mirrors the same provider payload into a module-level variable so code outside the component tree can still reach the active instance. All translation, formatting, storage, and backend-fetch behavior is delegated to @tolgee/web (which itself wraps @tolgee/core), so this package’s own surface is limited to context wiring, hooks, and the <T> component — a change to the core instance API would ripple through every hook here since each one forwards to it directly.

Tech Stack Written in TypeScript with strict: true, targeting es2017/esnext, and built with Rollup into separate CJS, ESM, and .mjs bundles plus a standalone tsc declaration-only pass for .d.ts files. The package lives in a pnpm + Turborepo monorepo (tolgee-js) versioned with Lerna, alongside sibling packages for Vue, Svelte, Angular, i18next interop, and a framework-agnostic web/core pair. Its only runtime dependency is @tolgee/web, pinned to the exact monorepo version on every release; React itself is a peer dependency accepting ^16.14 || ^17 || ^18 || ^19, a broad compatibility range that includes React 19. Testing uses Jest with jest-environment-jsdom, React Testing Library, and jest-fetch-mock for network stubbing. Releases are automated with semantic-release and commitlint (Conventional Commits) driven from GitHub Actions.

Code Quality Six spec files (roughly 900 lines) cover the provider, the <T> component, useTolgee, useTolgeeSSR, useTranslate, and namespace handling, split between component-level specs and an __integration suite that exercises hooks and components together rather than in isolation. The test script runs Jest with --collect-coverage --runInBand, and the monorepo enforces eslint --max-warnings 0 in CI on every push. TypeScript strict mode is enabled and the public API is fully typed and re-exported through a single types.ts. Naming is consistent (hooks prefixed use*, the provider suffixed Provider), and the one place an async failure could go silent — the provider’s tolgee.run() call — is caught explicitly and logged rather than ignored.

API Design The public surface is deliberately small: a provider, two or three hooks, and one component cover most integration needs, which keeps the initial learning curve low compared to hand-rolling a React i18n layer. Two choices stand out as solving real pain points rather than just wrapping the core API: a dedicated /server export that gives SSR frameworks (notably Next.js App Router) a distinct, tree-shakeable entry point instead of forcing all consumers through client-only code, and GlobalContextPlugin, which lets non-component code (utility functions, non-React modules) read the active Tolgee instance without prop-drilling. Suspense support is opt-in via a single useSuspense option rather than being forced on every consumer.