i18n-keyless-react 2.0.0 → 2.1.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

@@ -4,6 +4,8 @@ export { clearI18nKeylessStorage, validateLanguage, createMemoryStorage } from "
 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

@@ -3,5 +3,6 @@ export { init, setCurrentLanguage, useCurrentLanguage, getTranslation, getSuppor
 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.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
@@ -243,11 +244,17 @@ 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);
+    if (!isServerEnv() && !base.config.ssr) {
+        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.1.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.1.0",
     "zustand": "^5.0.3"
   },
   "peerDependencies": {