locl-js 2.0.0 → 2.0.1

package/README.md

@@ -4,7 +4,7 @@
 
 **LocL** is an ultra-fast, lightweight, and fully-featured TypeScript internationalization (i18n) library. Designed for modern web applications, backend services, and multi-framework setups, it provides compile-time type-safety, automatic pluralization, ICU-style select branching, built-in formatters, and reactive subscriptions with **zero external dependencies**.
 
-It is inspired by libraries like `i18next` and `react-i18next`, but engineered with a focus on strict TypeScript type checking, sub-millisecond execution, clean APIs, and 100% test coverage.
+It is inspired by libraries like `i18next` and `react-i18next`, but engineered with a focus on strict TypeScript type checking, sub-millisecond execution, clean APIs, and **100% test coverage across every statement, branch, and function**.
 
 ---
 
@@ -16,12 +16,12 @@ It is inspired by libraries like `i18next` and `react-i18next`, but engineered w
   - **`createLocLReact` Hook Factory**: Zero-declaration, pre-bound React suite.
   - **`LocLRegister` Declaration Merging**: Ambient global autocomplete for standalone imports.
 - **📦 Zero Dependencies & Lightweight**: Pure TypeScript with no runtime dependencies.
-- **🔄 Drop-in i18next Compat**: Swap existing `i18next` codebases effortlessly using `locl-js/compat` without rewriting translation call sites. Supports colon namespaces (`auth:login`), default fallbacks, and event listener cleanup.
+- **🔄 Drop-in i18next Compat**: Swap existing `i18next` codebases effortlessly using `locl-js/compat` without rewriting translation call sites. Supports colon namespaces (`auth:login`), strict parameter checking, default fallbacks, and event listener cleanup.
 - **🌐 Multi-Framework Reactive Store**: Implements the standard reactive store contract via `translator.subscribe()`, working out of the box in Svelte, Vue, Solid, and Node.js.
 - **🔢 Automatic Plurals**: Handles object plurals (`{ zero, one, other }`) and suffix plurals (`_zero`, `_one`, `_other`) directly via `t()` or dedicated `plural()`.
 - **🔀 ICU Select Support**: Conditional branching (`{gender, select, male {He} female {She} other {They}}`) with nested parameter interpolation (`{gender, select, male {He has {count} items}}`).
 - **🔧 Built-in & Custom Formatters**: Format dates, numbers, currencies, strings, and booleans inline via pipe syntax (`{val | number}`, `{date | date:short}`).
-- **⚡ High Performance Caching**: Granular scope-based translation caching and multi-proxy instance reuse.
+- **⚡ High Performance Caching**: Granular scope-based translation caching and multi-proxy instance reuse with zero proxy-of-proxy overhead.
 - **🛡️ Prototype-Safe Dynamic Resources**: Safely merge resources dynamically at runtime with built-in prototype pollution guards.
 - **💯 100% Test Coverage**: Fully verified across every line, branch, function, and edge case.
 
@@ -114,7 +114,7 @@ translator.t("staticNotice");
 
 ### Workflow A: Zero-Declaration Factory (`createLocLReact`) ⭐ *Recommended*
 
-No `.d.ts` declaration merging required. Bind your translator once and export typed components and hooks:
+No `.d.ts` declaration merging required. Pass your translator instance to `createLocLReact` once and export pre-bound, 100% typed components and hooks:
 
 ```tsx
 // src/i18n-react.ts
@@ -162,7 +162,7 @@ function Header() {
 }
 
 function Profile() {
-  // Scoped autocomplete: keys are restricted to the "user" namespace!
+  // Scoped autocomplete: keys are restricted strictly to the "user" namespace!
   const { t } = useTranslation("user");
 
   return (
@@ -183,7 +183,7 @@ function Profile() {
 
 ### Workflow B: Global Type Registry (`LocLRegister`)
 
-If you prefer importing directly from `"locl-js/react"`, augment `LocLRegister` once in your project (e.g. `src/i18n.d.ts`):
+If you prefer importing hooks and components directly from `"locl-js/react"`, augment `LocLRegister` once in your project (e.g. `src/i18n.d.ts`):
 
 ```typescript
 import { translator } from "./i18n";
@@ -195,7 +195,7 @@ declare module "locl-js/react" {
 }
 ```
 
-Now, standalone imports automatically have full autocomplete everywhere:
+Now, standalone imports automatically have full autocomplete everywhere without passing any generic arguments:
 
 ```tsx
 import { useTranslation, Trans } from "locl-js/react";
