i18n-keyless-react 2.0.0 → 2.2.0

package/dist/I18nKeylessText.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import React, { useEffect, useMemo } from "react";
 import { useI18nKeyless, getTranslation } from "./store.js";
 import { useI18nKeylessContext } from "./I18nKeylessProvider.js";
+import { getRequestScope } from "./request-scope.js";
 const warnAboutWhitespace = (text) => {
     if (process.env.NODE_ENV === "development" && text !== text.trim()) {
         console.warn(`I18nKeylessText received text with leading/trailing whitespace: "${text}". ` +
@@ -12,12 +13,13 @@ export const I18nKeylessText = ({ children, replace, context, debug = false, for
     const storeTranslations = useI18nKeyless((store) => store.translations);
     const storeCurrentLanguage = useI18nKeyless((store) => store.currentLanguage);
     const config = useI18nKeyless((store) => store.config);
-    // In SSR/provider mode, the language and translations come from the per-request
-    // context (so concurrent requests don't share state). Otherwise (SPA mode) they come
-    // from the global store. See docs/SSR.md.
-    const providerContext = useI18nKeylessContext();
-    const translations = providerContext?.translations ?? storeTranslations;
-    const currentLanguage = providerContext?.lang ?? storeCurrentLanguage;
+    // In SSR mode, language and translations come from the per-request scope so concurrent
+    // requests don't share state: the React-context provider first, then the
+    // AsyncLocalStorage request scope (set by runWithI18nKeyless). Otherwise (SPA mode)
+    // both are absent and we use the global store. See docs/SSR.md.
+    const requestScope = useI18nKeylessContext() ?? getRequestScope();
+    const translations = requestScope?.translations ?? storeTranslations;
+    const currentLanguage = requestScope?.lang ?? storeCurrentLanguage;
     // Trim the source text immediately
     const rawText = Array.isArray(children) ? children.join("") : String(children ?? "");
     const sourceText = rawText.trim();

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText.tsx";
-export { init, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store.ts";
+export { init, hydrateFromServer, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store.ts";
 export { clearI18nKeylessStorage, validateLanguage, createMemoryStorage } from "./utils.ts";
 export { I18nKeylessProvider, useI18nKeylessContext } from "./I18nKeylessProvider.tsx";
 export type { I18nKeylessProviderProps } from "./I18nKeylessProvider.tsx";
 export { getServerTranslations, clearServerTranslationsCache } from "./server.ts";
+export { runWithI18nKeyless, getRequestScope } from "./request-scope.ts";
+export type { I18nRequestScope } from "./request-scope.ts";
 export { clearI18nKeylessStorageAndStore } from "./store.ts";
 export type { I18nKeylessTextProps } from "./I18nKeylessText.tsx";
 export { type I18nConfig, type TranslationStoreState, type TranslationOptions, type TranslationStore } from "./types.ts";

package/dist/index.js

@@ -1,7 +1,8 @@
 export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText.js";
-export { init, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store.js";
+export { init, hydrateFromServer, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store.js";
 export { clearI18nKeylessStorage, validateLanguage, createMemoryStorage } from "./utils.js";
 export { I18nKeylessProvider, useI18nKeylessContext } from "./I18nKeylessProvider.js";
 export { getServerTranslations, clearServerTranslationsCache } from "./server.js";
+export { runWithI18nKeyless, getRequestScope } from "./request-scope.js";
 export { clearI18nKeylessStorageAndStore } from "./store.js";
 export { AVAILABLE_LANGS, getAllTranslationsFromLanguage, queue } from "i18n-keyless-core";

package/dist/request-scope.d.ts

@@ -0,0 +1,36 @@
+import type { Lang, Translations } from "i18n-keyless-core";
+/**
+ * Per-request translation scope for SSR.
+ *
+ * Set by `runWithI18nKeyless` and read by both `getTranslation(...)` and
+ * `<I18nKeylessText>` so a single server render resolves in `lang` using `translations`,
+ * without touching the process-global store and without leaking across concurrent
+ * requests. See docs/SSR.md.
+ */
+export interface I18nRequestScope {
+    lang: Lang;
+    translations: Translations;
+}
+/**
+ * Runs `fn` with a per-request translation scope active. Every `getTranslation(...)`
+ * call and every `<I18nKeylessText>` rendered within `fn` — synchronously OR across
+ * `await`s/streaming — resolves in `scope.lang` using `scope.translations`, with no
+ * change to the global store and full isolation between concurrent requests.
+ *
+ * Wrap your server render in it and await the result:
+ *
+ *   const html = await runWithI18nKeyless(
+ *     { lang, translations },
+ *     () => renderToString(<App />)
+ *   );
+ *
+ * Server-only. In the browser (or where AsyncLocalStorage is unavailable) it simply
+ * calls `fn` with no scoping. See docs/SSR.md.
+ */
+export declare function runWithI18nKeyless<R>(scope: I18nRequestScope, fn: () => R): Promise<R>;
+/**
+ * Returns the active per-request scope, or `undefined` when none is set (browser, or
+ * outside `runWithI18nKeyless`). Read internally by `getTranslation` and
+ * `<I18nKeylessText>`; exported for advanced/server use.
+ */
+export declare function getRequestScope(): I18nRequestScope | undefined;

package/dist/request-scope.js

@@ -0,0 +1,63 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// A single AsyncLocalStorage instance, created lazily on the server only. Each
+// `run()` creates an isolated store, so the instance is correctly a module singleton.
+let als;
+let alsInit;
+async function ensureALS() {
+    // Browser: no request scoping (single user → the store is correct). Also avoids
+    // pulling a Node builtin into client bundles.
+    if (als || typeof window !== "undefined") {
+        return;
+    }
+    if (!alsInit) {
+        alsInit = (async () => {
+            try {
+                // Variable specifier + ignore hints keep bundlers from trying to resolve a Node
+                // builtin into the browser graph. tsc keeps these comments (removeComments=false).
+                const specifier = "node:async_hooks";
+                const mod = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ /* webpackIgnore: true */ specifier)));
+                als = new mod.AsyncLocalStorage();
+            }
+            catch {
+                // AsyncLocalStorage unavailable (e.g. some edge runtimes). Scoping degrades to a
+                // no-op and getTranslation/<T> fall back to the global store. See docs/SSR.md.
+            }
+        })();
+    }
+    await alsInit;
+}
+/**
+ * Runs `fn` with a per-request translation scope active. Every `getTranslation(...)`
+ * call and every `<I18nKeylessText>` rendered within `fn` — synchronously OR across
+ * `await`s/streaming — resolves in `scope.lang` using `scope.translations`, with no
+ * change to the global store and full isolation between concurrent requests.
+ *
+ * Wrap your server render in it and await the result:
+ *
+ *   const html = await runWithI18nKeyless(
+ *     { lang, translations },
+ *     () => renderToString(<App />)
+ *   );
+ *
+ * Server-only. In the browser (or where AsyncLocalStorage is unavailable) it simply
+ * calls `fn` with no scoping. See docs/SSR.md.
+ */
+export async function runWithI18nKeyless(scope, fn) {
+    await ensureALS();
+    return als ? als.run(scope, fn) : fn();
+}
+/**
+ * Returns the active per-request scope, or `undefined` when none is set (browser, or
+ * outside `runWithI18nKeyless`). Read internally by `getTranslation` and
+ * `<I18nKeylessText>`; exported for advanced/server use.
+ */
+export function getRequestScope() {
+    return als?.getStore();
+}

package/dist/store.d.ts

@@ -1,6 +1,21 @@
-import { type Lang, type TranslationOptions } from "i18n-keyless-core";
+import { type Lang, type Translations, type TranslationOptions } from "i18n-keyless-core";
 import { type I18nConfig, type TranslationStore } from "./types.ts";
 export declare const useI18nKeyless: import("zustand").UseBoundStore<import("zustand").StoreApi<TranslationStore>>;
+/**
+ * Synchronously seeds the store from a server snapshot, BEFORE React's first client
+ * render, so the imperative `getTranslation(key)` returns the correct language on the
+ * very first render — no hydration mismatch, no blink. Call it in your client entry,
+ * before `hydrateRoot`, with the `{ lang, translations }` the server serialized into the
+ * HTML (the server can read it from `getRequestScope()`).
+ *
+ * The component path (`<I18nKeylessText>`) is covered by `<I18nKeylessProvider>`; the
+ * function path needs this synchronous store seed because a plain function cannot read
+ * React context. Server-only async `hydrate()` will not overwrite this seed. See docs/SSR.md.
+ */
+export declare function hydrateFromServer(snapshot?: {
+    lang?: Lang;
+    translations?: Translations;
+}): void;
 /**
  * Initializes the i18n configuration with defaults and validation
  * @param newConfig - The configuration object to initialize

package/dist/store.js

@@ -1,6 +1,7 @@
 import { queue, getAllTranslationsFromLanguage, getTranslationCore, sendTranslationsUsageToI18nKeyless, } from "i18n-keyless-core";
 import { create } from "zustand";
 import { storeKeys, setItem, getItem, clearI18nKeylessStorage, validateLanguage, createMemoryStorage } from "./utils.js";
+import { getRequestScope } from "./request-scope.js";
 /**
  * True when running without a DOM (server-side rendering). On the server the lib is
  * read-only: usage analytics are neither recorded nor sent. Evaluated at call time so
@@ -9,6 +10,14 @@ import { storeKeys, setItem, getItem, clearI18nKeylessStorage, validateLanguage,
 function isServerEnv() {
     return typeof window === "undefined";
 }
+/**
+ * True once a server snapshot has been applied synchronously on the client (via
+ * `hydrateFromServer`). When set, the async `hydrate()` treats the snapshot as
+ * authoritative for the current request and does not overwrite the seeded language /
+ * translations from storage (which may hold a different, stale language). Never set in
+ * SPA mode, so SPA hydration is unchanged. See docs/SSR.md.
+ */
+let serverSnapshotApplied = false;
 queue.on("empty", () => {
     // when each word is translated, fetch the translations for the current language
     const store = useI18nKeyless.getState();
@@ -119,6 +128,28 @@ export const useI18nKeyless = create((set, get) => ({
         }
     },
 }));
+/**
+ * Synchronously seeds the store from a server snapshot, BEFORE React's first client
+ * render, so the imperative `getTranslation(key)` returns the correct language on the
+ * very first render — no hydration mismatch, no blink. Call it in your client entry,
+ * before `hydrateRoot`, with the `{ lang, translations }` the server serialized into the
+ * HTML (the server can read it from `getRequestScope()`).
+ *
+ * The component path (`<I18nKeylessText>`) is covered by `<I18nKeylessProvider>`; the
+ * function path needs this synchronous store seed because a plain function cannot read
+ * React context. Server-only async `hydrate()` will not overwrite this seed. See docs/SSR.md.
+ */
+export function hydrateFromServer(snapshot) {
+    if (!snapshot?.lang) {
+        return;
+    }
+    serverSnapshotApplied = true;
+    const current = useI18nKeyless.getState();
+    useI18nKeyless.setState({
+        currentLanguage: snapshot.lang,
+        translations: { ...current.translations, ...(snapshot.translations ?? {}) },
+    });
+}
 async function hydrate() {
     const config = useI18nKeyless.getState().config;
     if (!config.API_KEY) {
@@ -129,15 +160,21 @@ async function hydrate() {
     if (!storage) {
         throw new Error(`i18n-keyless: storage is not initialized hydrating`);
     }
-    const translations = await getItem(storeKeys.translations, storage, JSON.parse);
-    if (translations) {
-        if (debug)
-            console.log("i18n-keyless: _hydrate", translations);
-        useI18nKeyless.setState({ translations: translations });
-    }
-    else {
-        if (debug)
-            console.log("i18n-keyless: _hydrate: no translations");
+    // When a server snapshot was applied, it is authoritative for the current request's
+    // language: skip loading translations / currentLanguage from storage (storage holds a
+    // single, possibly different/stale language and would clobber or mix the seed). Usage,
+    // uniqueId and lastRefresh are language-independent and still hydrate normally.
+    if (!serverSnapshotApplied) {
+        const translations = await getItem(storeKeys.translations, storage, JSON.parse);
+        if (translations) {
+            if (debug)
+                console.log("i18n-keyless: _hydrate", translations);
+            useI18nKeyless.setState({ translations: translations });
+        }
+        else {
+            if (debug)
+                console.log("i18n-keyless: _hydrate: no translations");
+        }
     }
     const translationsUsage = await getItem(storeKeys.translationsUsage, storage, JSON.parse);
     if (translationsUsage) {
@@ -151,7 +188,12 @@ async function hydrate() {
     }
     const currentLanguage = await getItem(storeKeys.currentLanguage, storage);
     const skipCurrentLanguageHydration = config.languages.skipCurrentLanguageHydration;
-    if (skipCurrentLanguageHydration) {
+    if (serverSnapshotApplied) {
+        // keep the synchronously-seeded language; do not override it from storage
+        if (debug)
+            console.log("i18n-keyless: _hydrate: keeping server-seeded language");
+    }
+    else if (skipCurrentLanguageHydration) {
         if (debug)
             console.log("i18n-keyless: _hydrate: skip current language hydration");
         useI18nKeyless.setState({ currentLanguage: config?.languages.initWithDefault });
@@ -243,11 +285,21 @@ export function getSupportedLanguages() {
     return useI18nKeyless.getState().config.languages.supported;
 }
 export function getTranslation(key, options) {
-    const store = useI18nKeyless.getState();
+    const base = useI18nKeyless.getState();
     // Read-only on the server: don't record usage (a render may be a crawler hit).
-    if (!isServerEnv() && !store.config.ssr) {
-        store.setTranslationUsage(key, options?.context);
+    // On the client, DEFER the usage write: getTranslation is called during component
+    // render, and setTranslationUsage writes to the store synchronously, which makes React
+    // log "Cannot update a component while rendering a different component". Usage analytics
+    // never needs to affect the current render, so flush it on a microtask (after render).
+    if (!isServerEnv() && !base.config.ssr) {
+        queueMicrotask(() => base.setTranslationUsage(key, options?.context));
     }
+    // SSR: if a per-request scope is active (set by runWithI18nKeyless), translate against
+    // that request's language/translations instead of the process-global store — so
+    // getTranslation, like <T>, renders the right language without leaking across
+    // concurrent requests. No scope (SPA / outside a scoped render) → use the store as-is.
+    const scope = getRequestScope();
+    const store = scope ? { ...base, currentLanguage: scope.lang, translations: scope.translations } : base;
     return getTranslationCore(key, store, options);
 }
 export function setCurrentLanguage(lang) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18n-keyless-react",
   "private": false,
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,7 +24,7 @@
     "postpublish": "rm -rf ./dist && rm *.tgz"
   },
   "dependencies": {
-    "i18n-keyless-core": "2.0.0",
+    "i18n-keyless-core": "2.2.0",
     "zustand": "^5.0.3"
   },
   "peerDependencies": {