i18n-keyless-react 1.18.0 → 2.1.0

package/dist/I18nKeylessProvider.d.ts

@@ -0,0 +1,48 @@
+import React from "react";
+import { type Lang, type Translations } from "i18n-keyless-core";
+export interface I18nKeylessContextValue {
+    /**
+     * The language this subtree renders in (typically derived from the URL / Accept-Language).
+     */
+    lang: Lang;
+    /**
+     * The translations map for `lang`, typically produced by `getServerTranslations(lang)`.
+     */
+    translations: Translations;
+}
+/**
+ * Returns the nearest `I18nKeylessProvider` value, or `null` when none is present.
+ * When `null`, `<I18nKeylessText>` falls back to the global zustand store (SPA mode).
+ */
+export declare function useI18nKeylessContext(): I18nKeylessContextValue | null;
+export interface I18nKeylessProviderProps {
+    /**
+     * The language to render in for this subtree (typically from the URL: `/{lang}/...`
+     * or `?lang={lang}`, or from `Accept-Language`).
+     */
+    lang: Lang;
+    /**
+     * The translations map for `lang`. On the server, produce it with
+     * `getServerTranslations(lang)`; serialize it into the HTML and pass the same map
+     * here on the client so the first client render matches the server output.
+     */
+    translations: Translations;
+    children: React.ReactNode;
+}
+/**
+ * Per-request language provider for SSR.
+ *
+ * When present, `<I18nKeylessText>` ("`<T>`") reads `lang` and `translations` from
+ * this context instead of the module-scope store. This is what lets a single server
+ * render produce HTML in a chosen non-primary language without leaking language state
+ * across concurrent requests (the store is a process-wide singleton; the context is
+ * per-render).
+ *
+ * On the client it additionally seeds the global store once on mount, so store-based
+ * consumers (e.g. `useCurrentLanguage`) stay consistent and there is no flash after
+ * hydration.
+ *
+ * In provider mode the language is controlled by the `lang` prop (drive it from the
+ * URL). `setCurrentLanguage` is for non-provider SPA mode. See docs/SSR.md.
+ */
+export declare const I18nKeylessProvider: React.FC<I18nKeylessProviderProps>;

package/dist/I18nKeylessProvider.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect } from "react";
+import { useI18nKeyless } from "./store.js";
+const I18nKeylessContext = createContext(null);
+/**
+ * Returns the nearest `I18nKeylessProvider` value, or `null` when none is present.
+ * When `null`, `<I18nKeylessText>` falls back to the global zustand store (SPA mode).
+ */
+export function useI18nKeylessContext() {
+    return useContext(I18nKeylessContext);
+}
+/**
+ * Per-request language provider for SSR.
+ *
+ * When present, `<I18nKeylessText>` ("`<T>`") reads `lang` and `translations` from
+ * this context instead of the module-scope store. This is what lets a single server
+ * render produce HTML in a chosen non-primary language without leaking language state
+ * across concurrent requests (the store is a process-wide singleton; the context is
+ * per-render).
+ *
+ * On the client it additionally seeds the global store once on mount, so store-based
+ * consumers (e.g. `useCurrentLanguage`) stay consistent and there is no flash after
+ * hydration.
+ *
+ * In provider mode the language is controlled by the `lang` prop (drive it from the
+ * URL). `setCurrentLanguage` is for non-provider SPA mode. See docs/SSR.md.
+ */
+export const I18nKeylessProvider = ({ lang, translations, children }) => {
+    // Client-only (effects don't run during SSR): seed the global store so reads after
+    // hydration match the server-rendered, context-driven output.
+    useEffect(() => {
+        useI18nKeyless.setState((state) => ({
+            currentLanguage: lang,
+            translations: { ...state.translations, ...translations },
+        }));
+    }, [lang, translations]);
+    return _jsx(I18nKeylessContext.Provider, { value: { lang, translations }, children: children });
+};