@@ -224,38 +224,60 @@ Renders complex translations containing formatting tags (`<bold>read</bold>`, `<
 />
 ```
 
-- **Tag element replacement**: Replaces tags with JSX elements (e.g. `<strong />`) while preserving inner text as children.
-- **Function renderers**: Supports custom render functions: `(content) => <span style={{ fontWeight: "bold" }}>{content}</span>`.
-- **Reactive updates**: Subscribes to `useSyncExternalStore` so language changes re-render smoothly.
+#### Key Capabilities
+
+- **Strict Key Validation**: Autocompletes valid keys and flags typos at compile time.
+- **Strict Value Validation**: If the template contains `{name}`, `values={{ name: ... }}` is required at compile time.
+- **Dynamic Key Fallback**: Unregistered or dynamic keys are allowed whenever an explicit `fallback` string is provided (`fallback="Default string"`).
+- **Scope Support**: Narrow keys using the `scope` prop: `<Trans scope="user" i18nKey="greeting" values={{ name: "Alice" }} />`.
+- **Standalone `translator` Prop**: When passing `translator={translator}`, `Trans` automatically infers the dictionary and provides autocomplete for that translator's keys.
+- **Tag Element Replacement**: Clones JSX elements (e.g. `<strong />`) while preserving inner text as children.
+- **Function Renderers**: Supports custom render functions: `(content) => <span style={{ fontWeight: "bold" }}>{content}</span>`.
+- **Reactive Updates**: Subscribes to `useSyncExternalStore` so language changes re-render smoothly.
 
 ---
 
 ## Drop-in `i18next` Compatibility (`locl-js/compat`)
 
-Migrate existing `i18next` codebases effortlessly without refactoring callsites:
+Migrate existing `i18next` codebases effortlessly without refactoring callsites. `locl-js/compat` preserves `i18next` runtime flexibility while offering full compile-time strict type checking:
 
 ```typescript
-import { initLocL } from "locl-js";
+import { initLocL, defineResources } from "locl-js";
 import { toI18next, createI18nextCompat } from "locl-js/compat";
 
+const resources = defineResources({
+  en: {
+    common: {
+      hello: "Hello, {name}!",
+      save: "Save"
+    },
+    apple_one: "1 apple",
+    apple_other: "{count} apples"
+  }
+});
 const locl = initLocL({ resources, fallbackLanguage: "en" });
 export const i18n = toI18next(locl);
 
-// Standard i18next patterns supported seamlessly:
-i18n.t("common:login", { name: "Alice" }); // Colon namespaces
-i18n.t("common.login");                   // Dot namespaces
-i18n.t("missing.key", "Default String");   // Default values
-i18n.exists("common:login");              // Key existence checks
+// Colon and dot syntax autocompleted and strictly enforced:
+i18n.t("common:hello", { name: "Maria" }); // Requires { name }!
+i18n.t("common.save");                    // Static key: options optional!
+
+// Plurals strictly enforce { count: number }:
+i18n.t("apple", { count: 5 });
+
+// Dynamic and fallback keys:
+i18n.t("missing.key", "Default Fallback");
+i18n.t("missing.key", { defaultValue: "Fallback Text" });
 
-// Plurals via count:
-i18n.t("apple", { count: 5 });             // "5 apples"
+// Key existence check (with autocomplete for colon and dot keys):
+i18n.exists("common:save"); // true
 
-// Dynamic resource bundle management:
+// Resource bundle management:
 i18n.addResourceBundle("en", "dynamic", { title: "Title" });
-i18n.hasResourceBundle("en", "dynamic");   // true
-i18n.getResourceBundle("en", "dynamic");   // { title: "Title" }
+i18n.hasResourceBundle("en", "dynamic"); // true
+i18n.getResourceBundle("en", "dynamic"); // { title: "Title" }
 
-// Event listeners with unbind cleanup:
+// Event listeners with cleanup callback:
 const unbind = i18n.on("languageChanged", (lng) => {
   console.log("Language changed to", lng);
 });
@@ -476,16 +498,16 @@ console.log(multiT.t("dashboard.welcome", { name: "Alice" })); // "Welcome, Alic
 
 ### React Exports (`locl-js/react`)
 
-- **`createLocLReact(translator)`**: Returns a pre-bound React suite (`LocLProvider`, `useTranslation`, `useLocL`, `Trans`).
+- **`createLocLReact(translator)`**: Returns a pre-bound, zero-declaration React suite (`LocLProvider`, `useTranslation`, `useLocL`, `Trans`, `LocLContext`).
 - **`LocLProvider`**: React Context Provider for the active translator.
-- **`useTranslation(scope?, customTranslator?)`**: Translation hook with scope support.
+- **`useTranslation(scope?, customTranslator?)`**: Translation hook with namespace scoping support.
 - **`useLocL(customTranslator?)`**: Hook returning translator instance and reactive language state.
-- **`<Trans />`**: Rich JSX tag interpolation component.
+- **`<Trans />`**: Rich JSX component interpolation component supporting strict key/param checking, fallbacks, and scope narrowing.
 - **`LocLRegister`**: Ambient interface for global type registration.
 
 ### Compat Exports (`locl-js/compat`)
 
-- **`toI18next(translator)`**: Wraps a LocL instance into an `i18next`-compatible API.
+- **`toI18next(translator)`**: Wraps a LocL instance into an `i18next`-compatible API with strict parameter checking.
 - **`createI18nextCompat(translator)`**: Alias of `toI18next`.
 
 ### `LocL` Instance Methods

package/dist/{LocL-fN9Yari8.d.mts → LocL-v4yNIiKt.d.mts}

@@ -432,6 +432,7 @@ declare class LocL<T extends Record<string, any>, Fallback extends keyof T & str
     private interpolate;
     private applyFormat;
     private makeReadOnly;
+    private isUnsafeObjectKey;
 }
 
-export { type Formatter as F, type InterpolationOptions as I, type LocLConfig as L, type NestedKeyOf as N, type PluralKeys as P, type ScopeType as S, type TranslationObjectFor as T, LocL as a, type LangWithPlurals as b, type Language as c };
+export { type Formatter as F, type InterpolationOptions as I, type LocLConfig as L, type NestedKeyOf as N, type PluralParamsFor as P, type ScopeType as S, type TranslationObjectFor as T, LocL as a, type LangWithPlurals as b, type ParamsFor as c, type PathValue as d, type IsEmptyParams as e, type PluralKeys as f, type Language as g, type Scope as h };

package/dist/{LocL-fN9Yari8.d.ts → LocL-v4yNIiKt.d.ts}

@@ -432,6 +432,7 @@ declare class LocL<T extends Record<string, any>, Fallback extends keyof T & str
     private interpolate;
     private applyFormat;
     private makeReadOnly;
+    private isUnsafeObjectKey;
 }
 
-export { type Formatter as F, type InterpolationOptions as I, type LocLConfig as L, type NestedKeyOf as N, type PluralKeys as P, type ScopeType as S, type TranslationObjectFor as T, LocL as a, type LangWithPlurals as b, type Language as c };
+export { type Formatter as F, type InterpolationOptions as I, type LocLConfig as L, type NestedKeyOf as N, type PluralParamsFor as P, type ScopeType as S, type TranslationObjectFor as T, LocL as a, type LangWithPlurals as b, type ParamsFor as c, type PathValue as d, type IsEmptyParams as e, type PluralKeys as f, type Language as g, type Scope as h };

package/dist/compat.d.mts

@@ -1,22 +1,36 @@
-import { N as NestedKeyOf, I as InterpolationOptions, a as LocL } from './LocL-fN9Yari8.mjs';
+import { N as NestedKeyOf, I as InterpolationOptions, P as PluralParamsFor, c as ParamsFor, d as PathValue, e as IsEmptyParams, T as TranslationObjectFor, f as PluralKeys, a as LocL } from './LocL-v4yNIiKt.mjs';
 import { DefaultResources, DefaultFallback } from './react.mjs';
 import 'react';
 
-/**
- * Key type that supports both colon syntax (`auth:login`) and dotted syntax (`auth.login`).
- */
-type I18nextKey<T> = T extends object ? {
-    [K in keyof T & string]: T[K] extends object ? `${K}:${NestedKeyOf<T[K]>}` | `${K}.${NestedKeyOf<T[K]>}` | `${K}` : `${K}`;
-}[keyof T & string] | NestedKeyOf<T> : string;
+type NormalizeKey<K extends string> = K extends `${infer NS}:${infer Rest}` ? `${NS}.${Rest}` : K;
+type ColonKeys<K extends string> = K extends `${infer NS}.${infer Rest}` ? `${NS}:${Rest}` | `${NS}.${Rest}` : K;
+type BaseKeys<Tr, PK extends string> = ((Tr extends object ? NestedKeyOf<Tr> : never) | PK) & string;
+type I18nextKey<Tr, PK extends string> = ColonKeys<BaseKeys<Tr, PK>>;
 interface I18nextOptions extends InterpolationOptions {
     ns?: string;
     defaultValue?: string;
     count?: number;
-    [key: string]: any;
 }
-interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>> {
-    t<K extends (I18nextKey<T[Fallback]> | (string & {}))>(key: K, options?: I18nextOptions): string;
-    t<K extends (I18nextKey<T[Fallback]> | (string & {}))>(key: K, defaultValue?: string, options?: I18nextOptions): string;
+type I18nextParamsFor<K extends string, Tr, PK extends string> = NormalizeKey<K> extends PK ? PluralParamsFor<NormalizeKey<K>, Tr> : ParamsFor<PathValue<Tr, NormalizeKey<K>>>;
+type I18nextHasParams<K extends string, Tr, PK extends string> = NormalizeKey<K> extends PK ? true : IsEmptyParams<ParamsFor<PathValue<Tr, NormalizeKey<K>>>> extends true ? false : true;
+type I18nextOptionsFor<K extends string, Tr, PK extends string> = I18nextParamsFor<K, Tr, PK> & I18nextOptions;
+interface I18nextTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, Tr = TranslationObjectFor<undefined, T, Fallback>, PK extends string = PluralKeys<undefined, T, Fallback>> {
+    <K extends I18nextKey<Tr, PK>>(key: K, ...args: I18nextHasParams<K, Tr, PK> extends true ? [options: I18nextOptionsFor<K, Tr, PK>] : [options?: I18nextOptions]): string;
+    <K extends I18nextKey<Tr, PK>>(key: K, defaultValue: string, ...args: I18nextHasParams<K, Tr, PK> extends true ? [options: I18nextOptionsFor<K, Tr, PK>] : [options?: I18nextOptions]): string;
+    (key: string, defaultValue: string, options?: I18nextOptions): string;
+    (key: string, options: {
+        defaultValue: string;
+    } & I18nextOptions): string;
+    (key: string, options: {
+        ns: string;
+    } & I18nextOptions): string;
+}
+interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, Tr = TranslationObjectFor<undefined, T, Fallback>, PK extends string = PluralKeys<undefined, T, Fallback>> {
+    t: I18nextTranslation<T, Fallback>;
+    exists<K extends I18nextKey<Tr, PK>>(key: K, options?: {
+        ns?: string;
+        [key: string]: any;
+    }): boolean;
     exists(key: string, options?: {
         ns?: string;
         [key: string]: any;
@@ -34,11 +48,7 @@ interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallba
     loadNamespaces(ns: string | string[], callback?: () => void): Promise<void>;
     translator: LocL<T, Fallback, any, any, any>;
 }
-/**
- * Wraps a LocL instance in an i18next-compatible interface.
- * Supports both colon (`common:login`) and dotted namespaces with full IDE autocomplete.
- */
 declare function toI18next<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(translator: LocL<T, Fallback, any, any, any>): I18nextCompat<T, Fallback>;
 declare const createI18nextCompat: typeof toI18next;
 
-export { type I18nextCompat, type I18nextKey, type I18nextOptions, createI18nextCompat, toI18next };
+export { type BaseKeys, type ColonKeys, type I18nextCompat, type I18nextHasParams, type I18nextKey, type I18nextOptions, type I18nextOptionsFor, type I18nextParamsFor, type I18nextTranslation, type NormalizeKey, createI18nextCompat, toI18next };

package/dist/compat.d.ts

@@ -1,22 +1,36 @@
-import { N as NestedKeyOf, I as InterpolationOptions, a as LocL } from './LocL-fN9Yari8.js';
+import { N as NestedKeyOf, I as InterpolationOptions, P as PluralParamsFor, c as ParamsFor, d as PathValue, e as IsEmptyParams, T as TranslationObjectFor, f as PluralKeys, a as LocL } from './LocL-v4yNIiKt.js';
 import { DefaultResources, DefaultFallback } from './react.js';
 import 'react';
 
-/**
- * Key type that supports both colon syntax (`auth:login`) and dotted syntax (`auth.login`).
- */
-type I18nextKey<T> = T extends object ? {
-    [K in keyof T & string]: T[K] extends object ? `${K}:${NestedKeyOf<T[K]>}` | `${K}.${NestedKeyOf<T[K]>}` | `${K}` : `${K}`;
-}[keyof T & string] | NestedKeyOf<T> : string;
+type NormalizeKey<K extends string> = K extends `${infer NS}:${infer Rest}` ? `${NS}.${Rest}` : K;
+type ColonKeys<K extends string> = K extends `${infer NS}.${infer Rest}` ? `${NS}:${Rest}` | `${NS}.${Rest}` : K;
+type BaseKeys<Tr, PK extends string> = ((Tr extends object ? NestedKeyOf<Tr> : never) | PK) & string;
+type I18nextKey<Tr, PK extends string> = ColonKeys<BaseKeys<Tr, PK>>;
 interface I18nextOptions extends InterpolationOptions {
     ns?: string;
     defaultValue?: string;
     count?: number;
-    [key: string]: any;
 }
-interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>> {
-    t<K extends (I18nextKey<T[Fallback]> | (string & {}))>(key: K, options?: I18nextOptions): string;
-    t<K extends (I18nextKey<T[Fallback]> | (string & {}))>(key: K, defaultValue?: string, options?: I18nextOptions): string;
+type I18nextParamsFor<K extends string, Tr, PK extends string> = NormalizeKey<K> extends PK ? PluralParamsFor<NormalizeKey<K>, Tr> : ParamsFor<PathValue<Tr, NormalizeKey<K>>>;
+type I18nextHasParams<K extends string, Tr, PK extends string> = NormalizeKey<K> extends PK ? true : IsEmptyParams<ParamsFor<PathValue<Tr, NormalizeKey<K>>>> extends true ? false : true;
+type I18nextOptionsFor<K extends string, Tr, PK extends string> = I18nextParamsFor<K, Tr, PK> & I18nextOptions;
+interface I18nextTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, Tr = TranslationObjectFor<undefined, T, Fallback>, PK extends string = PluralKeys<undefined, T, Fallback>> {
+    <K extends I18nextKey<Tr, PK>>(key: K, ...args: I18nextHasParams<K, Tr, PK> extends true ? [options: I18nextOptionsFor<K, Tr, PK>] : [options?: I18nextOptions]): string;
+    <K extends I18nextKey<Tr, PK>>(key: K, defaultValue: string, ...args: I18nextHasParams<K, Tr, PK> extends true ? [options: I18nextOptionsFor<K, Tr, PK>] : [options?: I18nextOptions]): string;
+    (key: string, defaultValue: string, options?: I18nextOptions): string;
+    (key: string, options: {
+        defaultValue: string;
+    } & I18nextOptions): string;
+    (key: string, options: {
+        ns: string;
+    } & I18nextOptions): string;
+}
+interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, Tr = TranslationObjectFor<undefined, T, Fallback>, PK extends string = PluralKeys<undefined, T, Fallback>> {
+    t: I18nextTranslation<T, Fallback>;
+    exists<K extends I18nextKey<Tr, PK>>(key: K, options?: {
+        ns?: string;
+        [key: string]: any;
+    }): boolean;
     exists(key: string, options?: {
         ns?: string;
         [key: string]: any;
@@ -34,11 +48,7 @@ interface I18nextCompat<T extends Record<string, any> = DefaultResources, Fallba
     loadNamespaces(ns: string | string[], callback?: () => void): Promise<void>;
     translator: LocL<T, Fallback, any, any, any>;
 }
-/**
- * Wraps a LocL instance in an i18next-compatible interface.
- * Supports both colon (`common:login`) and dotted namespaces with full IDE autocomplete.
- */
 declare function toI18next<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(translator: LocL<T, Fallback, any, any, any>): I18nextCompat<T, Fallback>;
 declare const createI18nextCompat: typeof toI18next;
 
-export { type I18nextCompat, type I18nextKey, type I18nextOptions, createI18nextCompat, toI18next };
+export { type BaseKeys, type ColonKeys, type I18nextCompat, type I18nextHasParams, type I18nextKey, type I18nextOptions, type I18nextOptionsFor, type I18nextParamsFor, type I18nextTranslation, type NormalizeKey, createI18nextCompat, toI18next };

package/dist/compat.js

@@ -38,41 +38,42 @@ function toI18next(translator) {
   translator.subscribe((newLang, prevLang) => {
     emit("languageChanged", newLang, prevLang);
   });
+  const tFunction = (key, arg1, arg2) => {
+    let defaultValue;
+    let options = {};
+    if (typeof arg1 === "string") {
+      defaultValue = arg1;
+      options = typeof arg2 === "object" && arg2 !== null ? arg2 : {};
+    } else if (typeof arg1 === "object" && arg1 !== null) {
+      options = arg1;
+      defaultValue = options.defaultValue;
+    }
+    let lookupKey = key;
+    let ns = options.ns;
+    if (key.includes(":")) {
+      const colonIdx = key.indexOf(":");
+      ns = key.slice(0, colonIdx);
+      lookupKey = key.slice(colonIdx + 1);
+    }
+    let activeTranslator = translator;
+    if (ns) {
+      activeTranslator = translator.withConfig({ scope: ns });
+    }
+    let result;
+    if (typeof options.count === "number") {
+      result = activeTranslator.plural(lookupKey, options);
+    } else {
+      result = activeTranslator.t(lookupKey, options);
+    }
+    const keyExists = activeTranslator.get(lookupKey) !== void 0 || result !== lookupKey;
+    if (!keyExists && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    return result ?? defaultValue ?? key;
+  };
   const compat = {
     translator,
-    t(key, arg1, arg2) {
-      let defaultValue;
-      let options = {};
-      if (typeof arg1 === "string") {
-        defaultValue = arg1;
-        options = typeof arg2 === "object" && arg2 !== null ? arg2 : {};
-      } else if (typeof arg1 === "object" && arg1 !== null) {
-        options = arg1;
-        defaultValue = options.defaultValue;
-      }
-      let lookupKey = key;
-      let ns = options.ns;
-      if (key.includes(":")) {
-        const colonIdx = key.indexOf(":");
-        ns = key.slice(0, colonIdx);
-        lookupKey = key.slice(colonIdx + 1);
-      }
-      let activeTranslator = translator;
-      if (ns) {
-        activeTranslator = translator.withConfig({ scope: ns });
-      }
-      let result;
-      if (typeof options.count === "number") {
-        result = activeTranslator.plural(lookupKey, options);
-      } else {
-        result = activeTranslator.t(lookupKey, options);
-      }
-      const keyExists = activeTranslator.get(lookupKey) !== void 0 || result !== lookupKey;
-      if (!keyExists && defaultValue !== void 0) {
-        return defaultValue;
-      }
-      return result ?? defaultValue ?? key;
-    },
+    t: tFunction,
     exists(key, options) {
       let lookupKey = key;
       let ns = options?.ns;
@@ -112,7 +113,7 @@ function toI18next(translator) {
     addResources(lng, ns, resources) {
       translator.addResources(lng, { [ns]: resources });
     },
-    addResourceBundle(lng, ns, resources, deep, overwrite) {
+    addResourceBundle(lng, ns, resources) {
       translator.addResources(lng, { [ns]: resources });
     },
     hasResourceBundle(lng, ns) {

package/dist/compat.mjs

@@ -13,41 +13,42 @@ function toI18next(translator) {
   translator.subscribe((newLang, prevLang) => {
     emit("languageChanged", newLang, prevLang);
   });
+  const tFunction = (key, arg1, arg2) => {
+    let defaultValue;
+    let options = {};
+    if (typeof arg1 === "string") {
+      defaultValue = arg1;
+      options = typeof arg2 === "object" && arg2 !== null ? arg2 : {};
+    } else if (typeof arg1 === "object" && arg1 !== null) {
+      options = arg1;
+      defaultValue = options.defaultValue;
+    }
+    let lookupKey = key;
+    let ns = options.ns;
+    if (key.includes(":")) {
+      const colonIdx = key.indexOf(":");
+      ns = key.slice(0, colonIdx);
+      lookupKey = key.slice(colonIdx + 1);
+    }
+    let activeTranslator = translator;
+    if (ns) {
+      activeTranslator = translator.withConfig({ scope: ns });
+    }
+    let result;
+    if (typeof options.count === "number") {
+      result = activeTranslator.plural(lookupKey, options);
+    } else {
+      result = activeTranslator.t(lookupKey, options);
+    }
+    const keyExists = activeTranslator.get(lookupKey) !== void 0 || result !== lookupKey;
+    if (!keyExists && defaultValue !== void 0) {
+      return defaultValue;
+    }
+    return result ?? defaultValue ?? key;
+  };
   const compat = {
     translator,
-    t(key, arg1, arg2) {
-      let defaultValue;
-      let options = {};
-      if (typeof arg1 === "string") {
-        defaultValue = arg1;
-        options = typeof arg2 === "object" && arg2 !== null ? arg2 : {};
-      } else if (typeof arg1 === "object" && arg1 !== null) {
-        options = arg1;
-        defaultValue = options.defaultValue;
-      }
-      let lookupKey = key;
-      let ns = options.ns;
-      if (key.includes(":")) {
-        const colonIdx = key.indexOf(":");
-        ns = key.slice(0, colonIdx);
-        lookupKey = key.slice(colonIdx + 1);
-      }
-      let activeTranslator = translator;
-      if (ns) {
-        activeTranslator = translator.withConfig({ scope: ns });
-      }
-      let result;
-      if (typeof options.count === "number") {
-        result = activeTranslator.plural(lookupKey, options);
-      } else {
-        result = activeTranslator.t(lookupKey, options);
-      }
-      const keyExists = activeTranslator.get(lookupKey) !== void 0 || result !== lookupKey;
-      if (!keyExists && defaultValue !== void 0) {
-        return defaultValue;
-      }
-      return result ?? defaultValue ?? key;
-    },
+    t: tFunction,
     exists(key, options) {
       let lookupKey = key;
       let ns = options?.ns;
@@ -87,7 +88,7 @@ function toI18next(translator) {
     addResources(lng, ns, resources) {
       translator.addResources(lng, { [ns]: resources });
     },
-    addResourceBundle(lng, ns, resources, deep, overwrite) {
+    addResourceBundle(lng, ns, resources) {
       translator.addResources(lng, { [ns]: resources });
     },
     hasResourceBundle(lng, ns) {

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { S as ScopeType, F as Formatter, L as LocLConfig, a as LocL } from './LocL-fN9Yari8.mjs';
-export { b as LangWithPlurals } from './LocL-fN9Yari8.mjs';
+import { S as ScopeType, F as Formatter, L as LocLConfig, a as LocL } from './LocL-v4yNIiKt.mjs';
+export { b as LangWithPlurals } from './LocL-v4yNIiKt.mjs';
 
 /**
  * Initializes a new LocL instance.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as ScopeType, F as Formatter, L as LocLConfig, a as LocL } from './LocL-fN9Yari8.js';
-export { b as LangWithPlurals } from './LocL-fN9Yari8.js';
+import { S as ScopeType, F as Formatter, L as LocLConfig, a as LocL } from './LocL-v4yNIiKt.js';
+export { b as LangWithPlurals } from './LocL-v4yNIiKt.js';
 
 /**
  * Initializes a new LocL instance.

package/dist/index.js

@@ -305,25 +305,26 @@ var LocL = class _LocL {
    * @param value - The translation value.
    */
   addResource(lang, key, value) {
-    if (!this.resources[lang]) {
-      this.resources[lang] = {};
+    if (this.isUnsafeObjectKey(lang)) {
+      return;
     }
     const keys = key.split(".");
+    if (keys.some((k) => this.isUnsafeObjectKey(k))) {
+      return;
+    }
+    if (!this.resources[lang]) {
+      this.resources[lang] = /* @__PURE__ */ Object.create(null);
+    }
     let current = this.resources[lang];
     for (let i = 0; i < keys.length - 1; i++) {
       const k = keys[i];
-      if (k === "__proto__" || k === "constructor" || k === "prototype") {
-        return;
-      }
       if (!current[k] || typeof current[k] !== "object") {
-        current[k] = {};
+        current[k] = /* @__PURE__ */ Object.create(null);
       }
       current = current[k];
     }
     const lastKey = keys[keys.length - 1];
-    if (lastKey !== "__proto__" && lastKey !== "constructor" && lastKey !== "prototype") {
-      current[lastKey] = value;
-    }
+    current[lastKey] = value;
     this.invalidateCacheForLang(lang);
   }
   /**
@@ -332,17 +333,20 @@ var LocL = class _LocL {
    * @param bundle - Object of translations to merge.
    */
   addResources(lang, bundle) {
+    if (this.isUnsafeObjectKey(lang)) {
+      return;
+    }
     if (!this.resources[lang]) {
-      this.resources[lang] = {};
+      this.resources[lang] = /* @__PURE__ */ Object.create(null);
     }
     const deepMerge = (target, source) => {
       for (const k of Object.keys(source)) {
-        if (k === "__proto__" || k === "constructor" || k === "prototype") {
+        if (this.isUnsafeObjectKey(k)) {
           continue;
         }
         if (source[k] && typeof source[k] === "object" && !Array.isArray(source[k])) {
           if (!target[k] || typeof target[k] !== "object") {
-            target[k] = {};
+            target[k] = /* @__PURE__ */ Object.create(null);
           }
           deepMerge(target[k], source[k]);
         } else {
@@ -563,7 +567,7 @@ var LocL = class _LocL {
         return void 0;
       }
       const keyTest = keysCopy.join(".");
-      if (current.hasOwnProperty(keyTest)) {
+      if (Object.prototype.hasOwnProperty.call(current, keyTest)) {
         return current[keyTest];
       }
       if (!(key in current)) {
@@ -737,6 +741,9 @@ var LocL = class _LocL {
     this.proxyCache.set(obj, proxy);
     return proxy;
   }
+  isUnsafeObjectKey(key) {
+    return key === "__proto__" || key === "constructor" || key === "prototype";
+  }
 };
 
 // src/index.ts

package/dist/index.mjs

@@ -277,25 +277,26 @@ var LocL = class _LocL {
    * @param value - The translation value.
    */
   addResource(lang, key, value) {
-    if (!this.resources[lang]) {
-      this.resources[lang] = {};
+    if (this.isUnsafeObjectKey(lang)) {
+      return;
     }
     const keys = key.split(".");
+    if (keys.some((k) => this.isUnsafeObjectKey(k))) {
+      return;
+    }
+    if (!this.resources[lang]) {
+      this.resources[lang] = /* @__PURE__ */ Object.create(null);
+    }
     let current = this.resources[lang];
     for (let i = 0; i < keys.length - 1; i++) {
       const k = keys[i];
-      if (k === "__proto__" || k === "constructor" || k === "prototype") {
-        return;
-      }
       if (!current[k] || typeof current[k] !== "object") {
-        current[k] = {};
+        current[k] = /* @__PURE__ */ Object.create(null);
       }
       current = current[k];
     }
     const lastKey = keys[keys.length - 1];
-    if (lastKey !== "__proto__" && lastKey !== "constructor" && lastKey !== "prototype") {
-      current[lastKey] = value;
-    }
+    current[lastKey] = value;
     this.invalidateCacheForLang(lang);
   }
   /**
@@ -304,17 +305,20 @@ var LocL = class _LocL {
    * @param bundle - Object of translations to merge.
    */
   addResources(lang, bundle) {
+    if (this.isUnsafeObjectKey(lang)) {
+      return;
+    }
     if (!this.resources[lang]) {
-      this.resources[lang] = {};
+      this.resources[lang] = /* @__PURE__ */ Object.create(null);
     }
     const deepMerge = (target, source) => {
       for (const k of Object.keys(source)) {
-        if (k === "__proto__" || k === "constructor" || k === "prototype") {
+        if (this.isUnsafeObjectKey(k)) {
           continue;
         }
         if (source[k] && typeof source[k] === "object" && !Array.isArray(source[k])) {
           if (!target[k] || typeof target[k] !== "object") {
-            target[k] = {};
+            target[k] = /* @__PURE__ */ Object.create(null);
           }
           deepMerge(target[k], source[k]);
         } else {
@@ -535,7 +539,7 @@ var LocL = class _LocL {
         return void 0;
       }
       const keyTest = keysCopy.join(".");
-      if (current.hasOwnProperty(keyTest)) {
+      if (Object.prototype.hasOwnProperty.call(current, keyTest)) {
         return current[keyTest];
       }
       if (!(key in current)) {
@@ -709,6 +713,9 @@ var LocL = class _LocL {
     this.proxyCache.set(obj, proxy);
     return proxy;
   }
+  isUnsafeObjectKey(key) {
+    return key === "__proto__" || key === "constructor" || key === "prototype";
+  }
 };
 
 // src/index.ts

package/dist/react.d.mts

@@ -1,28 +1,25 @@
 import React, { ReactElement, ReactNode } from 'react';
-import { S as ScopeType, N as NestedKeyOf, T as TranslationObjectFor, P as PluralKeys, I as InterpolationOptions, a as LocL, c as Language } from './LocL-fN9Yari8.mjs';
+import { S as ScopeType, N as NestedKeyOf, T as TranslationObjectFor, f as PluralKeys, e as IsEmptyParams, c as ParamsFor, d as PathValue, I as InterpolationOptions, a as LocL, g as Language, h as Scope } from './LocL-v4yNIiKt.mjs';
 
 type TransKey<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined> = (NestedKeyOf<TranslationObjectFor<S, T, Fallback>> | PluralKeys<S, T, Fallback>) & string;
-interface TransProps<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>> {
-    /** The translation key to look up (with IDE autocomplete + fallback tolerance) */
+type TransValues<T extends Record<string, any>, Fallback extends keyof T & string, S extends ScopeType<T, Fallback>, K extends string> = IsEmptyParams<ParamsFor<PathValue<TranslationObjectFor<S, T, Fallback>, K>>> extends true ? InterpolationOptions | undefined : ParamsFor<PathValue<TranslationObjectFor<S, T, Fallback>, K>> & InterpolationOptions;
+type TransProps<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>> = {
+    /** Strictly typed translation key */
+    i18nKey: K;
+    values?: TransValues<T, Fallback, S, K>;
+    components?: Record<string, ReactElement | ((content: ReactNode) => ReactNode)>;
+    translator?: LocL<T, any, any, any, any>;
+    scope?: S;
+    fallback?: string;
+} | {
+    /** Dynamic / fallback key allowed ONLY when fallback string is provided */
     i18nKey: K | (string & {});
-    /** Values to interpolate into variable placeholders ({name}, {{name}}) */
     values?: InterpolationOptions;
-    /**
-     * Component elements or functions to substitute for `<tag>content</tag>`
-     * @example
-     * components={{
-     *   bold: <strong />,
-     *   link: (content) => <a href="/terms">{content}</a>
-     * }}
-     */
     components?: Record<string, ReactElement | ((content: ReactNode) => ReactNode)>;
-    /** Optional custom translator instance if not using LocLContext */
-    translator?: LocL<any, any, any, any, any>;
-    /** Optional namespace scope for the translation key */
+    translator?: LocL<T, any, any, any, any>;
     scope?: S;
-    /** Fallback string if key is not found */
-    fallback?: string;
-}
+    fallback: string;
+};
 /**
  * Renders translated text with rich React component interpolation without `dangerouslySetInnerHTML`.
  * Subscribes reactively to language updates and supports strict type checking and autocompletion.
@@ -33,12 +30,12 @@ interface TransProps<T extends Record<string, any> = DefaultResources, Fallback
  *   values={{ name: "Alice" }}
  *   components={{
  *     bold: <strong />,
- *     link: <a href="/terms" />
+ *     link: (content) => <a href="/terms">{content}</a>
  *   }}
  * />
  * ```
  */
-declare function Trans<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>>({ i18nKey, values, components, translator: customTranslator, scope, fallback }: TransProps<T, Fallback, S, K>): ReactElement;
+declare function Trans<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>): ReactElement;
 
 /**
  * Global type registry for LocL React.
@@ -83,11 +80,10 @@ interface UseLocLResult<T extends Record<string, any> = DefaultResources, Fallba
 }
 interface UseTranslationResult<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined> extends UseLocLResult<T, Fallback, S> {
 }
-declare function useLocL<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<any, any, any, any, any>): UseLocLResult<T, Fallback, S>;
-declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(scope?: undefined, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
-declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
+declare function useLocL<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<T, Fallback, S, any, any> | LocL<any, any, any, any, any>): UseLocLResult<T, Fallback, S>;
+declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(scope?: undefined, customTranslator?: LocL<T, Fallback, any, any, any> | LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
+declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<T, Fallback, any, any, any> | LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
 interface BoundLocLProviderProps<T extends Record<string, any>, Fallback extends keyof T & string> {
-    /** Optional override translator; defaults to the instance passed to `createLocLReact` */
     translator?: LocL<any, any, any, any, any>;
     children: ReactNode;
 }
