@verbumia/realtime

Realtime translation updates for Verbumia. A plugin of your existing @verbumia/react-i18next provider: for dev versions it subscribes to the version's Centrifugo channel and, when a new release is published, bust-refetches the affected bundle and re-renders — no page reload, no redeploy.

This was previously baked into @verbumia/react-i18next core; it was extracted into this package in react-i18next 0.9.0 so realtime is opt-in and the core stays lean.

• @verbumia/realtime/react — the VerbumiaProvider plugin (web/React).
• @verbumia/realtime/core — the framework-agnostic Centrifugo client (LiveClient, fetchCentrifugoToken) for advanced/other-framework use.

MIT.

Install

npm i @verbumia/realtime

react and @verbumia/react-i18next (>= 0.9.0) are peer deps.

Usage (React)

Add verbumiaRealtime(...) to your i18n provider's plugins slot — no second context, no extra config (it reuses the provider's apiBase / projectUuid / token):

import { VerbumiaProvider } from "@verbumia/react-i18next";
import { verbumiaRealtime } from "@verbumia/realtime/react";

<VerbumiaProvider
  token="vrb_live_…"
  projectUuid="<project-uuid>"
  defaultLocale="fr"
  version="main"
  plugins={[
    verbumiaRealtime({
      wsUrl: "wss://centrifugo.verbumia.ca/connection/websocket",
    }),
  ]}
>
  <App />
</VerbumiaProvider>;

verbumiaRealtime accepts:

• wsUrl (required) — the Centrifugo WebSocket URL.
• tokenEndpoint (optional) — defaults to ${apiBase}/v1/auth/centrifugo-token.

Behaviour

Realtime is gated per version (Verbumia product model): on mount the plugin reads the configured version's state from the backend (GET /v1/projects/{id}/versions/{version} → is_dev + realtime_channel):

• dev version (is_dev: true) — mints a version-scoped translations token (POST /v1/auth/centrifugo-token { kind: "translations", version_uuid }) and subscribes to the version's realtime_channel.
• published version (realtime_channel === null) — no subscription; a console.warn explains realtime is dev-only, and bundles are served statically from the CDN.

This is independent of the provider's env flag (which only controls where bundles are fetched). On each translations_published push for a (language_code, namespace_slug) the app already loaded, the plugin calls i18n.reload({ locale, namespace }) — a cache-bypassing refetch + re-render. Connection + token minting are best-effort: a failure logs a console.warn and the SDK keeps serving the last bundle. Teardown cancels any in-flight setup and disposes the client.