i18n-keyless-core 2.3.2 → 2.4.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AVAILABLE_LANGS } from "./types.ts";
+export { AVAILABLE_LANGS, DEFAULT_NAMESPACE } from "./types.ts";
 export type { Lang, PrimaryLang, Translations, TranslationsUsage, HandleTranslateFunction, GetAllTranslationsFunction, SendTranslationsUsageFunction, GetAllTranslationsForAllLanguagesFunction, LanguagesConfig, LastRefresh, UniqueId, I18nKeylessRequestBody, I18nKeylessResponse, I18nKeylessTranslationsUsageRequestBody, I18nKeylessAllTranslationsResponse, FetchTranslationParams, TranslationOptions } from "./types.ts";
-export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, queue } from "./service.ts";
+export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, queue } from "./service.ts";
 export { api } from "./api.ts";

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AVAILABLE_LANGS } from "./types.js";
-export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, queue } from "./service.js";
+export { AVAILABLE_LANGS, DEFAULT_NAMESPACE } from "./types.js";
+export { getTranslationCore, getAllTranslationsFromLanguage, sendTranslationsUsageToI18nKeyless, getNamespacesToFetchAfterTranslationFinished, resolveNamespace, queue } from "./service.js";
 export { api } from "./api.js";

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "i18n-keyless-core",
     "private": false,
-    "version": "2.3.2",
+    "version": "2.4.1",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",

package/dist/service.d.ts

@@ -1,6 +1,19 @@
 import type { Lang, TranslationOptions, I18nKeylessResponse, FetchTranslationParams, TranslationsUsage } from "./types.ts";
 import MyPQueue from "./my-pqueue.ts";
 export declare const queue: MyPQueue;