@@ -96,11 +92,13 @@ interface LocLReactSuite<T extends Record<string, any>, Fallback extends keyof T
     LocLProvider: (props: BoundLocLProviderProps<T, Fallback>) => ReactElement;
     useLocL: <S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<any, any, any, any, any>) => UseLocLResult<T, Fallback, S>;
     useTranslation: {
+        (): UseTranslationResult<T, Fallback, undefined>;
+        <S extends Scope<T, Fallback>>(scope: S): UseTranslationResult<T, Fallback, S>;
+        <S extends Scope<T, Fallback>[]>(scope: S): UseTranslationResult<T, Fallback, S>;
         (scope?: undefined, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
         <S extends ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
-        <S extends ScopeType<T, Fallback> = any>(scope?: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
     };
-    Trans: <S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>) => ReactElement;
+    Trans: <S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>) => ReactElement;
     translator: LocL<T, Fallback, any, any, any>;
 }
 /**
@@ -117,4 +115,4 @@ interface LocLReactSuite<T extends Record<string, any>, Fallback extends keyof T
  */
 declare function createLocLReact<T extends Record<string, any>, Fallback extends keyof T & string>(defaultTranslator: LocL<T, Fallback, any, any, any>): LocLReactSuite<T, Fallback>;
 
-export { type BoundLocLProviderProps, type DefaultFallback, type DefaultResources, LocLContext, LocLProvider, type LocLProviderProps, type LocLReactSuite, type LocLRegister, Trans, type TransKey, type TransProps, type UseLocLResult, type UseTranslationResult, createLocLReact, useLocL, useTranslation };
+export { type BoundLocLProviderProps, type DefaultFallback, type DefaultResources, LocLContext, LocLProvider, type LocLProviderProps, type LocLReactSuite, type LocLRegister, Trans, type TransKey, type TransProps, type TransValues, type UseLocLResult, type UseTranslationResult, createLocLReact, useLocL, useTranslation };

