Skip to main content

What's new in Tolgee Platform v3 and Tolgee JS v5

· 3 min read
Jan Cizmar 🧑🏻‍💻
Štěpán Granát

We are proud to share that we have released the new versions of Tolgee Platform v3 and Tolgee JS v5. We have added namespaces support to structure your strings into smaller chunks. The base library of our JS integrations is completely redesigned to be more lightweight end extendable by plugins.

What's new in the Tolgee Platform v3

The most exciting feature of the new platform release is the namespaces support. Now you can select a namespace while creating a new key, importing data, or exporting data.

The breaking changes

While adding the namespaces support, we also removed some deprecated API endpoints. So if you use those in your CI/CD pipelines, please replace those with the /v2 endpoints. We have removed these endpoints:

  • All the endpoints matching /api/project/** (use /v2/projects/*)
  • All the endpoints matching /api/address-part/** (use /v2/slug/*)
  • /v2/projects/{projectId}/import/with-streaming-response (use /v2/projects/{projectId}/import)

While the /api/project/{projectId}/export/jsonZip is kept as the only v1 endpoint accessible with an API key.

We are removing these parameters of /v2/projects/export endpoint:

  • splitByScope
  • splitByScopeDelimiter
  • splitByScopeDepth

And introducing a new parameter structureDelimiter, which controls the character causing structuring in the resulting .jsons.

Since v3 supports namespaces natively, there is no need to control the depth of the directory structure in the export.

What's new in the Tolgee JS v5

The base package of Tolgee JS @tolgee/core was redesigned entirely and refactored to be more customizable, lightweight, and to support the namespaces feature. This new implementation makes it extremely simple to create new plugins or framework integrations.


We've extracted web-related plugins into a separate package, so @tolgee/core is as small as possible and ready to run in different environments (other than the web).

Unified initialization

In new integrations, tolgee is always initialized outside the actual integration, and only the tolgee instance is passed down. Example in React:

const tolgee = Tolgee()

export function App() {
return (
<TolgeeProvider tolgee={tolgee} fallback="Loading...">

This way, we offer you more flexibility in what you can do with the tolgee instance and embrace its plugin system.

Unified t function interface

All the integrations now use a unified t function interface, which is a bit different but cleaner and more straightforward read more.

Usage of Suspense in React integration

React integration now uses Suspense to implement dynamic namespaces addition nicely. The component which would start loading new namespace through useTranslate will trigger a suspense exception which you can catch by your Suspense component. If you don't catch it, it will bubble to TolgeeProvider and fallback will be shown.


  • The Tolgee Platform v3 and Tolgee JS v5 integrations support namespaces
  • Deprecated v1 endpoints (/api/*) were deleted
  • The JS @tolgee/core new JS SDKs are now lightweight, customizable, and cleaner
  • The @tolgee/web package contains plugins related to web
  • The interface of t function is unified across integrations
  • @tolgee/react now uses Suspense
Jan Cizmar 🧑🏻‍💻
Jan is a coding mastermind who's on a mission to save the world from software localization chaos. He has a passion for clean code, hates being a copy-pasting monkey 🙈 and is dedicated to delivering smart and simple software as the head of Tolgee.
Štěpán Granát
Štěpán is a passionate developer responsible for Frontend and SDK development at Tolgee. He's on a mission to make software localization as easy as pie while keeping it smart. 🧠