+/**
+ * Resolves the effective namespace for a translation call: an explicit per-call
+ * `namespace` wins, then the config-level `defaultNamespace`, then `DEFAULT_NAMESPACE`.
+ */
+export declare function resolveNamespace(options: TranslationOptions | undefined, config: FetchTranslationParams["config"]): string;
+/**
+ * Returns the namespaces queued since the last call (with their `unpersisted` flag) and
+ * clears the map.
+ */
+export declare function getNamespacesToFetchAfterTranslationFinished(): Array<{
+    namespace: string;
+    unpersisted: boolean;
+}>;
 /**
  * Gets a translation for the specified key from the store
  * @param key - The translation key (text in primary language)
@@ -24,7 +37,7 @@ export declare function translateKey(key: string, store: FetchTranslationParams,
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export declare function getAllTranslationsFromLanguage(targetLanguage: Lang, store: FetchTranslationParams): Promise<I18nKeylessResponse | void>;
+export declare function getAllTranslationsFromLanguage(targetLanguage: Lang, store: FetchTranslationParams, namespace?: string): Promise<I18nKeylessResponse | void>;
 /**
  * Send the translations usage to i18n-keyless API
  *
@@ -33,11 +46,11 @@ export declare function getAllTranslationsFromLanguage(targetLanguage: Lang, sto
  *
  * It's called on lib initialization
  * and everytime the language is set
- * @param translationsUsage - The translations usage to send to the API
+ * @param translationsUsageByNamespace - Usage keyed by namespace (default under "default")
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export declare function sendTranslationsUsageToI18nKeyless(translationsUsage: TranslationsUsage, store: FetchTranslationParams): Promise<{
+export declare function sendTranslationsUsageToI18nKeyless(translationsUsageByNamespace: Record<string, TranslationsUsage>, store: FetchTranslationParams): Promise<{
     ok: boolean;
     message: string;
 } | void>;

package/dist/service.js

@@ -1,7 +1,35 @@
+import { DEFAULT_NAMESPACE } from "./types.js";
 import MyPQueue from "./my-pqueue.js";
 import packageJson from "./package.json" with { type: "json" };
 import { api } from "./api.js";
 export const queue = new MyPQueue({ concurrency: 30 });
+/**
+ * Resolves the effective namespace for a translation call: an explicit per-call
+ * `namespace` wins, then the config-level `defaultNamespace`, then `DEFAULT_NAMESPACE`.
+ */
+export function resolveNamespace(options, config) {
+    return options?.namespace || config.defaultNamespace || DEFAULT_NAMESPACE;
+}
+/**
+ * Scratchpad of namespaces that had at least one missing key queued for translation since
+ * the last bulk fetch (mapped to whether that namespace is `unpersisted`). The queue's
+ * "empty" handler (in the react store / node service) reads this to know which namespaces
+ * to bulk-fetch — so we only re-download the namespaces that were actually rendered, never
+ * the whole project — and whether to persist the result.
+ */
+const namespacesToFetchAfterTranslationFinished = new Map();
+/**
+ * Returns the namespaces queued since the last call (with their `unpersisted` flag) and
+ * clears the map.
+ */
+export function getNamespacesToFetchAfterTranslationFinished() {
+    const namespaces = Array.from(namespacesToFetchAfterTranslationFinished, ([namespace, unpersisted]) => ({
+        namespace,
+        unpersisted,
+    }));
+    namespacesToFetchAfterTranslationFinished.clear();
+    return namespaces;
+}
 /**
  * Gets a translation for the specified key from the store
  * @param key - The translation key (text in primary language)
@@ -61,6 +89,7 @@ export function translateKey(key, store, options) {
     }
     const context = options?.context;
     const debug = options?.debug;
+    const namespace = resolveNamespace(options, config);
     // if (key.length > 280) {
     //   console.error("i18n-keyless: Key length exceeds 280 characters limit:", key);
     //   return;
@@ -69,7 +98,7 @@ export function translateKey(key, store, options) {
         return;
     }
     if (debug) {
-        console.log("translateKey", key, context, debug);
+        console.log("translateKey", key, context, namespace, debug);
     }
     const forceTemporaryLang = options?.forceTemporary?.[currentLanguage];
     const translation = context ? translations[`${key}__${context}`] : translations[key];
@@ -79,13 +108,19 @@ export function translateKey(key, store, options) {
         }
         return;
     }
+    // Remember this namespace (and whether it's unpersisted) so the queue's "empty" handler
+    // bulk-fetches it (and only it) and persists the result accordingly.
+    namespacesToFetchAfterTranslationFinished.set(namespace, !!options?.unpersistedNamespace);
+    // Dedup/guard per namespace so the same source text can be queued independently under
+    // different namespaces.
+    const queueId = `${namespace}:${key}`;
     queue.add(async () => {
         try {
-            if (translating[key]) {
+            if (translating[queueId]) {
                 return;
             }
             else {
-                translating[key] = true;
+                translating[queueId] = true;
             }
             if (config.handleTranslate) {
                 await config.handleTranslate?.(key);
@@ -94,6 +129,9 @@ export function translateKey(key, store, options) {
                 const body = {
                     key,
                     context,
+                    // Omit the default namespace so the wire format is unchanged for projects that
+                    // don't use namespaces (the backend treats "no namespace" as the default).
+                    namespace: namespace === DEFAULT_NAMESPACE ? undefined : namespace,
                     forceTemporary: options?.forceTemporary,
                     languages: config.languages.supported,
                     primaryLanguage: config.languages.primary,
@@ -122,14 +160,14 @@ export function translateKey(key, store, options) {
                     console.warn("i18n-keyless: ", response.message);
                 }
             }
-            translating[key] = false;
+            translating[queueId] = false;
             return;
         }
         catch (error) {
             console.error("i18n-keyless: Error translating key:", error);
-            translating[key] = false;
+            translating[queueId] = false;
         }
-    }, { priority: 1, id: key });
+    }, { priority: 1, id: queueId });
 }
 /**
  * Fetches all translations for a target language
@@ -137,7 +175,7 @@ export function translateKey(key, store, options) {
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export async function getAllTranslationsFromLanguage(targetLanguage, store) {
+export async function getAllTranslationsFromLanguage(targetLanguage, store, namespace) {
     const config = store.config;
     const lastRefresh = store.lastRefresh;
     const uniqueId = store.uniqueId;
@@ -148,11 +186,14 @@ export async function getAllTranslationsFromLanguage(targetLanguage, store) {
     // if (config.languages.primary === targetLanguage) {
     //   return;
     // }
+    // Omit the default namespace from the query so existing (non-namespaced) installs keep
+    // hitting the exact same URL.
+    const namespaceQuery = namespace && namespace !== DEFAULT_NAMESPACE ? `&namespace=${encodeURIComponent(namespace)}` : "";
     try {
         const response = config.getAllTranslations
             ? await config.getAllTranslations()
             : await api
-                .fetchTranslationsForOneLanguage(`${config.API_URL || "https://api.i18n-keyless.com"}/translate/${targetLanguage}?last_refresh=${lastRefresh}`, {
+                .fetchTranslationsForOneLanguage(`${config.API_URL || "https://api.i18n-keyless.com"}/translate/${targetLanguage}?last_refresh=${lastRefresh}${namespaceQuery}`, {
                 method: "GET",
                 headers: {
                     "Content-Type": "application/json",
@@ -182,22 +223,27 @@ export async function getAllTranslationsFromLanguage(targetLanguage, store) {
  *
  * It's called on lib initialization
  * and everytime the language is set
- * @param translationsUsage - The translations usage to send to the API
+ * @param translationsUsageByNamespace - Usage keyed by namespace (default under "default")
  * @param store - The translation store
  * @returns Promise resolving to the translation response or void if failed
  */