package/dist/react.d.ts

@@ -1,28 +1,25 @@
 import React, { ReactElement, ReactNode } from 'react';
-import { S as ScopeType, N as NestedKeyOf, T as TranslationObjectFor, P as PluralKeys, I as InterpolationOptions, a as LocL, c as Language } from './LocL-fN9Yari8.js';
+import { S as ScopeType, N as NestedKeyOf, T as TranslationObjectFor, f as PluralKeys, e as IsEmptyParams, c as ParamsFor, d as PathValue, I as InterpolationOptions, a as LocL, g as Language, h as Scope } from './LocL-v4yNIiKt.js';
 
 type TransKey<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined> = (NestedKeyOf<TranslationObjectFor<S, T, Fallback>> | PluralKeys<S, T, Fallback>) & string;
-interface TransProps<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>> {
-    /** The translation key to look up (with IDE autocomplete + fallback tolerance) */
+type TransValues<T extends Record<string, any>, Fallback extends keyof T & string, S extends ScopeType<T, Fallback>, K extends string> = IsEmptyParams<ParamsFor<PathValue<TranslationObjectFor<S, T, Fallback>, K>>> extends true ? InterpolationOptions | undefined : ParamsFor<PathValue<TranslationObjectFor<S, T, Fallback>, K>> & InterpolationOptions;
+type TransProps<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>> = {
+    /** Strictly typed translation key */
+    i18nKey: K;
+    values?: TransValues<T, Fallback, S, K>;
+    components?: Record<string, ReactElement | ((content: ReactNode) => ReactNode)>;
+    translator?: LocL<T, any, any, any, any>;
+    scope?: S;
+    fallback?: string;
+} | {
+    /** Dynamic / fallback key allowed ONLY when fallback string is provided */
     i18nKey: K | (string & {});
-    /** Values to interpolate into variable placeholders ({name}, {{name}}) */
     values?: InterpolationOptions;
-    /**
-     * Component elements or functions to substitute for `<tag>content</tag>`
-     * @example
-     * components={{
-     *   bold: <strong />,
-     *   link: (content) => <a href="/terms">{content}</a>
-     * }}
-     */
     components?: Record<string, ReactElement | ((content: ReactNode) => ReactNode)>;
-    /** Optional custom translator instance if not using LocLContext */
-    translator?: LocL<any, any, any, any, any>;
-    /** Optional namespace scope for the translation key */
+    translator?: LocL<T, any, any, any, any>;
     scope?: S;
-    /** Fallback string if key is not found */
-    fallback?: string;
-}
+    fallback: string;
+};
 /**
  * Renders translated text with rich React component interpolation without `dangerouslySetInnerHTML`.
  * Subscribes reactively to language updates and supports strict type checking and autocompletion.
@@ -33,12 +30,12 @@ interface TransProps<T extends Record<string, any> = DefaultResources, Fallback
  *   values={{ name: "Alice" }}
  *   components={{
  *     bold: <strong />,
- *     link: <a href="/terms" />
+ *     link: (content) => <a href="/terms">{content}</a>
  *   }}
  * />
  * ```
  */