package/dist/I18nKeylessText.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { useEffect, useMemo } from "react";
-import { useI18nKeyless, getTranslation } from "./store";
+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}". ` +
@@ -8,9 +10,16 @@ const warnAboutWhitespace = (text) => {
     }
 };
 export const I18nKeylessText = ({ children, replace, context, debug = false, forceTemporary }) => {
-    const translations = useI18nKeyless((store) => store.translations);
-    const currentLanguage = useI18nKeyless((store) => store.currentLanguage);
+    const storeTranslations = useI18nKeyless((store) => store.translations);
+    const storeCurrentLanguage = useI18nKeyless((store) => store.currentLanguage);
     const config = useI18nKeyless((store) => store.config);
+    // 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,6 +1,12 @@
-export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText";
-export { init, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store";
-export { clearI18nKeylessStorage, validateLanguage } from "./utils";
-export type { I18nKeylessTextProps } from "./I18nKeylessText";
-export { type I18nConfig, type TranslationStoreState, type TranslationOptions, type TranslationStore } from "./types";
+export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText.tsx";
+export { init, 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";
 export { AVAILABLE_LANGS, type Lang, type PrimaryLang, type Translations, type I18nKeylessRequestBody, type I18nKeylessResponse, getAllTranslationsFromLanguage, queue } from "i18n-keyless-core";

package/dist/index.js

@@ -1,4 +1,8 @@
-export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText";
-export { init, setCurrentLanguage, useCurrentLanguage, getTranslation, getSupportedLanguages, useI18nKeyless } from "./store";
-export { clearI18nKeylessStorage, validateLanguage } from "./utils";
+export { I18nKeylessText, I18nKeylessText as T } from "./I18nKeylessText.js";
+export { init, 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/server.d.ts

@@ -0,0 +1,18 @@
+import { type Lang, type Translations } from "i18n-keyless-core";
+/**
+ * Fetches the translations map for `lang` on the server, cached per process.
+ *
+ * Pass the result to `<I18nKeylessProvider lang={lang} translations={...}>` and
+ * serialize it into the HTML so the client can hydrate without a flash.
+ *
+ * Requires `init()` to have been called first (so the store holds API config). Returns
+ * an empty map for the primary language (no translation needed) and on fetch failure.
+ *
+ * See docs/SSR.md.
+ */
+export declare function getServerTranslations(lang: Lang): Promise<Translations>;
+/**
+ * Clears the per-process server translations cache. Pass a `lang` to evict a single
+ * language, or omit it to clear everything (e.g. after publishing new translations).
+ */
+export declare function clearServerTranslationsCache(lang?: Lang): void;

package/dist/server.js

@@ -0,0 +1,49 @@
+import { getAllTranslationsFromLanguage } from "i18n-keyless-core";
+import { useI18nKeyless } from "./store.js";
+/**
+ * Process-wide cache of translations per language.
+ *
+ * Translations for a given language are identical for every request, so they are
+ * global, cacheable data — only the *choice* of language is per-request. Caching here
+ * means each language is fetched at most once per server process. A process restart /
+ * redeploy naturally picks up new translations.
+ */
+const cache = new Map();
+/**
+ * Fetches the translations map for `lang` on the server, cached per process.
+ *
+ * Pass the result to `<I18nKeylessProvider lang={lang} translations={...}>` and
+ * serialize it into the HTML so the client can hydrate without a flash.
+ *
+ * Requires `init()` to have been called first (so the store holds API config). Returns
+ * an empty map for the primary language (no translation needed) and on fetch failure.
+ *
+ * See docs/SSR.md.
+ */
+export async function getServerTranslations(lang) {
+    const store = useI18nKeyless.getState();
+    if (lang === store.config.languages.primary) {
+        return {};
+    }
+    const cached = cache.get(lang);
+    if (cached) {
+        return cached;
+    }
+    // lastRefresh: null forces a full fetch of the language.
+    const response = await getAllTranslationsFromLanguage(lang, { ...store, lastRefresh: null });
+    const translations = response?.ok ? response.data.translations : {};
+    cache.set(lang, translations);
+    return translations;
+}
+/**
+ * Clears the per-process server translations cache. Pass a `lang` to evict a single
+ * language, or omit it to clear everything (e.g. after publishing new translations).
+ */
+export function clearServerTranslationsCache(lang) {
+    if (lang) {
+        cache.delete(lang);
+    }
+    else {
+        cache.clear();
+    }
+}

package/dist/store.d.ts

@@ -1,5 +1,5 @@
 import { type Lang, type TranslationOptions } from "i18n-keyless-core";
-import { type I18nConfig, type TranslationStore } from "./types";
+import { type I18nConfig, type TranslationStore } from "./types.ts";
 export declare const useI18nKeyless: import("zustand").UseBoundStore<import("zustand").StoreApi<TranslationStore>>;
 /**
  * Initializes the i18n configuration with defaults and validation

package/dist/store.js

@@ -1,6 +1,15 @@
 import { queue, getAllTranslationsFromLanguage, getTranslationCore, sendTranslationsUsageToI18nKeyless, } from "i18n-keyless-core";
 import { create } from "zustand";
-import { storeKeys, setItem, getItem, clearI18nKeylessStorage, validateLanguage } from "./utils";
+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
+ * the environment can be detected (and stubbed in tests) per call. See docs/SSR.md.
+ */
+function isServerEnv() {
+    return typeof window === "undefined";
+}
 queue.on("empty", () => {
     // when each word is translated, fetch the translations for the current language
     const store = useI18nKeyless.getState();
@@ -190,8 +199,16 @@ export async function init(newConfig) {
         newConfig.languages.supported.push(newConfig.languages.initWithDefault);
     }
     if (!newConfig.storage) {
-        console.log("storage is required", newConfig.storage);
-        throw new Error("i18n-keyless: storage is required. You can use react-native-mmkv, @react-native-async-storage/async-storage, or window.localStorage, or any storage that has a getItem, setItem, removeItem, or get, set, and remove method");
+        if (typeof window === "undefined") {
+            // Server-side (SSR): no DOM storage exists. Default to an in-memory adapter so
+            // the server can init and cache translations for the process lifetime, instead
+            // of throwing. See docs/SSR.md.
+            newConfig.storage = createMemoryStorage();
+        }
+        else {
+            console.log("storage is required", newConfig.storage);
+            throw new Error("i18n-keyless: storage is required. You can use react-native-mmkv, @react-native-async-storage/async-storage, or window.localStorage, or any storage that has a getItem, setItem, removeItem, or get, set, and remove method");
+        }
     }
     if (!newConfig.getAllTranslations || !newConfig.handleTranslate) {
         if (!newConfig.API_KEY) {
@@ -213,7 +230,11 @@ export async function init(newConfig) {
     newConfig.onInit?.(currentLanguage);
     // initialize the language to fetch all the translations
     useI18nKeyless.getState().setLanguage(currentLanguage);
-    useI18nKeyless.getState().sendTranslationsUsage();
+    // Read-only on the server: don't POST usage stats on boot (crawler-triggered renders
+    // and serverless per-request inits would otherwise pollute/spam the prune signal).
+    if (!isServerEnv() && !newConfig.ssr) {
+        useI18nKeyless.getState().sendTranslationsUsage();
+    }
 }
 export function useCurrentLanguage() {
     const currentLanguage = useI18nKeyless((state) => state.currentLanguage);
@@ -223,8 +244,17 @@ export function getSupportedLanguages() {
     return useI18nKeyless.getState().config.languages.supported;
 }
 export function getTranslation(key, options) {
-    const store = useI18nKeyless.getState();
-    store.setTranslationUsage(key, options?.context);
+    const base = useI18nKeyless.getState();
+    // Read-only on the server: don't record usage (a render may be a crawler hit).
+    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/dist/types.d.ts

@@ -48,6 +48,18 @@ export interface I18nConfig {
      * if true, all the logs will be displayed in the console
      */
     debug?: boolean;
+    /**
+     * Read-only mode for server-side rendering.
+     *
+     * When the lib runs on a server (no `window`) it is automatically treated as
+     * read-only: usage analytics are not sent and not recorded (a server render can be
+     * triggered by a crawler, which would pollute the prune signal, and serverless
+     * per-request inits would POST on every request). Set `ssr: true` to force this
+     * read-only behavior explicitly even in an environment where `window` exists.
+     *
+     * This does NOT affect translate-on-miss — missing keys are still requested. See docs/SSR.md.
+     */
+    ssr?: boolean;
     /**
      * called everytime the language is set, maybe to set also the locale to dayjs or whatever
      */

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { I18nConfig } from "./types";
+import type { I18nConfig } from "./types.ts";
 /**
  * The keys used to store i18n-keyless data in storage
  */
@@ -37,6 +37,19 @@ export declare function deleteItem(key: string, storage: I18nConfig["storage"]):
  * @param storage - The storage implementation to clear
  */
 export declare function clearI18nKeylessStorage(storage: I18nConfig["storage"]): Promise<void>;
+/**
+ * Creates an in-memory storage adapter backed by a Map.
+ *
+ * Used as the default storage on the server (when `typeof window === "undefined"`
+ * and no `storage` is provided to `init`). It satisfies the storage interface and
+ * keeps translations cached for the lifetime of the process, so a long-lived server
+ * fetches each language at most once per boot. It does NOT persist across restarts —
+ * which is the correct, expected behavior server-side.
+ *
+ * On the browser, a missing `storage` remains a loud error (a real misconfiguration),
+ * so this is intentionally not used as a client default.
+ */
+export declare function createMemoryStorage(): NonNullable<I18nConfig["storage"]>;
 /**
  * Validates the language against the supported languages
  * @param lang - The language to validate

package/dist/utils.js

@@ -100,6 +100,33 @@ export async function clearI18nKeylessStorage(storage) {
         deleteItem(key, storage);
     }
 }
+/**
+ * Creates an in-memory storage adapter backed by a Map.
+ *
+ * Used as the default storage on the server (when `typeof window === "undefined"`
+ * and no `storage` is provided to `init`). It satisfies the storage interface and
+ * keeps translations cached for the lifetime of the process, so a long-lived server
+ * fetches each language at most once per boot. It does NOT persist across restarts —
+ * which is the correct, expected behavior server-side.
+ *
+ * On the browser, a missing `storage` remains a loud error (a real misconfiguration),
+ * so this is intentionally not used as a client default.
+ */
+export function createMemoryStorage() {
+    const map = new Map();
+    return {
+        getItem: (key) => map.get(key) ?? null,
+        setItem: (key, value) => {
+            map.set(key, value);
+        },
+        removeItem: (key) => {
+            map.delete(key);
+        },
+        clear: () => {
+            map.clear();
+        },
+    };
+}
 /**
  * Validates the language against the supported languages
  * @param lang - The language to validate

package/package.json

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