@verbumia/react-i18next 0.7.1 → 0.9.0

package/README.md

@@ -63,8 +63,13 @@ interface VerbumiaConfig {
   defaultLocale: string;          // BCP-47 (e.g. "fr", "fr-CA")
   fallbackLng?: string;           // resolved before reporting a key as missing
   namespaces?: string[];          // default ['common']
-  apiBase?: string;               // default 'https://api.verbumia.ca'
+  defaultNS?: string;             // alias: default namespace for single-ns apps
+  apiBase?: string;               // default 'https://api.verbumia.dev'
   cdnBase?: string;               // default 'https://cdn.verbumia.ca'
+  version?: string;               // version slug, default 'main' (in cache keys)
+  versionSlug?: string;           // @deprecated alias of `version`
+  env?: 'prod' | 'dev';           // default 'prod' (drives fetch source)
+  plugins?: VerbumiaPlugin[];     // e.g. @verbumia/feedback, @verbumia/realtime
   transport?: (batch: MissingKeyEvent[]) => void | Promise<void>;
   missingHandler?: 'send' | 'log' | 'off';   // default 'send'
   flushIntervalMs?: number;       // default 5000
@@ -73,25 +78,58 @@ interface VerbumiaConfig {
 }
 ```
 
+`version` selects which published version's bundles to load
+(`/p/<project>/<version>/latest/...`); it defaults to `'main'` and is part
+of the SDK's bundle cache keys, so two providers with different `version`
+values never share cached bundles. `versionSlug` is a **deprecated** alias
+of `version` (if both are set, `version` wins).
+
+> **Removed in 0.9.0:** the `liveUpdates` / `centrifugoWsUrl` /
+> `centrifugoTokenEndpoint` config keys. Realtime updates now live in the
+> separate [`@verbumia/realtime`](../realtime) plugin (see
+> [Realtime updates](#realtime-updates)). Passing any of those keys throws
+> a clear migration error.
+```
+
 ### `useTranslation(defaultNamespace?)`
 
 Returns `{ t, i18n }`.
 
 ```ts
-type TranslationFunction = (
-  key: string,                                  // "ns:key.path" or "key.path"
-  options?: Record<string, unknown> & { defaultValue?: string }
-) => string;
+// Two call shapes — the native object form AND the react-i18next-style
+// positional fallback (a string 2nd arg is the default value):
+type TranslationFunction = {
+  (key: string, defaultValue: string, options?: Record<string, unknown>): string;
+  (key: string, options?: Record<string, unknown> & { defaultValue?: string }): string;
+};
 
 interface I18nInstance {
   ready: boolean;
   locale: string;
+  language: string;                             // alias of `locale`
   setLocale(next: string): Promise<void>;
+  changeLanguage(next: string): Promise<void>;  // alias of `setLocale`
+  t: TranslationFunction;                       // for out-of-React use via getI18n()
   missingEvents: MissingKeyEvent[];             // newest first, capped buffer
   flushMissing(): Promise<void>;                // force-flush the pending batch
+  reload(opts?: { locale?: string; namespace?: string }): Promise<void>;
 }
 ```
 
+### `i18n.reload(opts?)`
+
+Bust-refetches already-loaded bundles (bypassing the browser HTTP cache)
+and re-renders. Without `opts` it refreshes every loaded `(locale, ns)`
+bundle; pass `{ locale }` and/or `{ namespace }` to narrow. Returns once
+all refetches settle. Useful for a manual "refresh translations" button,
+and it's what [`@verbumia/realtime`](#realtime-updates) calls on a
+`translations_published` push.
+
+```ts
+await getI18n().reload();                                  // refresh all
+await getI18n().reload({ locale: "fr", namespace: "common" });
+```
+
 ### `<Trans>`
 
 Inline translation with JSX slots:
@@ -110,6 +148,41 @@ and the SDK swaps the elements at render time.
 
 ---
 
+## Migrating from react-i18next
+
+`@verbumia/react-i18next` is built to be a near drop-in for react-i18next, so
+existing codebases migrate with minimal changes:
+
+- **Positional default value** — `t('key', 'Default text')` works (so does
+  `t('key', 'Hi {{name}}', { name })`), alongside the native
+  `t('key', { defaultValue })`. No codemod needed for inline fallbacks.
+- **`changeLanguage` / `language`** — `i18n.changeLanguage('en')` (alias of
+  `setLocale`) and the `i18n.language` getter (alias of `locale`) are available.
+- **Out-of-React access** — `getI18n()` returns the active instance for use in
+  plain modules, stores, or helpers (the react-i18next standalone-singleton
+  pattern):
+
+  ```ts
+  import { getI18n } from "@verbumia/react-i18next";
+  // anywhere after <VerbumiaProvider> has mounted:
+  const label = getI18n().t("nav.home", "Home");
+  await getI18n().changeLanguage("en");
+  ```
+
+  `getI18n()` throws a clear error if no provider is mounted yet, and assumes a
+  single app-wide provider.
+- **Default namespace** — the default is `['common']` (not react-i18next's
+  `'translation'`). Migrants pass `namespaces={['translation']}`, or the
+  `defaultNS="translation"` alias for single-namespace apps.
+
+### Not yet supported (planned for V1.1)
+
+Plurals and context are **not** resolved yet: `t('key', { count })` performs
+interpolation only — it does **not** select plural keys (`key_one` /
+`key_other`) or context keys (`key_male`). Handle these manually until V1.1.
+
+---
+
 ## Missing-key flow
 
 1. The user navigates a page that calls `t("hello.title")`.
@@ -171,6 +244,38 @@ import { defaultTransport, logTransport } from "@verbumia/react-i18next";
 
 ---
 
+## Realtime updates
+
+Zero-deploy translation updates (subscribe to the project's Centrifugo
+`translations:` channel and bust-refetch on publish) live in the separate
+[`@verbumia/realtime`](../realtime) package — added as a **plugin** of this
+provider, not configured here:
+
+```tsx
+import { VerbumiaProvider } from "@verbumia/react-i18next";
+import { verbumiaRealtime } from "@verbumia/realtime/react";
+
+<VerbumiaProvider
+  {...config}
+  env="dev"
+  plugins={[
+    verbumiaRealtime({ wsUrl: "wss://centrifugo.verbumia.ca/connection/websocket" }),
+  ]}
+>
+  <App />
+</VerbumiaProvider>;
+```
+
+Under the hood the plugin calls [`i18n.reload(...)`](#i18nreloadopts) on
+each `translations_published` push. Realtime is a dev-version-only feature
+(it only subscribes when `env: "dev"`).
+
+> The `liveUpdates` / `centrifugoWsUrl` / `centrifugoTokenEndpoint` config
+> keys were **removed in 0.9.0**. Install `@verbumia/realtime` and use the
+> plugin instead.
+
+---
+
 ## Recipes
 
 ### Next.js (App Router)

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   Trans: () => Trans,
   VerbumiaProvider: () => VerbumiaProvider,
   defaultTransport: () => defaultTransport,
+  getI18n: () => getI18n,
   keyRegistry: () => keyRegistry,
   logTransport: () => logTransport,
   useTranslation: () => useTranslation
@@ -74,111 +75,6 @@ var logTransport = (batch) => {
   }
 };
 
-// src/live.ts
-var LiveClient = class {
-  constructor(cfg) {
-    this.cfg = cfg;
-  }
-  cfg;
-  _ws = null;
-  _id = 0;
-  _backoffMs = 1e3;
-  _disposed = false;
-  _connectAcked = false;
-  /** Open the socket and try to subscribe. Idempotent — calling twice is a no-op. */
-  async connect() {
-    if (this._ws) return;
-    if (this._disposed) return;
-    this.cfg.onStatus?.("connecting");
-    const token = this.cfg.refreshToken ? await this.cfg.refreshToken() : this.cfg.token;
-    let url = this.cfg.url;
-    if (!url.includes("/connection/websocket")) {
-      url = url.replace(/\/+$/, "") + "/connection/websocket";
-    }
-    const ws = new WebSocket(url);
-    this._ws = ws;
-    this._connectAcked = false;
-    ws.onopen = () => {
-      this._send({ id: ++this._id, connect: { token } });
-    };
-    ws.onmessage = (evt) => this._onFrame(evt.data);
-    ws.onclose = () => this._onClose();
-    ws.onerror = () => {
-    };
-  }
-  dispose() {
-    this._disposed = true;
-    if (this._ws) {
-      try {
-        this._ws.close();
-      } catch {
-      }
-      this._ws = null;
-    }
-    this.cfg.onStatus?.("disconnected");
-  }
-  // ---- internals ----
-  _send(msg) {
-    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
-    try {
-      this._ws.send(JSON.stringify(msg));
-    } catch {
-    }
-  }
-  _onFrame(raw) {
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      return;
-    }
-    if (!parsed || typeof parsed !== "object") return;
-    if (Object.keys(parsed).length === 0) {
-      this._send({});
-      return;
-    }
-    if (parsed.connect && !this._connectAcked) {
-      this._connectAcked = true;
-      this.cfg.onStatus?.("connected");
-      this._backoffMs = 1e3;
-      this._send({
-        id: ++this._id,
-        subscribe: { channel: this.cfg.channel }
-      });
-      return;
-    }
-    const push = parsed.push;
-    if (push && push.channel === this.cfg.channel && push.pub) {
-      this.cfg.onMessage(push.pub.data);
-    }
-  }
-  _onClose() {
-    this._ws = null;
-    this._connectAcked = false;
-    this.cfg.onStatus?.("disconnected");
-    if (this._disposed) return;
-    const delay = this._backoffMs;
-    this._backoffMs = Math.min(this._backoffMs * 2, 3e4);
-    setTimeout(() => {
-      if (!this._disposed) void this.connect();
-    }, delay);
-  }
-};
-async function fetchCentrifugoToken(endpoint, projectUuid, authToken, fetchImpl = fetch) {
-  const r = await fetchImpl(endpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `ApiKey ${authToken}`
-    },
-    body: JSON.stringify({ project_uuid: projectUuid })
-  });
-  if (!r.ok) {
-    throw new Error(`centrifugo-token endpoint ${r.status}: ${await r.text()}`);
-  }
-  return await r.json();
-}
-
 // src/key-registry.ts
 var GLOBAL = "__verbumia_key_registry__";
 var SEP = "\0";