-declare function Trans<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>>({ i18nKey, values, components, translator: customTranslator, scope, fallback }: TransProps<T, Fallback, S, K>): ReactElement;
+declare function Trans<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>): ReactElement;
 
 /**
  * Global type registry for LocL React.
@@ -83,11 +80,10 @@ interface UseLocLResult<T extends Record<string, any> = DefaultResources, Fallba
 }
 interface UseTranslationResult<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined> extends UseLocLResult<T, Fallback, S> {
 }
-declare function useLocL<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<any, any, any, any, any>): UseLocLResult<T, Fallback, S>;
-declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(scope?: undefined, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
-declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
+declare function useLocL<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<T, Fallback, S, any, any> | LocL<any, any, any, any, any>): UseLocLResult<T, Fallback, S>;
+declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>>(scope?: undefined, customTranslator?: LocL<T, Fallback, any, any, any> | LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
+declare function useTranslation<T extends Record<string, any> = DefaultResources, Fallback extends keyof T & string = DefaultFallback<T>, S extends ScopeType<T, Fallback> = ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<T, Fallback, any, any, any> | LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
 interface BoundLocLProviderProps<T extends Record<string, any>, Fallback extends keyof T & string> {
-    /** Optional override translator; defaults to the instance passed to `createLocLReact` */
     translator?: LocL<any, any, any, any, any>;
     children: ReactNode;
 }