-export async function sendTranslationsUsageToI18nKeyless(translationsUsage, store) {
+export async function sendTranslationsUsageToI18nKeyless(translationsUsageByNamespace, store) {
     const config = store.config;
     if (!config.API_KEY) {
         console.error("i18n-keyless: No config found");
         return;
     }
-    if (Object.keys(translationsUsage).length === 0) {
+    if (Object.keys(translationsUsageByNamespace).length === 0) {
         return;
     }
+    const requestBody = {
+        primaryLanguage: config.languages.primary,
+        translationsUsageByNamespace,
+    };
     try {
         const response = config.sendTranslationsUsage
-            ? await config.sendTranslationsUsage(translationsUsage)
+            ? // custom handlers keep their flat signature: hand them the default-namespace bucket
+                await config.sendTranslationsUsage(translationsUsageByNamespace.default ?? {})
             : await api
                 .postLastUsedTranslations(`${config.API_URL || "https://api.i18n-keyless.com"}/translate/last-used-translations`, {
                 method: "POST",
@@ -206,10 +252,7 @@ export async function sendTranslationsUsageToI18nKeyless(translationsUsage, stor
                     Authorization: `Bearer ${config.API_KEY}`,
                     Version: packageJson.version,
                 },
-                body: JSON.stringify({
-                    primaryLanguage: config.languages.primary,
-                    translationsUsage,
-                }),
+                body: JSON.stringify(requestBody),
             })
                 .then((res) => res);
         if (response.message) {

package/dist/types.d.ts

@@ -1,6 +1,12 @@
 export type PrimaryLang = "fr" | "en";
 export declare const AVAILABLE_LANGS: readonly ["fr", "en", "nl", "it", "de", "es", "pl", "pt", "ro", "hu", "sv", "tr", "ja", "cn", "cz", "ru", "ko", "ar"];
 export type Lang = (typeof AVAILABLE_LANGS)[number];
+/**
+ * The namespace used when none is provided (per call or via `defaultNamespace` in config).
+ * The default namespace reuses the legacy storage keys (`i18n-keyless-translations` and
+ * `i18n-keyless-last-refresh`) so existing installs keep working without any migration.
+ */
+export declare const DEFAULT_NAMESPACE = "default";
 /**
  * The translations for a key
  * { "un text": "a text" }
@@ -63,6 +69,23 @@ export type TranslationOptions = {
      * You'll find it useful when it occurs to you, don't worry :)
      */
     context?: string;
+    /**
+     * The namespace this translation belongs to.
+     * Translations are fetched and persisted per namespace, so splitting a large project
+     * into several namespaces keeps each storage item small (avoids the localStorage quota
+     * error) and lets the app download only the namespaces it actually renders.
+     * Defaults to `defaultNamespace` from the config, or "default" if neither is set.
+     */
+    namespace?: string;
+    /**
+     * When true, this namespace's translations live in memory only: they are never written
+     * to storage, never added to the persisted namespaces index, and never reloaded at boot
+     * or refetched on language change from storage. Use it for high-cardinality, transient
+     * namespaces (e.g. one namespace per discussion) so they add zero storage weight and zero
+     * boot / language-switch cost. Defaults to false (persisted).
+     * Only affects the client (i18n-keyless-react); the node lib is in-memory regardless.
+     */
+    unpersistedNamespace?: boolean;
     /**
      * Could be helpful if something weird happens with this particular key.
      */
@@ -84,13 +107,22 @@ export type TranslationOptions = {
 export interface I18nKeylessRequestBody {
     key: string;
     context?: string;
+    namespace?: string;
     forceTemporary?: TranslationOptions["forceTemporary"];
     languages: LanguagesConfig["supported"];
     primaryLanguage: LanguagesConfig["primary"];
 }
 export interface I18nKeylessTranslationsUsageRequestBody {
     primaryLanguage: LanguagesConfig["primary"];
-    translationsUsage: TranslationsUsage;
+    /**
+     * Usage keyed by namespace: `{ "<namespace>": { "key__context": "YYYY-MM-DD" } }`. The
+     * default namespace is included under the key "default". The backend marks `last_used` on
+     * the exact `(key, context, namespace)` row.
+     *
+     * (Clients < 2.4.0 instead send a flat `translationsUsage` with no namespace; the backend
+     * treats that as the "default" namespace.) `unpersistedNamespace` namespaces are excluded.
+     */
+    translationsUsageByNamespace: Record<string, TranslationsUsage>;
 }
 export interface I18nKeylessResponse {
     ok: boolean;
@@ -120,6 +152,7 @@ export type FetchTranslationParams = {
         API_KEY: string;
         API_URL?: string;
         languages: LanguagesConfig;
+        defaultNamespace?: string;
         addMissingTranslations?: boolean;
         debug?: boolean;
         handleTranslate?: HandleTranslateFunction;

package/dist/types.js

@@ -18,3 +18,9 @@ export const AVAILABLE_LANGS = [
     "ko",
     "ar"
 ];
+/**
+ * The namespace used when none is provided (per call or via `defaultNamespace` in config).
+ * The default namespace reuses the legacy storage keys (`i18n-keyless-translations` and
+ * `i18n-keyless-last-refresh`) so existing installs keep working without any migration.
+ */
+export const DEFAULT_NAMESPACE = "default";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "i18n-keyless-core",
   "private": false,
-  "version": "2.3.2",
+  "version": "2.4.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",