@@ -316,10 +212,10 @@ var VerbumiaI18n = class {
   fallbackLng;
   missingEvents = [];
   _bundles = /* @__PURE__ */ new Map();
-  // `${locale}/${ns}` -> tree
+  // `${version}/${locale}/${ns}` -> tree
   _attempted = /* @__PURE__ */ new Set();
-  // `${locale}/${ns}` keys we've fetched
-  // Tighter gate than `_attempted`: this set only contains (locale, ns)
+  // `${version}/${locale}/${ns}` keys we've fetched
+  // Tighter gate than `_attempted`: this set only contains (version, locale, ns)
   // pairs whose CDN response was 200 with at least one top-level key. An
   // empty bundle (404 → {} OR 200 → {}) is treated as "no data yet";
   // calling t() against a key in such a bundle does NOT fire reportMissing.
@@ -334,13 +230,20 @@ var VerbumiaI18n = class {
   // dedup `${locale}/${ns}/${key}` per-flush
   _timer = null;
   _listeners = /* @__PURE__ */ new Set();
-  _live = null;
   // Stable snapshot reference for useSyncExternalStore. Returning a fresh
   // object on each getSnapshot call would loop React forever — we rebuild
   // it ONLY in _notify (when state actually changed) and return the cached
   // reference between notifications.
   _snapshot;
   constructor(config) {
+    const removedRealtimeKeys = Object.keys(config).filter(
+      (k) => k === "liveUpdates" || k.startsWith("centrifugo")
+    );
+    if (removedRealtimeKeys.length > 0) {
+      throw new Error(
+        `@verbumia/react-i18next: ${removedRealtimeKeys.join(", ")} ${removedRealtimeKeys.length > 1 ? "were" : "was"} removed in 0.9.0 \u2014 realtime is now the @verbumia/realtime plugin. Remove them and pass \`plugins: [verbumiaRealtime({ wsUrl })]\` to <VerbumiaProvider> instead.`
+      );
+    }
     this.locale = config.defaultLocale;
     this.fallbackLng = config.fallbackLng;
     this._config = {
@@ -349,14 +252,11 @@ var VerbumiaI18n = class {
       missingHandler: config.missingHandler ?? "send",
       token: config.token,
       projectUuid: config.projectUuid,
-      namespaces: config.namespaces?.length ? config.namespaces : ["common"],
+      namespaces: config.namespaces?.length ? config.namespaces : config.defaultNS ? [config.defaultNS] : ["common"],
       flushIntervalMs: config.flushIntervalMs ?? DEFAULT_FLUSH_MS,
       flushBatchSize: config.flushBatchSize ?? DEFAULT_BATCH,
       missingEventsBufferSize: config.missingEventsBufferSize ?? DEFAULT_BUFFER,
-      versionSlug: config.versionSlug ?? DEFAULT_VERSION_SLUG,
-      liveUpdates: !!config.liveUpdates,
-      centrifugoTokenEndpoint: config.centrifugoTokenEndpoint ?? `${(config.apiBase ?? DEFAULT_API_BASE).replace(/\/+$/, "")}/v1/auth/centrifugo-token`,
-      centrifugoWsUrl: config.centrifugoWsUrl ?? "",
+      version: config.version ?? config.versionSlug ?? DEFAULT_VERSION_SLUG,
       env: config.env ?? "prod"
     };
     this._transport = config.transport ?? (this._config.missingHandler === "log" ? logTransport : defaultTransport({
@@ -378,11 +278,21 @@ var VerbumiaI18n = class {
     return {
       ready: this.ready,
       locale: this.locale,
+      language: this.locale,
       setLocale: this.setLocale,
+      changeLanguage: this.changeLanguage,
+      t: this.t,
       missingEvents: this.missingEvents,
-      flushMissing: this.flushMissing
+      flushMissing: this.flushMissing,
+      reload: this.reload
     };
   }
+  /** Bundle cache-key builder. Includes `version` so providers with
+   *  different `version` values never share cached bundles. The segments
+   *  (version/locale/ns) are slugs and never contain '/'. */
+  _bundleKey(locale, ns) {
+    return `${this._config.version}/${locale}/${ns}`;
+  }
   _notify() {
     this._snapshot = this._buildSnapshot();
     for (const l of this._listeners) l();
@@ -405,9 +315,6 @@ var VerbumiaI18n = class {
     );
     this.ready = true;
     this._startTimer();
-    if (this._config.liveUpdates && this._config.env === "dev") {
-      this._startLive(fetchImpl);
-    }
     this._notify();
   }
   setLocale = async (next) => {
@@ -421,102 +328,64 @@ var VerbumiaI18n = class {
     this.ready = true;
     this._notify();
   };
+  /** Alias of {@link setLocale} for react-i18next compatibility. */
+  changeLanguage = (next) => this.setLocale(next);
+  /** Alias of {@link locale} for react-i18next compatibility. */
+  get language() {
+    return this.locale;
+  }
   stop() {
     keyRegistry.detach();
     if (this._timer) {
       clearInterval(this._timer);
       this._timer = null;
     }
-    if (this._live) {
-      this._live.dispose();
-      this._live = null;
-    }
   }
   /**
-   * Start the Centrifugo subscription and re-fetch the relevant bundle on
-   * each `translations_published` event. Best-effort: if the WS URL or
-   * token endpoint isn't reachable, we log silently and the SDK continues
-   * to serve the initial bundle.
+   * Bust-refetch already-loaded bundles and re-render once. Generic
+   * replacement for the old realtime-only refetch: iterate the
+   * `_attempted` cache keys (`${version}/${locale}/${ns}`), optionally
+   * filtered by `opts.locale` / `opts.namespace`, and re-pull each one
+   * with `{ bust: true }` so the mutable CDN `latest/` alias bypasses the
+   * HTTP cache. After all settle, `_notify()` once so React re-renders.
+   *
+   * Used by `@verbumia/realtime` on a `translations_published` push and as
+   * a manual refresh hook. If nothing matches, returns without notifying.
    */
-  _startLive(fetchImpl) {
-    const wsUrl = this._config.centrifugoWsUrl;
-    if (!wsUrl) {
-      if (typeof console !== "undefined") {
-        console.warn(
-          "@verbumia/react-i18next: liveUpdates=true but centrifugoWsUrl is empty; skipping subscription."
-        );
-      }
-      return;
+  reload = async (opts = {}) => {
+    const targets = [];
+    for (const key of this._attempted) {
+      const parts = key.split("/");
+      const locale = parts[1];
+      const ns = parts[2];
+      if (!locale || !ns) continue;
+      if (opts.locale && opts.locale !== locale) continue;
+      if (opts.namespace && opts.namespace !== ns) continue;
+      targets.push({ locale, ns });
     }
-    const projectUuid = this._config.projectUuid;
-    const tokenEndpoint = this._config.centrifugoTokenEndpoint;
-    const apiToken = this._config.token;
-    const refreshToken = async () => {
-      const { token } = await fetchCentrifugoToken(
-        tokenEndpoint,
-        projectUuid,
-        apiToken,
-        fetchImpl
-      );
-      return token;
-    };
-    void (async () => {
-      let channel;
-      let token;
-      try {
-        const minted = await fetchCentrifugoToken(
-          tokenEndpoint,
-          projectUuid,
-          apiToken,
-          fetchImpl
-        );
-        channel = minted.channel;
-        token = minted.token;
-      } catch (err) {
-        if (typeof console !== "undefined") {
-          console.warn("@verbumia/react-i18next: live token mint failed", err);
-        }
-        return;
-      }
-      this._live = new LiveClient({
-        url: wsUrl,
-        token,
-        channel,
-        refreshToken,
-        onMessage: (data) => this._onLiveMessage(data, fetchImpl)
-      });
-      void this._live.connect();
-    })();
-  }
-  _onLiveMessage(data, fetchImpl) {
-    if (!data || typeof data !== "object") return;
-    const d = data;
-    if (d.event !== "translations_published") return;
-    const lang = d.language_code;
-    const ns = d.namespace_slug;
-    if (!lang || !ns) return;
-    const cacheKey = `${lang}/${ns}`;
-    if (!this._attempted.has(cacheKey)) return;
-    void this._loadBundle(lang, ns, fetchImpl, { bust: true }).then(() => {
-      this._notify();
-    });
-  }
+    if (targets.length === 0) return;
+    await Promise.all(
+      targets.map((t) => this._loadBundle(t.locale, t.ns, fetch, { bust: true }))
+    );
+    this._notify();
+  };
   // ---- Translation ----
-  t = (key, options) => {
+  t = (key, optionsOrDefault, maybeOptions) => {
+    const options = typeof optionsOrDefault === "string" ? { ...maybeOptions ?? {}, defaultValue: optionsOrDefault } : optionsOrDefault;
     const namespace = this._splitNamespace(key);
     const bareKey = namespace.bareKey;
     const ns = namespace.ns;
-    const fromActive = resolve(this._bundles.get(`${this.locale}/${ns}`), bareKey);
+    const fromActive = resolve(this._bundles.get(this._bundleKey(this.locale, ns)), bareKey);
     if (fromActive != null) {
       return this._render(fromActive, this.locale, options);
     }
     if (this.fallbackLng && this.fallbackLng !== this.locale) {
-      const fb = resolve(this._bundles.get(`${this.fallbackLng}/${ns}`), bareKey);
+      const fb = resolve(this._bundles.get(this._bundleKey(this.fallbackLng, ns)), bareKey);
       if (fb != null) {
         return this._render(fb, this.fallbackLng, options);
       }
     }
-    if (this.ready && this._attempted.has(`${this.locale}/${ns}`) && this._hasContent.has(`${this.locale}/${ns}`)) {
+    if (this.ready && this._attempted.has(this._bundleKey(this.locale, ns)) && this._hasContent.has(this._bundleKey(this.locale, ns))) {
       this._reportMissing({
         key: bareKey,
         namespace: ns,
@@ -563,13 +432,13 @@ var VerbumiaI18n = class {
     return { ns: this._config.namespaces[0], bareKey: key };
   }
   async _loadBundle(locale, ns, fetchImpl = fetch, opts = {}) {
-    const cacheKey = `${locale}/${ns}`;
+    const cacheKey = this._bundleKey(locale, ns);
     let url;
     let init;
     if (this._config.env === "dev") {
       const params = new URLSearchParams({ language: locale, namespace: ns });
-      if (this._config.versionSlug && this._config.versionSlug !== "main") {
-        params.set("version_slug", this._config.versionSlug);
+      if (this._config.version && this._config.version !== "main") {
+        params.set("version_slug", this._config.version);
       }
       url = `${this._config.apiBase.replace(/\/+$/, "")}/v1/projects/${this._config.projectUuid}/translations/runtime?${params.toString()}`;
       init = {
@@ -578,7 +447,7 @@ var VerbumiaI18n = class {
         credentials: "omit"
       };
     } else {
-      url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.versionSlug}/latest/${locale}/${ns}.json`;
+      url = `${this._config.cdnBase.replace(/\/+$/, "")}/p/${this._config.projectUuid}/${this._config.version}/latest/${locale}/${ns}.json`;
       init = { method: "GET", credentials: "omit" };
     }
     if (opts.bust) {
@@ -633,7 +502,7 @@ var VerbumiaI18n = class {
       return options.defaultValue;
     }
     if (this.fallbackLng && this.fallbackLng !== this.locale) {
-      const fb = resolve(this._bundles.get(`${this.fallbackLng}/${ns}`), bareKey);
+      const fb = resolve(this._bundles.get(this._bundleKey(this.fallbackLng, ns)), bareKey);
       if (typeof fb === "string") {
         return fb;
       }
@@ -657,6 +526,23 @@ var VerbumiaI18n = class {
   }
 };
 
+// src/singleton.ts
+var _active = null;
+function _setActiveInstance(instance) {
+  _active = instance;
+}
+function _clearActiveInstance(instance) {
+  if (_active === instance) _active = null;
+}
+function getI18n() {
+  if (!_active) {
+    throw new Error(
+      "@verbumia/react-i18next: getI18n() was called before <VerbumiaProvider> mounted (no active i18n instance)."
+    );
+  }
+  return _active;
+}
+
 // src/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var VerbumiaContext = (0, import_react.createContext)(null);
@@ -666,11 +552,13 @@ function VerbumiaProvider({
 }) {
   const i18n = (0, import_react.useMemo)(() => new VerbumiaI18n(config), []);
   (0, import_react.useEffect)(() => {
+    _setActiveInstance(i18n);
     void i18n.start();
     const teardowns = (config.plugins ?? []).map((p) => p.setup?.({ i18n, config })).filter((t) => typeof t === "function");
     return () => {
       teardowns.forEach((t) => t());
       i18n.stop();
+      _clearActiveInstance(i18n);
     };
   }, [i18n]);
   const value = (0, import_react.useMemo)(() => ({ i18n }), [i18n]);
@@ -702,13 +590,14 @@ function useTranslation(defaultNamespace) {
   renderedRef.current = /* @__PURE__ */ new Set();
   const tokenRef = (0, import_react2.useRef)(/* @__PURE__ */ Symbol("verbumia.t"));
   const t = (0, import_react2.useMemo)(() => {
-    return (key, options) => {
+    const fn = (key, optionsOrDefault, maybeOptions) => {
       const fullKey = defaultNamespace && !key.includes(":") ? `${defaultNamespace}:${key}` : key;
       renderedRef.current.add(
         keyRegistry.encode(fullKey, i18n.defaultNamespace)
       );
-      return i18n.t(fullKey, options);
+      return i18n.t(fullKey, optionsOrDefault, maybeOptions);
     };
+    return fn;
   }, [i18n, defaultNamespace]);
   (0, import_react2.useEffect)(() => {
     keyRegistry._set(tokenRef.current, renderedRef.current);
@@ -764,6 +653,7 @@ function splitOnComponents(text, components) {
   Trans,
   VerbumiaProvider,
   defaultTransport,
+  getI18n,
   keyRegistry,
   logTransport,
   useTranslation