@@ -96,11 +92,13 @@ interface LocLReactSuite<T extends Record<string, any>, Fallback extends keyof T
     LocLProvider: (props: BoundLocLProviderProps<T, Fallback>) => ReactElement;
     useLocL: <S extends ScopeType<T, Fallback> = undefined>(customTranslator?: LocL<any, any, any, any, any>) => UseLocLResult<T, Fallback, S>;
     useTranslation: {
+        (): UseTranslationResult<T, Fallback, undefined>;
+        <S extends Scope<T, Fallback>>(scope: S): UseTranslationResult<T, Fallback, S>;
+        <S extends Scope<T, Fallback>[]>(scope: S): UseTranslationResult<T, Fallback, S>;
         (scope?: undefined, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, undefined>;
         <S extends ScopeType<T, Fallback>>(scope: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
-        <S extends ScopeType<T, Fallback> = any>(scope?: S, customTranslator?: LocL<any, any, any, any, any>): UseTranslationResult<T, Fallback, S>;
     };
-    Trans: <S extends ScopeType<T, Fallback> = undefined, K extends string = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>) => ReactElement;
+    Trans: <S extends ScopeType<T, Fallback> = undefined, K extends TransKey<T, Fallback, S> = TransKey<T, Fallback, S>>(props: TransProps<T, Fallback, S, K>) => ReactElement;
     translator: LocL<T, Fallback, any, any, any>;
 }
 /**
@@ -117,4 +115,4 @@ interface LocLReactSuite<T extends Record<string, any>, Fallback extends keyof T
  */
 declare function createLocLReact<T extends Record<string, any>, Fallback extends keyof T & string>(defaultTranslator: LocL<T, Fallback, any, any, any>): LocLReactSuite<T, Fallback>;
 
