@pantho075/locale 0.1.1 → 0.1.3

package/README.md

@@ -17,6 +17,8 @@ export function Example() {
 }
 ```
 
+The example above uses the package's built-in sample bundles (`en`, `bn`, `ne`). For real apps you'll want to use your own data — see [Using your own translations](#using-your-own-translations) below.
+
 ## Install
 
 ```bash
@@ -53,28 +55,166 @@ const { title, home } = getTranslation("en");
 console.log(title, home.header, home.footer);
 ```
 
-### Adding your own keys
+## Using your own translations
 
-Edit `src/locales/en.ts` (and `bn.ts`, `ne.ts`) in this package, or fork it. Each file is just a plain object exported as default:
+The package ships with three sample locales for demo purposes. To use your own translation data, call `setLocales(...)` once at app startup with a map of language code → bundle. After that, `getTranslation` and `useTranslation` return your data.
 
 ```ts
-// src/locales/en.ts
-const data = {
-  title: "Welcome",
-  home: {
-    header: "Hello",
-    footer: "Goodbye",
-  },
-  greeting: "Hi there",
-};
+// src/translations.ts
+import { setLocales } from "@pantho075/locale";
+import en from "./locales/en";
+import bn from "./locales/bn";
+
+setLocales({ en, bn });
+```
+
+Then anywhere in your app:
 
-export default data;
+```ts
+import { useTranslation } from "@pantho075/locale";
+
+function Greeting({ lang }: { lang: string }) {
+  const t = useTranslation<typeof en>(lang);
+  return <h1>{t.title}</h1>;
+}
 ```
 
+### Semantics
+
+- **`setLocales` replaces the entire map** — it does not merge. If you call `setLocales({ en })`, the previous `bn`/`ne` entries are gone and will return `{}`. Pass every locale you want available.
+- **One-shot setup.** Call `setLocales` at app startup. Calling it later does not invalidate previously memoized `useTranslation` results — if you need to swap locales at runtime, hold `lang` in reactive state and let React re-run the hook.
+- **Missing languages return `{}`** (the same frozen empty object every time — safe to compare with `===`).
+- **Missing keys return `undefined`** — standard JS object semantics. No proxy wrapping.
+
 ### Adding a new locale
 
-1. Create `src/locales/<code>.ts` that exports the locale object as default.
-2. Import it in `src/getTranslation.ts` and add it to the `locales` map.
+You don't need to touch this package's source. Just add a file in your app and register it via `setLocales`:
+
+```ts
+// src/locales/ja.ts
+export default {
+  title: "こんにちは",
+  home: { header: "ヘッダー", footer: "フッター" },
+};
+```
+
+```ts
+// src/translations.ts
+import { setLocales } from "@pantho075/locale";
+import en from "./locales/en";
+import ja from "./locales/ja";
+
+setLocales({ en, ja });
+```
+
+## Language switching
+
+The hooks accept any `string` for `lang`, but for a real app you'll usually want a constrained set of codes, a default fallback, and a UI control to switch between them. Build those once in your app — the package doesn't ship them because they tend to be tied to your auth/session model.
+
+### Typing the supported codes
+
+```ts
+// src/i18n/lang.ts
+
+/** Matches `AuthUser.lang` from the verify-token response. */
+export type Lang = "en" | "bn" | "ne";
+
+export const SUPPORTED_LANGS: readonly Lang[] = ["en", "bn", "ne"] as const;
+export const DEFAULT_LANG: Lang = "en";
+
+/**
+ * Narrow an arbitrary value (e.g. `useAuthStore((s) => s.user?.lang)`,
+ * which is `Lang | undefined`) to one of our `Lang` codes, falling back
+ * to `DEFAULT_LANG`. Pass the result to `getTranslation` / `useTranslation`.
+ */
+export function resolveLang(value: unknown): Lang {
+  return typeof value === "string" &&
+    (SUPPORTED_LANGS as readonly string[]).includes(value)
+    ? (value as Lang)
+    : DEFAULT_LANG;
+}
+```
+
+### Reading translations in components
+
+```tsx
+// src/components/Greeting.tsx
+import { useTranslation } from "@pantho075/locale";
+import type { Translations } from "@/types/localeTypes";
+import { resolveLang } from "@/i18n/lang";
+import { useAuthStore } from "@/stores/auth";
+
+export function Greeting() {
+  const lang = useAuthStore((s) => s.user?.lang);
+  const t = useTranslation<Translations>(resolveLang(lang));
+  return <h1>{t.title}</h1>;
+}
+```
+
+…and in non-React / server code:
+
+```ts
+import { getTranslation } from "@pantho075/locale";
+import { resolveLang } from "@/i18n/lang";
+import type { Translations } from "@/types/localeTypes";
+
+export async function loadGreeting() {
+  const { loading } = getTranslation<Translations>(resolveLang("bn"));
+  return loading;
+}
+```
+
+### Switching languages at runtime
+
+The package ships `switchLocale(lang)` — call it and every component using `useTranslation()` (no argument) re-renders with the new bundle. Combined with `setLocales(...)` at startup, this is the whole switching story.
+
+```tsx
+// src/components/LanguageSwitcher.tsx
+import { switchLocale } from "@pantho075/locale";
+import { useAuthStore } from "@/stores/auth";
+import type { Lang } from "@/i18n/lang";
+
+const LABELS: Record<Lang, string> = {
+  en: "English",
+  bn: "বাংলা",
+  ne: "नेपाली",
+};
+
+export function LanguageSwitcher() {
+  const user = useAuthStore((s) => s.user);
+
+  return (
+    <select
+      value={user?.lang ?? "en"}
+      onChange={(e) => {
+        const next = e.target.value as Lang;
+        // Persist to your auth store / cookie / localStorage…
+        useAuthStore.setState((s) => ({
+          user: s.user ? { ...s.user, lang: next } : s.user,
+        }));
+        // And tell the package. Components using useTranslation() with no
+        // argument re-render automatically.
+        switchLocale(next);
+      }}
+    >
+      {(Object.keys(LABELS) as Lang[]).map((code) => (
+        <option key={code} value={code}>{LABELS[code]}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+Components don't need to change. They call `useTranslation()` with no argument:
+
+```tsx
+// was: const t = useTranslation<Translations>(lang);
+// now: same hook, no arg → subscribes to the active lang
+const t = useTranslation<Translations>();
+return <h1>{t.title}</h1>;
+```
+
+`useTranslation` keeps its existing `(lang)` signature for callers that want to pin a language. The two modes coexist — explicit arg wins over the active lang.
 
 ## API
 
@@ -93,26 +233,43 @@ interface English {
 const en = getTranslation<English>("en");
 ```
 
-### `useTranslation<T>(lang: string): T`
+### `useTranslation<T>(lang?: string): T`
+
+React hook wrapping `getTranslation`. Two modes:
 
-React hook wrapping `getTranslation`. Memoized on `lang` — same language returns the same object reference across re-renders.
+- **Explicit** — `useTranslation('en')` is memoized on `'en'`. Same language returns the same object reference across re-renders.
+- **Active** — `useTranslation()` (no argument) subscribes to the package's currently active language and returns `getTranslation(activeLang)`. Components re-render automatically when `switchLocale(...)` is called.
 
 ```ts
 import { useTranslation } from "@pantho075/locale";
 
-const { title } = useTranslation("en"); // string | undefined
-const en = useTranslation<English>("en"); // typed
+const { title } = useTranslation("en");      // explicit, pinned
+const t = useTranslation<English>();         // active, subscribes
+```
+
+### `switchLocale(lang: string): void`
+
+Sets the package's active language and notifies every `useTranslation()` subscriber to re-render. Idempotent: calling with the current value is a no-op. Unknown values are accepted and fall back to the empty bundle the same way `getTranslation(unknown)` does.
+
+```ts
+import { switchLocale } from "@pantho075/locale";
+
+switchLocale("bn");
 ```
 
+See [Switching languages at runtime](#switching-languages-at-runtime).
+
+### `setLocales<T>(locales: Record<string, T>): void`
+
+Replaces the package's internal locale registry. Call once at app startup to swap in your own bundles. See [Using your own translations](#using-your-own-translations).
+
 ### `TranslationData`
 
 The default return type — `Record<string, unknown>`. Most consumers will constrain this with their own interface via the generic.
 
 ## Why no JSON files?
 
-Because the package ships its own locale data, it doesn't need to scan the consumer's filesystem, doesn't need a bundler alias, and doesn't need `resolveJsonModule`. The data is just regular TypeScript that gets tree-shaken and bundled like any other code.
-
-If you want to override locales from your own app, you can fork the package and build your own locale map.
+Translation data is just regular TypeScript that gets tree-shaken and bundled like any other code. `setLocales` lets your app own its own locale files without forking the package or shipping JSON.
 
 ## License
 

package/dist/index.cjs

@@ -39,14 +39,49 @@ var locales = {
   bn: bn_default,
   ne: ne_default
 };
+function setLocales(next) {
+  locales = next;
+}
 function getTranslation(lang) {
   return locales[lang] ?? EMPTY;
 }
+
+// src/switchLocale.ts
+var activeLang;
+var listeners = /* @__PURE__ */ new Set();
+function subscribe(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function getActiveLang() {
+  return activeLang;
+}
+function switchLocale(lang) {
+  if (lang === activeLang) return;
+  activeLang = lang;
+  for (const listener of [...listeners]) {
+    listener();
+  }
+}
+
+// src/useTranslation.ts
 function useTranslation(lang) {
+  if (lang === void 0) {
+    const active = react.useSyncExternalStore(
+      subscribe,
+      getActiveLang,
+      () => void 0
+    );
+    return getTranslation(active ?? "");
+  }
   return react.useMemo(() => getTranslation(lang), [lang]);
 }
 
 exports.getTranslation = getTranslation;
+exports.setLocales = setLocales;
+exports.switchLocale = switchLocale;
 exports.useTranslation = useTranslation;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/locales/bn.ts","../src/locales/en.ts","../src/locales/ne.ts","../src/getTranslation.ts","../src/useTranslation.ts"],"names":["data","useMemo"],"mappings":";;;;;AAAA,IAAM,IAAA,GAAO;AAAA,EACX,KAAA,EAAO,4CAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gCAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQ,IAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACFf,IAAM,KAAA,GAAyB,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAQ/C,IAAM,OAAA,GAA2C;AAAA,EAC/C,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA;AACF,CAAA;AASO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAQ,OAAA,CAAQ,IAAI,CAAA,IAAK,KAAA;AAC3B;ACpBO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAOC,cAAQ,MAAM,cAAA,CAAkB,IAAI,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AACtD","file":"index.cjs","sourcesContent":["const data = {\n  title: \"শিরোনাম\",\n  home: {\n    header: \"হেডার\",\n    footer: \"ফুটার\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","import bn from \"./locales/bn\";\nimport en from \"./locales/en\";\nimport ne from \"./locales/ne\";\nimport type { TranslationData } from \"./types\";\n\n/** Shared empty fallback for unknown languages. Frozen so it can't be mutated. */\nconst EMPTY: TranslationData = Object.freeze({});\n\n/**\n * Locale registry. Adding a new language means:\n *   1. drop a `src/locales/<code>.ts` that exports the locale object as default\n *   2. import it here\n *   3. add it to this map\n */\nconst locales: Record<string, TranslationData> = {\n  en,\n  bn,\n  ne,\n};\n\n/**\n * Returns the translation bundle for the given language code.\n * Unknown / undefined / empty values fall back to a stable empty object.\n *\n * Framework-agnostic: works in React, Next.js server components, Vue,\n * Svelte, or vanilla Node scripts.\n */\nexport function getTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return (locales[lang] ?? EMPTY) as T;\n}\n","import { useMemo } from \"react\";\nimport { getTranslation } from \"./getTranslation\";\nimport type { TranslationData } from \"./types\";\n\n/**\n * React hook: returns the translation bundle for the given language.\n *\n * Memoized on `lang`, so the same language produces a stable object\n * reference across re-renders. Switching language swaps the reference\n * (and any consumers destructuring top-level keys will re-render).\n */\nexport function useTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return useMemo(() => getTranslation<T>(lang), [lang]);\n}\n"]}
+{"version":3,"sources":["../src/locales/bn.ts","../src/locales/en.ts","../src/locales/ne.ts","../src/getTranslation.ts","../src/switchLocale.ts","../src/useTranslation.ts"],"names":["data","useSyncExternalStore","useMemo"],"mappings":";;;;;AAAA,IAAM,IAAA,GAAO;AAAA,EACX,KAAA,EAAO,4CAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gCAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQ,IAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACFf,IAAM,KAAA,GAAyB,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAY/C,IAAI,OAAA,GAA2C;AAAA,EAC7C,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA;AACF,CAAA;AAuBO,SAAS,WACd,IAAA,EACM;AACN,EAAA,OAAA,GAAU,IAAA;AACZ;AASO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAQ,OAAA,CAAQ,IAAI,CAAA,IAAK,KAAA;AAC3B;;;ACjDA,IAAI,UAAA;AAEJ,IAAM,SAAA,uBAAgB,GAAA,EAAgB;AAG/B,SAAS,UAAU,QAAA,EAAkC;AAC1D,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AAMO,SAAS,aAAA,GAAoC;AAClD,EAAA,OAAO,UAAA;AACT;AAaO,SAAS,aAAa,IAAA,EAAoB;AAC/C,EAAA,IAAI,SAAS,UAAA,EAAY;AACzB,EAAA,UAAA,GAAa,IAAA;AAGb,EAAA,KAAA,MAAW,QAAA,IAAY,CAAC,GAAG,SAAS,CAAA,EAAG;AACrC,IAAA,QAAA,EAAS;AAAA,EACX;AACF;;;AC7BO,SAAS,eACd,IAAA,EACG;AACH,EAAA,IAAI,SAAS,MAAA,EAAW;AAKtB,IAAA,MAAM,MAAA,GAASC,0BAAA;AAAA,MACb,SAAA;AAAA,MACA,aAAA;AAAA,MACA,MAAM;AAAA,KACR;AACA,IAAA,OAAO,cAAA,CAAkB,UAAU,EAAE,CAAA;AAAA,EACvC;AAEA,EAAA,OAAOC,cAAQ,MAAM,cAAA,CAAkB,IAAI,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AACtD","file":"index.cjs","sourcesContent":["const data = {\n  title: \"শিরোনাম\",\n  home: {\n    header: \"হেডার\",\n    footer: \"ফুটার\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","import bn from \"./locales/bn\";\nimport en from \"./locales/en\";\nimport ne from \"./locales/ne\";\nimport type { TranslationData } from \"./types\";\n\n/** Shared empty fallback for unknown languages. Frozen so it can't be mutated. */\nconst EMPTY: TranslationData = Object.freeze({});\n\n/**\n * Locale registry. Adding a new language means:\n *   1. drop a `src/locales/<code>.ts` that exports the locale object as default\n *   2. import it here\n *   3. add it to this map\n *\n * These entries are the default sample bundles. Consumers that need to\n * translate their own data should call `setLocales(...)` once at app\n * startup to replace the entire map — see the README.\n */\nlet locales: Record<string, TranslationData> = {\n  en,\n  bn,\n  ne,\n};\n\n/**\n * Replace the package's locale registry with the consumer's bundles.\n *\n * The new map **replaces** the existing entries wholesale — it does\n * not merge. Pass every locale you want available; anything missing\n * from `next` will fall back to the empty bundle.\n *\n * This is intended as one-shot app startup configuration. It does\n * not invalidate previously memoized `useTranslation` results — if a\n * consumer swaps locales at runtime, they should pass `lang` as\n * reactive state so React re-runs the hook.\n *\n * @example\n * ```ts\n * import { setLocales } from \"@pantho075/locale\";\n * import { en } from \"./locales/en\";\n * import { bn } from \"./locales/bn\";\n *\n * setLocales({ en, bn });\n * ```\n */\nexport function setLocales<T extends object = TranslationData>(\n  next: Record<string, T>,\n): void {\n  locales = next as unknown as Record<string, TranslationData>;\n}\n\n/**\n * Returns the translation bundle for the given language code.\n * Unknown / undefined / empty values fall back to a stable empty object.\n *\n * Framework-agnostic: works in React, Next.js server components, Vue,\n * Svelte, or vanilla Node scripts.\n */\nexport function getTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return (locales[lang] ?? EMPTY) as T;\n}\n","/**\n * Module-scoped active language + listener channel.\n *\n * The package exposes one mutable concept: the currently active language.\n * `switchLocale(...)` mutates it; `subscribe` / `getActiveLang` let React\n * hooks observe changes via `useSyncExternalStore`.\n *\n * SSR safety: `getActiveLang` is called during render and must be\n * deterministic. We keep `activeLang` as a plain `string | undefined`\n * so server and client agree on `undefined` until `switchLocale` fires\n * on the client (which is exactly when re-renders are valid).\n */\n\nlet activeLang: string | undefined;\n\nconst listeners = new Set<() => void>();\n\n/** Subscribe to active-lang changes. Returns an unsubscribe fn. */\nexport function subscribe(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * Read the current active language. Returns `undefined` until\n * `switchLocale` has been called for the first time.\n */\nexport function getActiveLang(): string | undefined {\n  return activeLang;\n}\n\n/**\n * Set the package's active language and notify all subscribers.\n *\n * The argument is a key from the map last passed to `setLocales(...)`.\n * Unknown values are accepted — they fall back to the empty bundle the\n * same way `getTranslation(unknown)` does. This keeps the API permissive\n * and matches the rest of the package.\n *\n * Idempotent: calling with the current active value is a no-op (no\n * listener notifications, no re-renders).\n */\nexport function switchLocale(lang: string): void {\n  if (lang === activeLang) return;\n  activeLang = lang;\n  // Snapshot first — listeners may unsubscribe themselves during the\n  // notification, and mutating the Set mid-iteration would skip them.\n  for (const listener of [...listeners]) {\n    listener();\n  }\n}\n","import { useMemo, useSyncExternalStore } from \"react\";\nimport { getTranslation } from \"./getTranslation\";\nimport {\n  getActiveLang,\n  subscribe as subscribeActiveLang,\n} from \"./switchLocale\";\nimport type { TranslationData } from \"./types\";\n\n/**\n * React hook: returns the translation bundle for the given language,\n * or — when called with no argument — for the package's currently\n * active language (set via `switchLocale`).\n *\n * Two modes:\n *\n * - **Explicit** — `useTranslation('en')` is memoized on `'en'`. Same\n *   language produces a stable object reference across re-renders.\n *   Switching the argument swaps the reference.\n *\n * - **Active** — `useTranslation()` subscribes to the active language\n *   and returns `getTranslation(activeLang)`. Components re-render\n *   automatically when `switchLocale(...)` is called.\n */\nexport function useTranslation<T extends object = TranslationData>(\n  lang?: string,\n): T {\n  if (lang === undefined) {\n    // `useSyncExternalStore` requires the snapshot getter to return the\n    // same value across calls when nothing has changed. Our snapshot is\n    // `activeLang ?? ''` so SSR (where activeLang is undefined) and the\n    // first client render agree before any `switchLocale` fires.\n    const active = useSyncExternalStore(\n      subscribeActiveLang,\n      getActiveLang,\n      () => undefined,\n    );\n    return getTranslation<T>(active ?? \"\");\n  }\n\n  return useMemo(() => getTranslation<T>(lang), [lang]);\n}\n"]}

package/dist/index.d.cts

@@ -4,6 +4,28 @@
  */
 type TranslationData = Record<string, unknown>;
 
+/**
+ * Replace the package's locale registry with the consumer's bundles.
+ *
+ * The new map **replaces** the existing entries wholesale — it does
+ * not merge. Pass every locale you want available; anything missing
+ * from `next` will fall back to the empty bundle.
+ *
+ * This is intended as one-shot app startup configuration. It does
+ * not invalidate previously memoized `useTranslation` results — if a
+ * consumer swaps locales at runtime, they should pass `lang` as
+ * reactive state so React re-runs the hook.
+ *
+ * @example
+ * ```ts
+ * import { setLocales } from "@pantho075/locale";
+ * import { en } from "./locales/en";
+ * import { bn } from "./locales/bn";
+ *
+ * setLocales({ en, bn });
+ * ```
+ */
+declare function setLocales<T extends object = TranslationData>(next: Record<string, T>): void;
 /**
  * Returns the translation bundle for the given language code.
  * Unknown / undefined / empty values fall back to a stable empty object.
@@ -14,12 +36,33 @@ type TranslationData = Record<string, unknown>;
 declare function getTranslation<T extends object = TranslationData>(lang: string): T;
 
 /**
- * React hook: returns the translation bundle for the given language.
+ * React hook: returns the translation bundle for the given language,
+ * or — when called with no argument — for the package's currently
+ * active language (set via `switchLocale`).
+ *
+ * Two modes:
+ *
+ * - **Explicit** — `useTranslation('en')` is memoized on `'en'`. Same
+ *   language produces a stable object reference across re-renders.
+ *   Switching the argument swaps the reference.
+ *
+ * - **Active** — `useTranslation()` subscribes to the active language
+ *   and returns `getTranslation(activeLang)`. Components re-render
+ *   automatically when `switchLocale(...)` is called.
+ */
+declare function useTranslation<T extends object = TranslationData>(lang?: string): T;
+
+/**
+ * Set the package's active language and notify all subscribers.
+ *
+ * The argument is a key from the map last passed to `setLocales(...)`.
+ * Unknown values are accepted — they fall back to the empty bundle the
+ * same way `getTranslation(unknown)` does. This keeps the API permissive
+ * and matches the rest of the package.
  *
- * Memoized on `lang`, so the same language produces a stable object
- * reference across re-renders. Switching language swaps the reference
- * (and any consumers destructuring top-level keys will re-render).
+ * Idempotent: calling with the current active value is a no-op (no
+ * listener notifications, no re-renders).
  */
-declare function useTranslation<T extends object = TranslationData>(lang: string): T;
+declare function switchLocale(lang: string): void;
 
-export { type TranslationData, getTranslation, useTranslation };
+export { type TranslationData, getTranslation, setLocales, switchLocale, useTranslation };

package/dist/index.d.ts

@@ -4,6 +4,28 @@
  */
 type TranslationData = Record<string, unknown>;
 
+/**
+ * Replace the package's locale registry with the consumer's bundles.
+ *
+ * The new map **replaces** the existing entries wholesale — it does
+ * not merge. Pass every locale you want available; anything missing
+ * from `next` will fall back to the empty bundle.
+ *
+ * This is intended as one-shot app startup configuration. It does
+ * not invalidate previously memoized `useTranslation` results — if a
+ * consumer swaps locales at runtime, they should pass `lang` as
+ * reactive state so React re-runs the hook.
+ *
+ * @example
+ * ```ts
+ * import { setLocales } from "@pantho075/locale";
+ * import { en } from "./locales/en";
+ * import { bn } from "./locales/bn";
+ *
+ * setLocales({ en, bn });
+ * ```
+ */
+declare function setLocales<T extends object = TranslationData>(next: Record<string, T>): void;
 /**
  * Returns the translation bundle for the given language code.
  * Unknown / undefined / empty values fall back to a stable empty object.
@@ -14,12 +36,33 @@ type TranslationData = Record<string, unknown>;
 declare function getTranslation<T extends object = TranslationData>(lang: string): T;
 
 /**
- * React hook: returns the translation bundle for the given language.
+ * React hook: returns the translation bundle for the given language,
+ * or — when called with no argument — for the package's currently
+ * active language (set via `switchLocale`).
+ *
+ * Two modes:
+ *
+ * - **Explicit** — `useTranslation('en')` is memoized on `'en'`. Same
+ *   language produces a stable object reference across re-renders.
+ *   Switching the argument swaps the reference.
+ *
+ * - **Active** — `useTranslation()` subscribes to the active language
+ *   and returns `getTranslation(activeLang)`. Components re-render
+ *   automatically when `switchLocale(...)` is called.
+ */
+declare function useTranslation<T extends object = TranslationData>(lang?: string): T;
+
+/**
+ * Set the package's active language and notify all subscribers.
+ *
+ * The argument is a key from the map last passed to `setLocales(...)`.
+ * Unknown values are accepted — they fall back to the empty bundle the
+ * same way `getTranslation(unknown)` does. This keeps the API permissive
+ * and matches the rest of the package.
  *
- * Memoized on `lang`, so the same language produces a stable object
- * reference across re-renders. Switching language swaps the reference
- * (and any consumers destructuring top-level keys will re-render).
+ * Idempotent: calling with the current active value is a no-op (no
+ * listener notifications, no re-renders).
  */
-declare function useTranslation<T extends object = TranslationData>(lang: string): T;
+declare function switchLocale(lang: string): void;
 
-export { type TranslationData, getTranslation, useTranslation };
+export { type TranslationData, getTranslation, setLocales, switchLocale, useTranslation };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { useMemo } from 'react';
+import { useSyncExternalStore, useMemo } from 'react';
 
 // src/locales/bn.ts
 var data = {
@@ -37,13 +37,46 @@ var locales = {
   bn: bn_default,
   ne: ne_default
 };
+function setLocales(next) {
+  locales = next;
+}
 function getTranslation(lang) {
   return locales[lang] ?? EMPTY;
 }
+
+// src/switchLocale.ts
+var activeLang;
+var listeners = /* @__PURE__ */ new Set();
+function subscribe(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function getActiveLang() {
+  return activeLang;
+}
+function switchLocale(lang) {
+  if (lang === activeLang) return;
+  activeLang = lang;
+  for (const listener of [...listeners]) {
+    listener();
+  }
+}
+
+// src/useTranslation.ts
 function useTranslation(lang) {
+  if (lang === void 0) {
+    const active = useSyncExternalStore(
+      subscribe,
+      getActiveLang,
+      () => void 0
+    );
+    return getTranslation(active ?? "");
+  }
   return useMemo(() => getTranslation(lang), [lang]);
 }
 
-export { getTranslation, useTranslation };
+export { getTranslation, setLocales, switchLocale, useTranslation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/locales/bn.ts","../src/locales/en.ts","../src/locales/ne.ts","../src/getTranslation.ts","../src/useTranslation.ts"],"names":["data"],"mappings":";;;AAAA,IAAM,IAAA,GAAO;AAAA,EACX,KAAA,EAAO,4CAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gCAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQ,IAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACFf,IAAM,KAAA,GAAyB,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAQ/C,IAAM,OAAA,GAA2C;AAAA,EAC/C,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA;AACF,CAAA;AASO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAQ,OAAA,CAAQ,IAAI,CAAA,IAAK,KAAA;AAC3B;ACpBO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAO,QAAQ,MAAM,cAAA,CAAkB,IAAI,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AACtD","file":"index.js","sourcesContent":["const data = {\n  title: \"শিরোনাম\",\n  home: {\n    header: \"হেডার\",\n    footer: \"ফুটার\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","import bn from \"./locales/bn\";\nimport en from \"./locales/en\";\nimport ne from \"./locales/ne\";\nimport type { TranslationData } from \"./types\";\n\n/** Shared empty fallback for unknown languages. Frozen so it can't be mutated. */\nconst EMPTY: TranslationData = Object.freeze({});\n\n/**\n * Locale registry. Adding a new language means:\n *   1. drop a `src/locales/<code>.ts` that exports the locale object as default\n *   2. import it here\n *   3. add it to this map\n */\nconst locales: Record<string, TranslationData> = {\n  en,\n  bn,\n  ne,\n};\n\n/**\n * Returns the translation bundle for the given language code.\n * Unknown / undefined / empty values fall back to a stable empty object.\n *\n * Framework-agnostic: works in React, Next.js server components, Vue,\n * Svelte, or vanilla Node scripts.\n */\nexport function getTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return (locales[lang] ?? EMPTY) as T;\n}\n","import { useMemo } from \"react\";\nimport { getTranslation } from \"./getTranslation\";\nimport type { TranslationData } from \"./types\";\n\n/**\n * React hook: returns the translation bundle for the given language.\n *\n * Memoized on `lang`, so the same language produces a stable object\n * reference across re-renders. Switching language swaps the reference\n * (and any consumers destructuring top-level keys will re-render).\n */\nexport function useTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return useMemo(() => getTranslation<T>(lang), [lang]);\n}\n"]}
+{"version":3,"sources":["../src/locales/bn.ts","../src/locales/en.ts","../src/locales/ne.ts","../src/getTranslation.ts","../src/switchLocale.ts","../src/useTranslation.ts"],"names":["data"],"mappings":";;;AAAA,IAAM,IAAA,GAAO;AAAA,EACX,KAAA,EAAO,4CAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gCAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQ,IAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACRf,IAAMA,KAAAA,GAAO;AAAA,EACX,KAAA,EAAO,WAAA;AAAA,EACP,IAAA,EAAM;AAAA,IACJ,MAAA,EAAQ,gBAAA;AAAA,IACR,MAAA,EAAQ;AAAA;AAEZ,CAAA;AAEA,IAAO,UAAA,GAAQA,KAAAA;;;ACFf,IAAM,KAAA,GAAyB,MAAA,CAAO,MAAA,CAAO,EAAE,CAAA;AAY/C,IAAI,OAAA,GAA2C;AAAA,EAC7C,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA,UAAA;AAAA,EACA,EAAA,EAAA;AACF,CAAA;AAuBO,SAAS,WACd,IAAA,EACM;AACN,EAAA,OAAA,GAAU,IAAA;AACZ;AASO,SAAS,eACd,IAAA,EACG;AACH,EAAA,OAAQ,OAAA,CAAQ,IAAI,CAAA,IAAK,KAAA;AAC3B;;;ACjDA,IAAI,UAAA;AAEJ,IAAM,SAAA,uBAAgB,GAAA,EAAgB;AAG/B,SAAS,UAAU,QAAA,EAAkC;AAC1D,EAAA,SAAA,CAAU,IAAI,QAAQ,CAAA;AACtB,EAAA,OAAO,MAAM;AACX,IAAA,SAAA,CAAU,OAAO,QAAQ,CAAA;AAAA,EAC3B,CAAA;AACF;AAMO,SAAS,aAAA,GAAoC;AAClD,EAAA,OAAO,UAAA;AACT;AAaO,SAAS,aAAa,IAAA,EAAoB;AAC/C,EAAA,IAAI,SAAS,UAAA,EAAY;AACzB,EAAA,UAAA,GAAa,IAAA;AAGb,EAAA,KAAA,MAAW,QAAA,IAAY,CAAC,GAAG,SAAS,CAAA,EAAG;AACrC,IAAA,QAAA,EAAS;AAAA,EACX;AACF;;;AC7BO,SAAS,eACd,IAAA,EACG;AACH,EAAA,IAAI,SAAS,MAAA,EAAW;AAKtB,IAAA,MAAM,MAAA,GAAS,oBAAA;AAAA,MACb,SAAA;AAAA,MACA,aAAA;AAAA,MACA,MAAM;AAAA,KACR;AACA,IAAA,OAAO,cAAA,CAAkB,UAAU,EAAE,CAAA;AAAA,EACvC;AAEA,EAAA,OAAO,QAAQ,MAAM,cAAA,CAAkB,IAAI,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AACtD","file":"index.js","sourcesContent":["const data = {\n  title: \"শিরোনাম\",\n  home: {\n    header: \"হেডার\",\n    footer: \"ফুটার\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","const data = {\n  title: \"the title\",\n  home: {\n    header: \"this is header\",\n    footer: \"this is footer\",\n  },\n};\n\nexport default data;\n","import bn from \"./locales/bn\";\nimport en from \"./locales/en\";\nimport ne from \"./locales/ne\";\nimport type { TranslationData } from \"./types\";\n\n/** Shared empty fallback for unknown languages. Frozen so it can't be mutated. */\nconst EMPTY: TranslationData = Object.freeze({});\n\n/**\n * Locale registry. Adding a new language means:\n *   1. drop a `src/locales/<code>.ts` that exports the locale object as default\n *   2. import it here\n *   3. add it to this map\n *\n * These entries are the default sample bundles. Consumers that need to\n * translate their own data should call `setLocales(...)` once at app\n * startup to replace the entire map — see the README.\n */\nlet locales: Record<string, TranslationData> = {\n  en,\n  bn,\n  ne,\n};\n\n/**\n * Replace the package's locale registry with the consumer's bundles.\n *\n * The new map **replaces** the existing entries wholesale — it does\n * not merge. Pass every locale you want available; anything missing\n * from `next` will fall back to the empty bundle.\n *\n * This is intended as one-shot app startup configuration. It does\n * not invalidate previously memoized `useTranslation` results — if a\n * consumer swaps locales at runtime, they should pass `lang` as\n * reactive state so React re-runs the hook.\n *\n * @example\n * ```ts\n * import { setLocales } from \"@pantho075/locale\";\n * import { en } from \"./locales/en\";\n * import { bn } from \"./locales/bn\";\n *\n * setLocales({ en, bn });\n * ```\n */\nexport function setLocales<T extends object = TranslationData>(\n  next: Record<string, T>,\n): void {\n  locales = next as unknown as Record<string, TranslationData>;\n}\n\n/**\n * Returns the translation bundle for the given language code.\n * Unknown / undefined / empty values fall back to a stable empty object.\n *\n * Framework-agnostic: works in React, Next.js server components, Vue,\n * Svelte, or vanilla Node scripts.\n */\nexport function getTranslation<T extends object = TranslationData>(\n  lang: string,\n): T {\n  return (locales[lang] ?? EMPTY) as T;\n}\n","/**\n * Module-scoped active language + listener channel.\n *\n * The package exposes one mutable concept: the currently active language.\n * `switchLocale(...)` mutates it; `subscribe` / `getActiveLang` let React\n * hooks observe changes via `useSyncExternalStore`.\n *\n * SSR safety: `getActiveLang` is called during render and must be\n * deterministic. We keep `activeLang` as a plain `string | undefined`\n * so server and client agree on `undefined` until `switchLocale` fires\n * on the client (which is exactly when re-renders are valid).\n */\n\nlet activeLang: string | undefined;\n\nconst listeners = new Set<() => void>();\n\n/** Subscribe to active-lang changes. Returns an unsubscribe fn. */\nexport function subscribe(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/**\n * Read the current active language. Returns `undefined` until\n * `switchLocale` has been called for the first time.\n */\nexport function getActiveLang(): string | undefined {\n  return activeLang;\n}\n\n/**\n * Set the package's active language and notify all subscribers.\n *\n * The argument is a key from the map last passed to `setLocales(...)`.\n * Unknown values are accepted — they fall back to the empty bundle the\n * same way `getTranslation(unknown)` does. This keeps the API permissive\n * and matches the rest of the package.\n *\n * Idempotent: calling with the current active value is a no-op (no\n * listener notifications, no re-renders).\n */\nexport function switchLocale(lang: string): void {\n  if (lang === activeLang) return;\n  activeLang = lang;\n  // Snapshot first — listeners may unsubscribe themselves during the\n  // notification, and mutating the Set mid-iteration would skip them.\n  for (const listener of [...listeners]) {\n    listener();\n  }\n}\n","import { useMemo, useSyncExternalStore } from \"react\";\nimport { getTranslation } from \"./getTranslation\";\nimport {\n  getActiveLang,\n  subscribe as subscribeActiveLang,\n} from \"./switchLocale\";\nimport type { TranslationData } from \"./types\";\n\n/**\n * React hook: returns the translation bundle for the given language,\n * or — when called with no argument — for the package's currently\n * active language (set via `switchLocale`).\n *\n * Two modes:\n *\n * - **Explicit** — `useTranslation('en')` is memoized on `'en'`. Same\n *   language produces a stable object reference across re-renders.\n *   Switching the argument swaps the reference.\n *\n * - **Active** — `useTranslation()` subscribes to the active language\n *   and returns `getTranslation(activeLang)`. Components re-render\n *   automatically when `switchLocale(...)` is called.\n */\nexport function useTranslation<T extends object = TranslationData>(\n  lang?: string,\n): T {\n  if (lang === undefined) {\n    // `useSyncExternalStore` requires the snapshot getter to return the\n    // same value across calls when nothing has changed. Our snapshot is\n    // `activeLang ?? ''` so SSR (where activeLang is undefined) and the\n    // first client render agree before any `switchLocale` fires.\n    const active = useSyncExternalStore(\n      subscribeActiveLang,\n      getActiveLang,\n      () => undefined,\n    );\n    return getTranslation<T>(active ?? \"\");\n  }\n\n  return useMemo(() => getTranslation<T>(lang), [lang]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantho075/locale",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Tiny framework-agnostic i18n core. Translation data lives in TS, no JSON files, no provider. Works in React, Next.js, Vue, Svelte, and Node.",
   "type": "module",
   "sideEffects": false,