i18n-keyless-react 1.18.0 → 2.0.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,7 @@
 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";
 const warnAboutWhitespace = (text) => {
     if (process.env.NODE_ENV === "development" && text !== text.trim()) {
         console.warn(`I18nKeylessText received text with leading/trailing whitespace: "${text}". ` +
@@ -8,9 +9,15 @@ 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/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;
     // 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,10 @@
-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 { 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,7 @@
-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 { clearI18nKeylessStorageAndStore } from "./store.js";
 export { AVAILABLE_LANGS, getAllTranslationsFromLanguage, queue } from "i18n-keyless-core";

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,14 @@
 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";
+/**
+ * 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 +198,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 +229,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);
@@ -224,7 +244,10 @@ export function getSupportedLanguages() {
 }
 export function getTranslation(key, options) {
     const store = useI18nKeyless.getState();
-    store.setTranslationUsage(key, options?.context);
+    // 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);
+    }
     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.0.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.0.0",
     "zustand": "^5.0.3"
   },
   "peerDependencies": {