i18n-keyless-react 2.2.0 → 2.3.1

package/dist/I18nKeylessText.js

@@ -2,7 +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";
+import { getRequestScope, recordUsedKey } 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}". ` +
@@ -29,9 +29,11 @@ export const I18nKeylessText = ({ children, replace, context, debug = false, for
     useEffect(() => {
         getTranslation(sourceText, { context, debug, forceTemporary });
     }, [sourceText, currentLanguage, context, debug, forceTemporary]);
-    const translatedText = currentLanguage === config.languages.primary
-        ? sourceText
-        : translations[context ? `${sourceText}__${context}` : sourceText] || sourceText;
+    const storageKey = context ? `${sourceText}__${context}` : sourceText;
+    // Record the key for the per-page SSR snapshot (no-op off-server; pure Set.add, no
+    // setState, so no render-time update warning). See docs/SSR.md.
+    recordUsedKey(storageKey);
+    const translatedText = currentLanguage === config.languages.primary ? sourceText : translations[storageKey] || sourceText;
     const finalText = useMemo(() => {
         if (!replace) {
             return translatedText;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ 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 { runWithI18nKeyless, getRequestScope, getUsedTranslationsSnapshot } from "./request-scope.ts";
 export type { I18nRequestScope } from "./request-scope.ts";
 export { clearI18nKeylessStorageAndStore } from "./store.ts";
 export type { I18nKeylessTextProps } from "./I18nKeylessText.tsx";

package/dist/index.js

@@ -3,6 +3,6 @@ export { init, hydrateFromServer, setCurrentLanguage, useCurrentLanguage, getTra
 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 { runWithI18nKeyless, getRequestScope, getUsedTranslationsSnapshot } from "./request-scope.js";
 export { clearI18nKeylessStorageAndStore } from "./store.js";
 export { AVAILABLE_LANGS, getAllTranslationsFromLanguage, queue } from "i18n-keyless-core";

package/dist/request-scope.d.ts

@@ -29,8 +29,27 @@ export interface I18nRequestScope {
  */
 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.
+ * Returns the active per-request scope (`{ lang, translations }` with the FULL set
+ * available for resolution), 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;
+/**
+ * Records that `key` (the storage key, i.e. `key` or `key__context`) was used in the
+ * current render. No-op outside a `runWithI18nKeyless` scope (browser / SPA). Pure
+ * `Set.add` — no store write, no setState. Internal: called by `getTranslation` and
+ * `<I18nKeylessText>`.
+ */
+export declare function recordUsedKey(key: string): void;
+/**
+ * Returns a snapshot containing ONLY the keys used during the current render (∩ the keys
+ * actually available in the scope's translations), for serializing a per-page subset into
+ * the SSR HTML instead of the full language set. Use it at the serialization site in
+ * place of `getRequestScope()` when the language set is large.
+ *
+ * The full set is still used for resolution during render; only the serialized snapshot is
+ * narrowed. Pair it with `init()`'s background full fetch on the client so subsequent
+ * client-side navigation has every key. Returns `undefined` outside a scope. See docs/SSR.md.
+ */
+export declare function getUsedTranslationsSnapshot(): I18nRequestScope | undefined;

package/dist/request-scope.js

@@ -7,23 +7,36 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     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;
+// `run()` creates an isolated store, so the instance is correctly a process singleton.
+//
+// CRITICAL: the instance is stored on `globalThis` under a `Symbol.for(...)` key, NOT in a
+// module-level variable. Bundlers that build separate server-entry and SSR-render
+// environments (e.g. TanStack Start / Vite SSR) instantiate this package more than once in
+// the same process. With a module-local `als`, `runWithI18nKeyless` (called from the server
+// entry) would set `als` on copy A, while `getRequestScope`/`recordUsedKey` (called during
+// the React render) would read copy B's `als` — `undefined` — and SSR would silently fall
+// back to the primary language with a hydration mismatch. Routing every read and write
+// through the shared `globalThis` slot guarantees all module copies use ONE ALS.
+const ALS_KEY = Symbol.for("i18n-keyless.als");
+const ALS_INIT_KEY = Symbol.for("i18n-keyless.alsInit");
+const registry = globalThis;
+function getAls() {
+    return registry[ALS_KEY];
+}
 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") {
+    if (registry[ALS_KEY] || typeof window !== "undefined") {
         return;
     }
-    if (!alsInit) {
-        alsInit = (async () => {
+    if (!registry[ALS_INIT_KEY]) {
+        registry[ALS_INIT_KEY] = (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();
+                registry[ALS_KEY] = new mod.AsyncLocalStorage();
             }
             catch {
                 // AsyncLocalStorage unavailable (e.g. some edge runtimes). Scoping degrades to a
@@ -31,7 +44,7 @@ async function ensureALS() {
             }
         })();
     }
-    await alsInit;
+    await registry[ALS_INIT_KEY];
 }
 /**
  * Runs `fn` with a per-request translation scope active. Every `getTranslation(...)`
@@ -51,13 +64,52 @@ async function ensureALS() {
  */
 export async function runWithI18nKeyless(scope, fn) {
     await ensureALS();
-    return als ? als.run(scope, fn) : fn();
+    const als = getAls();
+    if (!als) {
+        return fn();
+    }
+    // Each run gets its own `used` Set, isolated to this request's async context.
+    return als.run({ lang: scope.lang, translations: scope.translations, used: new Set() }, 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.
+ * Returns the active per-request scope (`{ lang, translations }` with the FULL set
+ * available for resolution), 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();
+    const s = getAls()?.getStore();
+    return s ? { lang: s.lang, translations: s.translations } : undefined;
+}
+/**
+ * Records that `key` (the storage key, i.e. `key` or `key__context`) was used in the
+ * current render. No-op outside a `runWithI18nKeyless` scope (browser / SPA). Pure
+ * `Set.add` — no store write, no setState. Internal: called by `getTranslation` and
+ * `<I18nKeylessText>`.
+ */
+export function recordUsedKey(key) {
+    getAls()?.getStore()?.used.add(key);
+}
+/**
+ * Returns a snapshot containing ONLY the keys used during the current render (∩ the keys
+ * actually available in the scope's translations), for serializing a per-page subset into
+ * the SSR HTML instead of the full language set. Use it at the serialization site in
+ * place of `getRequestScope()` when the language set is large.
+ *
+ * The full set is still used for resolution during render; only the serialized snapshot is
+ * narrowed. Pair it with `init()`'s background full fetch on the client so subsequent
+ * client-side navigation has every key. Returns `undefined` outside a scope. See docs/SSR.md.
+ */
+export function getUsedTranslationsSnapshot() {
+    const s = getAls()?.getStore();
+    if (!s) {
+        return undefined;
+    }
+    const translations = {};
+    for (const key of s.used) {
+        if (key in s.translations) {
+            translations[key] = s.translations[key];
+        }
+    }
+    return { lang: s.lang, translations };
 }

package/dist/store.js

@@ -1,7 +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";
+import { getRequestScope, recordUsedKey } 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
@@ -294,6 +294,9 @@ export function getTranslation(key, options) {
     if (!isServerEnv() && !base.config.ssr) {
         queueMicrotask(() => base.setTranslationUsage(key, options?.context));
     }
+    // Record the key for the per-page SSR snapshot (no-op off-server). Pure Set.add — no
+    // store write. Use the storage key (with context) so it matches the translations map.
+    recordUsedKey(options?.context ? `${key}__${options.context}` : key);
     // 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18n-keyless-react",
   "private": false,
-  "version": "2.2.0",
+  "version": "2.3.1",
   "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.2.0",
+    "i18n-keyless-core": "2.3.1",
     "zustand": "^5.0.3"
   },
   "peerDependencies": {