i18n-keyless-react 2.1.0 → 2.3.0

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

@@ -1,10 +1,10 @@
 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 { 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

@@ -1,8 +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 { 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

@@ -51,13 +51,51 @@ async function ensureALS() {
  */
 export async function runWithI18nKeyless(scope, fn) {
     await ensureALS();
-    return als ? als.run(scope, fn) : fn();
+    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 = als?.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) {
+    als?.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 = als?.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.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,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
@@ -10,6 +10,14 @@ import { getRequestScope } from "./request-scope.js";
 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();
@@ -120,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) {
@@ -130,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) {
@@ -152,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 });
@@ -246,9 +287,16 @@ export function getSupportedLanguages() {
 export function getTranslation(key, options) {
     const base = useI18nKeyless.getState();
     // Read-only on the server: don't record usage (a render may be a crawler hit).
+    // 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) {
-        base.setTranslationUsage(key, options?.context);
+        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.1.0",
+  "version": "2.3.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.1.0",
+    "i18n-keyless-core": "2.3.0",
     "zustand": "^5.0.3"
   },
   "peerDependencies": {