-export { type BoundLocLProviderProps, type DefaultFallback, type DefaultResources, LocLContext, LocLProvider, type LocLProviderProps, type LocLReactSuite, type LocLRegister, Trans, type TransKey, type TransProps, type UseLocLResult, type UseTranslationResult, createLocLReact, useLocL, useTranslation };
+export { type BoundLocLProviderProps, type DefaultFallback, type DefaultResources, LocLContext, LocLProvider, type LocLProviderProps, type LocLReactSuite, type LocLRegister, Trans, type TransKey, type TransProps, type TransValues, type UseLocLResult, type UseTranslationResult, createLocLReact, useLocL, useTranslation };

package/dist/react.js

@@ -43,14 +43,15 @@ var import_react2 = require("react");
 // src/react/Trans.tsx
 var import_react = __toESM(require("react"));
 var import_jsx_runtime = require("react/jsx-runtime");
-function Trans({
-  i18nKey,
-  values,
-  components = {},
-  translator: customTranslator,
-  scope,
-  fallback
-}) {
+function Trans(props) {
+  const {
+    i18nKey,
+    values,
+    components = {},
+    translator: customTranslator,
+    scope,
+    fallback
+  } = props;
   const contextTranslator = (0, import_react.useContext)(LocLContext);
   const activeTranslator = customTranslator ?? contextTranslator;
   const getSnapshot = () => activeTranslator ? activeTranslator.getLanguage() : "";

package/dist/react.mjs

@@ -4,14 +4,15 @@ import { createContext, useContext as useContext2, useSyncExternalStore as useSy
 // src/react/Trans.tsx
 import React, { isValidElement, cloneElement, useContext, useMemo, useSyncExternalStore } from "react";
 import { Fragment, jsx } from "react/jsx-runtime";
-function Trans({
-  i18nKey,
-  values,
-  components = {},
-  translator: customTranslator,
-  scope,
-  fallback
-}) {
+function Trans(props) {
+  const {
+    i18nKey,
+    values,
+    components = {},
+    translator: customTranslator,
+    scope,
+    fallback
+  } = props;
   const contextTranslator = useContext(LocLContext);
   const activeTranslator = customTranslator ?? contextTranslator;
   const getSnapshot = () => activeTranslator ? activeTranslator.getLanguage() : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locl-js",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Modern TypeScript internationalization (i18n) library with type-safety, performance, and backend usability",
   "license": "MIT",
   "author": "Sztrida Sámuel <sztsam@gmail.com>",