i18n-keyless-react 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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";

package/dist/index.js

@@ -1,5 +1,5 @@
 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";

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

@@ -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,8 +287,12 @@ 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));
     }
     // 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

package/package.json

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