@pyreon/i18n 0.9.0 → 0.11.0

package/lib/types/core.d.ts

@@ -0,0 +1,142 @@
+import { Computed, Signal } from "@pyreon/reactivity";
+
+//#region src/types.d.ts
+/** A nested dictionary of translation strings. */
+type TranslationDictionary = {
+  [key: string]: string | TranslationDictionary;
+};
+/** Map of locale → dictionary (or namespace → dictionary). */
+type TranslationMessages = Record<string, TranslationDictionary>;
+/**
+ * Async function that loads translations for a locale and namespace.
+ * Return the dictionary for that namespace, or undefined if not found.
+ */
+type NamespaceLoader = (locale: string, namespace: string) => Promise<TranslationDictionary | undefined>;
+/** Interpolation values for translation strings. */
+type InterpolationValues = Record<string, string | number>;
+/** Pluralization rules map — locale → function that picks the plural form. */
+type PluralRules = Record<string, (count: number) => string>;
+/** Options for creating an i18n instance. */
+interface I18nOptions {
+  /** The initial locale (e.g. "en"). */
+  locale: string;
+  /** Fallback locale used when a key is missing in the active locale. */
+  fallbackLocale?: string;
+  /** Static messages keyed by locale. */
+  messages?: Record<string, TranslationDictionary>;
+  /**
+   * Async loader for namespace-based translation loading.
+   * Called with (locale, namespace) when `loadNamespace()` is invoked.
+   */
+  loader?: NamespaceLoader;
+  /**
+   * Default namespace used when `t()` is called without a namespace prefix.
+   * Defaults to "common".
+   */
+  defaultNamespace?: string;
+  /**
+   * Custom plural rules per locale.
+   * If not provided, uses `Intl.PluralRules` where available.
+   */
+  pluralRules?: PluralRules;
+  /**
+   * Missing key handler — called when a translation key is not found.
+   * Useful for logging, reporting, or returning a custom fallback.
+   */
+  onMissingKey?: (locale: string, key: string, namespace?: string) => string | undefined;
+}
+/** The public i18n instance returned by `createI18n()`. */
+interface I18nInstance {
+  /**
+   * Translate a key with optional interpolation.
+   * Reads the current locale reactively — re-evaluates in effects/computeds.
+   *
+   * Key format: "key" (uses default namespace) or "namespace:key".
+   * Nested keys use dots: "user.greeting" or "auth:errors.invalid".
+   *
+   * Interpolation: "Hello {{name}}" + { name: "Alice" } → "Hello Alice"
+   * Pluralization: key with "_one", "_other" etc. suffixes + { count: N }
+   */
+  t: (key: string, values?: InterpolationValues) => string;
+  /** Current locale (reactive signal). */
+  locale: Signal<string>;
+  /**
+   * Load a namespace's translations for the given locale (or current locale).
+   * Returns a promise that resolves when loading is complete.
+   */
+  loadNamespace: (namespace: string, locale?: string) => Promise<void>;
+  /**
+   * Whether any namespace is currently being loaded.
+   */
+  isLoading: Computed<boolean>;
+  /**
+   * Set of namespaces that have been loaded for the current locale.
+   */
+  loadedNamespaces: Computed<Set<string>>;
+  /**
+   * Check if a translation key exists in the current locale.
+   */
+  exists: (key: string) => boolean;
+  /**
+   * Add translations for a locale (merged with existing).
+   * Useful for adding translations at runtime without async loading.
+   */
+  addMessages: (locale: string, messages: TranslationDictionary, namespace?: string) => void;
+  /**
+   * Get all available locales (those with any registered messages).
+   */
+  availableLocales: Computed<string[]>;
+}
+//#endregion
+//#region src/create-i18n.d.ts
+/**
+ * Create a reactive i18n instance.
+ *
+ * @example
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   fallbackLocale: 'en',
+ *   messages: {
+ *     en: { greeting: 'Hello {{name}}!' },
+ *     de: { greeting: 'Hallo {{name}}!' },
+ *   },
+ * })
+ *
+ * // Reactive translation — re-evaluates on locale change
+ * i18n.t('greeting', { name: 'Alice' }) // "Hello Alice!"
+ * i18n.locale.set('de')
+ * i18n.t('greeting', { name: 'Alice' }) // "Hallo Alice!"
+ *
+ * @example
+ * // Async namespace loading
+ * const i18n = createI18n({
+ *   locale: 'en',
+ *   loader: async (locale, namespace) => {
+ *     const mod = await import(`./locales/${locale}/${namespace}.json`)
+ *     return mod.default
+ *   },
+ * })
+ * await i18n.loadNamespace('auth')
+ * i18n.t('auth:errors.invalid') // looks up "errors.invalid" in "auth" namespace
+ */
+declare function createI18n(options: I18nOptions): I18nInstance;
+//#endregion
+//#region src/interpolation.d.ts
+/**
+ * Replace `{{key}}` placeholders in a string with values from the given record.
+ * Supports optional whitespace inside braces: `{{ name }}` works too.
+ * Unmatched placeholders are left as-is.
+ */
+declare function interpolate(template: string, values?: InterpolationValues): string;
+//#endregion
+//#region src/pluralization.d.ts
+/**
+ * Resolve the plural category for a given count and locale.
+ *
+ * Uses custom rules if provided, otherwise falls back to `Intl.PluralRules`.
+ * Returns CLDR plural categories: "zero", "one", "two", "few", "many", "other".
+ */
+declare function resolvePluralCategory(locale: string, count: number, customRules?: PluralRules): string;
+//#endregion
+export { type I18nInstance, type I18nOptions, type InterpolationValues, type NamespaceLoader, type PluralRules, type TranslationDictionary, type TranslationMessages, createI18n, interpolate, resolvePluralCategory };
+//# sourceMappingURL=core2.d.ts.map

package/lib/types/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/create-i18n.ts","../../../src/interpolation.ts","../../../src/pluralization.ts"],"mappings":";;;;KAGY,qBAAA;EAAA,CACT,GAAA,oBAAuB,qBAAA;AAAA;;KAId,mBAAA,GAAsB,MAAA,SAAe,qBAAA;;AAAjD;;;KAMY,eAAA,IACV,MAAA,UACA,SAAA,aACG,OAAA,CAAQ,qBAAA;;KAGD,mBAAA,GAAsB,MAAA;;KAGtB,WAAA,GAAc,MAAA,UAAgB,KAAA;;UAGzB,WAAA;EAVf;EAYA,MAAA;EAXW;EAaX,cAAA;EAbgC;EAehC,QAAA,GAAW,MAAA,SAAe,qBAAA;EAZG;;;;EAiB7B,MAAA,GAAS,eAAA;EAdY;;;;EAmBrB,gBAAA;EAhB0B;;;;EAqB1B,WAAA,GAAc,WAAA;EAAA;;;;EAKd,YAAA,IAAgB,MAAA,UAAgB,GAAA,UAAa,SAAA;AAAA;;UAI9B,YAAA;EAnBf;;;;;;;;;;EA8BA,CAAA,GAAI,GAAA,UAAa,MAAA,GAAS,mBAAA;EAXX;EAcf,MAAA,EAAQ,MAAA;;;;;EAMR,aAAA,GAAgB,SAAA,UAAmB,MAAA,cAAoB,OAAA;EAU5B;;;EAL3B,SAAA,EAAW,QAAA;EAqBe;;;EAhB1B,gBAAA,EAAkB,QAAA,CAAS,GAAA;EAnBD;;;EAwB1B,MAAA,GAAS,GAAA;EAfT;;;;EAqBA,WAAA,GAAc,MAAA,UAAgB,QAAA,EAAU,qBAAA,EAAuB,SAAA;EAhBpD;;;EAqBX,gBAAA,EAAkB,QAAA;AAAA;;;;;AAnGpB;;;;;AAKA;;;;;AAMA;;;;;;;;;;AAMA;;;;;AAGA;;;iBCiFgB,UAAA,CAAW,OAAA,EAAS,WAAA,GAAc,YAAA;;;;;ADrGlD;;;iBEMgB,WAAA,CAAY,QAAA,UAAkB,MAAA,GAAS,mBAAA;;;;;AFNvD;;;;iBGKgB,qBAAA,CACd,MAAA,UACA,KAAA,UACA,WAAA,GAAc,WAAA"}

package/lib/types/devtools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"devtools2.d.ts","names":[],"sources":["../../../src/devtools.ts"],"mappings":";;AAmBA;;;;;AAMA;;;;;iBANgB,YAAA,CAAa,IAAA,UAAc,QAAA;;iBAM3B,cAAA,CAAe,IAAA;;iBAMf,sBAAA,CAAA;AAQhB;AAAA,iBAAgB,eAAA,CAAgB,IAAA;;;;iBA4BhB,eAAA,CACd,IAAA,WACC,MAAA;;iBAaa,YAAA,CAAa,QAAA;;iBAQb,cAAA,CAAA"}
+{"version":3,"file":"devtools2.d.ts","names":[],"sources":["../../../src/devtools.ts"],"mappings":";;AAmBA;;;;;AAMA;;;;;iBANgB,YAAA,CAAa,IAAA,UAAc,QAAA;;iBAM3B,cAAA,CAAe,IAAA;;iBAMf,sBAAA,CAAA;AAQhB;AAAA,iBAAgB,eAAA,CAAgB,IAAA;;;;iBA4BhB,eAAA,CAAgB,IAAA,WAAe,MAAA;;iBAa/B,YAAA,CAAa,QAAA;;iBAQb,cAAA,CAAA"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/context.ts","../../../src/create-i18n.ts","../../../src/interpolation.ts","../../../src/pluralization.ts","../../../src/trans.tsx"],"mappings":";;;;;;KAGY,qBAAA;EAAA,CACT,GAAA,oBAAuB,qBAAA;AAAA;AAD1B;AAAA,KAKY,mBAAA,GAAsB,MAAA,SAAe,qBAAA;;;;AAAjD;KAMY,eAAA,IACV,MAAA,UACA,SAAA,aACG,OAAA,CAAQ,qBAAA;;KAGD,mBAAA,GAAsB,MAAA;;KAGtB,WAAA,GAAc,MAAA,UAAgB,KAAA;;UAGzB,WAAA;EATL;EAWV,MAAA;EAZA;EAcA,cAAA;EAbW;EAeX,QAAA,GAAW,MAAA,SAAe,qBAAA;EAfM;AAGlC;;;EAiBE,MAAA,GAAS,eAAA;EAjB6B;AAGxC;;;EAmBE,gBAAA;EAnBqD;AAGvD;;;EAqBE,WAAA,GAAc,WAAA;EAfH;;;;EAoBX,YAAA,IACE,MAAA,UACA,GAAA,UACA,SAAA;AAAA;;UAKa,YAAA;EA5BJ;;;;;;;;;;EAuCX,CAAA,GAAI,GAAA,UAAa,MAAA,GAAS,mBAAA;EAhBN;EAmBpB,MAAA,EAAQ,MAAA;EAdO;;;;EAoBf,aAAA,GAAgB,SAAA,UAAmB,MAAA,cAAoB,OAAA;EAAA;;;EAKvD,SAAA,EAAW,QAAA;EAkBC;;;EAbZ,gBAAA,EAAkB,QAAA,CAAS,GAAA;EAnB3B;;;EAwBA,MAAA,GAAS,GAAA;EArBT;;;;EA2BA,WAAA,GACE,MAAA,UACA,QAAA,EAAU,qBAAA,EACV,SAAA;EAxBqD;;;EA8BvD,gBAAA,EAAkB,QAAA;AAAA;;;cC1GP,WAAA,EAAW,aAAA,CAAA,OAAA,CAAA,YAAA;AAAA,UAEP,iBAAA,SAA0B,KAAA;EACzC,QAAA,EAAU,YAAA;EACV,QAAA,GAAW,UAAA;AAAA;;;;ADAb;;;;;AAMA;;;iBCQgB,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA;;;;;;;ADFxD;;;;iBCmBgB,OAAA,CAAA,GAAW,YAAA;;;;;;;ADpC3B;;;;;AAKA;;;;;AAMA;;;;;;;;;;AAMA;;;;;AAGA;iBEgEgB,UAAA,CAAW,OAAA,EAAS,WAAA,GAAc,YAAA;;;;;;;AFpFlD;iBGMgB,WAAA,CACd,QAAA,UACA,MAAA,GAAS,mBAAA;;;;;;;AHRX;;iBIKgB,qBAAA,CACd,MAAA,UACA,KAAA,UACA,WAAA,GAAc,WAAA;;;UCNN,QAAA;EACR,GAAA;EACA,QAAA;AAAA;;;;;ALCF;;;iBKSgB,aAAA,CAAc,IAAA,qBAAyB,QAAA;AAAA,UAiBtC,UAAA,SAAmB,KAAA;ELpBxB;EKsBV,OAAA;;EAEA,MAAA,GAAS,mBAAA;ELvBT;;;;;;AAKF;;;;;AAGA;EK4BE,UAAA,GAAa,MAAA,UAAgB,QAAA;;;;ALzB/B;EK8BE,CAAA,GAAI,GAAA,UAAa,MAAA,GAAS,mBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;ALI5B;;;;;;;;;iBK8BgB,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,KAAA"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/context.ts","../../../src/create-i18n.ts","../../../src/interpolation.ts","../../../src/pluralization.ts","../../../src/trans.tsx"],"mappings":";;;;;;KAGY,qBAAA;EAAA,CACT,GAAA,oBAAuB,qBAAA;AAAA;AAD1B;AAAA,KAKY,mBAAA,GAAsB,MAAA,SAAe,qBAAA;;;;AAAjD;KAMY,eAAA,IACV,MAAA,UACA,SAAA,aACG,OAAA,CAAQ,qBAAA;;KAGD,mBAAA,GAAsB,MAAA;;KAGtB,WAAA,GAAc,MAAA,UAAgB,KAAA;;UAGzB,WAAA;EATL;EAWV,MAAA;EAZA;EAcA,cAAA;EAbW;EAeX,QAAA,GAAW,MAAA,SAAe,qBAAA;EAfM;AAGlC;;;EAiBE,MAAA,GAAS,eAAA;EAjB6B;AAGxC;;;EAmBE,gBAAA;EAnBqD;AAGvD;;;EAqBE,WAAA,GAAc,WAAA;EAfH;;;;EAoBX,YAAA,IAAgB,MAAA,UAAgB,GAAA,UAAa,SAAA;AAAA;;UAI9B,YAAA;EAxBJ;;;;;;;;;;EAmCX,CAAA,GAAI,GAAA,UAAa,MAAA,GAAS,mBAAA;EAfqC;EAkB/D,MAAA,EAAQ,MAAA;EAdO;;;;EAoBf,aAAA,GAAgB,SAAA,UAAmB,MAAA,cAAoB,OAAA;EAAA;;;EAKvD,SAAA,EAAW,QAAA;EAgB6B;;;EAXxC,gBAAA,EAAkB,QAAA,CAAS,GAAA;EAnB3B;;;EAwBA,MAAA,GAAS,GAAA;EArBT;;;;EA2BA,WAAA,GAAc,MAAA,UAAgB,QAAA,EAAU,qBAAA,EAAuB,SAAA;EArBR;;;EA0BvD,gBAAA,EAAkB,QAAA;AAAA;;;cClGP,WAAA,EAAW,aAAA,CAAA,OAAA,CAAA,YAAA;AAAA,UAEP,iBAAA,SAA0B,KAAA;EACzC,QAAA,EAAU,YAAA;EACV,QAAA,GAAW,UAAA;AAAA;;;;ADAb;;;;;AAMA;;;iBCQgB,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA;;;;;;;ADFxD;;;;iBCmBgB,OAAA,CAAA,GAAW,YAAA;;;;;;;ADpC3B;;;;;AAKA;;;;;AAMA;;;;;;;;;;AAMA;;;;;AAGA;iBEiFgB,UAAA,CAAW,OAAA,EAAS,WAAA,GAAc,YAAA;;;;;;;AFrGlD;iBGMgB,WAAA,CAAY,QAAA,UAAkB,MAAA,GAAS,mBAAA;;;;;;;AHNvD;;iBIKgB,qBAAA,CACd,MAAA,UACA,KAAA,UACA,WAAA,GAAc,WAAA;;;UCNN,QAAA;EACR,GAAA;EACA,QAAA;AAAA;;;;;ALCF;;;iBKSgB,aAAA,CAAc,IAAA,qBAAyB,QAAA;AAAA,UAiBtC,UAAA,SAAmB,KAAA;ELpBxB;EKsBV,OAAA;;EAEA,MAAA,GAAS,mBAAA;ELvBT;;;;;;AAKF;;;;;AAGA;EK4BE,UAAA,GAAa,MAAA,UAAgB,QAAA;;;;ALzB/B;EK8BE,CAAA,GAAI,GAAA,UAAa,MAAA,GAAS,mBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;ALA5B;;;;;;;;;iBKkCgB,KAAA,CAAM,KAAA,EAAO,UAAA,GAAa,KAAA"}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@pyreon/i18n",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Reactive internationalization for Pyreon with async namespace loading",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pyreon/fundamentals.git",
-    "directory": "packages/i18n"
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/fundamentals/i18n"
   },
   "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/i18n#readme",
   "bugs": {
-    "url": "https://github.com/pyreon/fundamentals/issues"
+    "url": "https://github.com/pyreon/pyreon/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -32,6 +32,11 @@
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
     },
+    "./core": {
+      "bun": "./src/core.ts",
+      "import": "./lib/core.js",
+      "types": "./lib/types/core.d.ts"
+    },
     "./devtools": {
       "bun": "./src/devtools.ts",
       "import": "./lib/devtools.js",
@@ -42,10 +47,17 @@
     "build": "vl_rolldown_build",
     "dev": "vl_rolldown_build-watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ."
   },
   "peerDependencies": {
-    "@pyreon/core": ">=0.7.0 <0.8.0",
-    "@pyreon/reactivity": ">=0.7.0 <0.8.0"
+    "@pyreon/core": "^0.11.0",
+    "@pyreon/reactivity": "^0.11.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/core": "^0.11.0",
+    "@pyreon/reactivity": "^0.11.0",
+    "@pyreon/runtime-dom": "^0.11.0"
   }
 }

package/src/context.ts

@@ -1,6 +1,6 @@
-import type { Props, VNode, VNodeChild } from '@pyreon/core'
-import { createContext, provide, useContext } from '@pyreon/core'
-import type { I18nInstance } from './types'
+import type { Props, VNode, VNodeChild } from "@pyreon/core"
+import { createContext, provide, useContext } from "@pyreon/core"
+import type { I18nInstance } from "./types"
 
 export const I18nContext = createContext<I18nInstance | null>(null)
 
@@ -24,7 +24,7 @@ export function I18nProvider(props: I18nProviderProps): VNode {
   provide(I18nContext, props.instance)
 
   const ch = props.children
-  return (typeof ch === 'function' ? (ch as () => VNodeChild)() : ch) as VNode
+  return (typeof ch === "function" ? (ch as () => VNodeChild)() : ch) as VNode
 }
 
 /**
@@ -40,9 +40,7 @@ export function I18nProvider(props: I18nProviderProps): VNode {
 export function useI18n(): I18nInstance {
   const instance = useContext(I18nContext)
   if (!instance) {
-    throw new Error(
-      '[@pyreon/i18n] useI18n() must be used within an <I18nProvider>.',
-    )
+    throw new Error("[@pyreon/i18n] useI18n() must be used within an <I18nProvider>.")
   }
   return instance
 }

package/src/core.ts

@@ -0,0 +1,22 @@
+/**
+ * Framework-agnostic i18n core — no @pyreon/core dependency.
+ * Use this entry point for backend/server usage where you only need
+ * createI18n() and translation utilities.
+ *
+ * @example
+ * ```ts
+ * import { createI18n, interpolate } from "@pyreon/i18n/core"
+ * ```
+ */
+export { createI18n } from "./create-i18n"
+export { interpolate } from "./interpolation"
+export { resolvePluralCategory } from "./pluralization"
+export type {
+  I18nInstance,
+  I18nOptions,
+  InterpolationValues,
+  NamespaceLoader,
+  PluralRules,
+  TranslationDictionary,
+  TranslationMessages,
+} from "./types"

package/src/create-i18n.ts

@@ -1,54 +1,71 @@
-import { computed, signal } from '@pyreon/reactivity'
-import { interpolate } from './interpolation'
-import { resolvePluralCategory } from './pluralization'
-import type {
-  I18nInstance,
-  I18nOptions,
-  InterpolationValues,
-  TranslationDictionary,
-} from './types'
+import { computed, signal } from "@pyreon/reactivity"
+import { interpolate } from "./interpolation"
+import { resolvePluralCategory } from "./pluralization"
+import type { I18nInstance, I18nOptions, InterpolationValues, TranslationDictionary } from "./types"
 
 /**
  * Resolve a dot-separated key path in a nested dictionary.
  * E.g. "user.greeting" → dictionary.user.greeting
  */
-function resolveKey(
-  dict: TranslationDictionary,
-  keyPath: string,
-): string | undefined {
-  const parts = keyPath.split('.')
+function resolveKey(dict: TranslationDictionary, keyPath: string): string | undefined {
+  const parts = keyPath.split(".")
   let current: TranslationDictionary | string = dict
 
   for (const part of parts) {
-    if (current == null || typeof current === 'string') return undefined
+    if (current == null || typeof current === "string") return undefined
     current = current[part] as TranslationDictionary | string
   }
 
-  return typeof current === 'string' ? current : undefined
+  return typeof current === "string" ? current : undefined
+}
+
+/**
+ * Convert flat dotted keys into nested objects.
+ * `{ 'section.title': 'Report' }` → `{ section: { title: 'Report' } }`
+ * Keys that don't contain dots are passed through as-is.
+ * Already-nested objects are preserved — only string values with dotted keys are expanded.
+ */
+function nestFlatKeys(messages: TranslationDictionary): TranslationDictionary {
+  const result: TranslationDictionary = {}
+  let hasFlatKeys = false
+
+  for (const key of Object.keys(messages)) {
+    const value = messages[key]
+    if (key.includes(".") && typeof value === "string") {
+      hasFlatKeys = true
+      const parts = key.split(".")
+      let current: TranslationDictionary = result
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i] as string
+        if (!(part in current) || typeof current[part] !== "object") {
+          current[part] = {}
+        }
+        current = current[part] as TranslationDictionary
+      }
+      current[parts[parts.length - 1] as string] = value
+    } else if (value !== undefined) {
+      result[key] = value
+    }
+  }
+
+  return hasFlatKeys ? result : messages
 }
 
 /**
  * Deep-merge source into target (mutates target).
  */
-function deepMerge(
-  target: TranslationDictionary,
-  source: TranslationDictionary,
-): void {
+function deepMerge(target: TranslationDictionary, source: TranslationDictionary): void {
   for (const key of Object.keys(source)) {
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype')
-      continue
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue
     const sourceVal = source[key]
     const targetVal = target[key]
     if (
-      typeof sourceVal === 'object' &&
+      typeof sourceVal === "object" &&
       sourceVal !== null &&
-      typeof targetVal === 'object' &&
+      typeof targetVal === "object" &&
       targetVal !== null
     ) {
-      deepMerge(
-        targetVal as TranslationDictionary,
-        sourceVal as TranslationDictionary,
-      )
+      deepMerge(targetVal as TranslationDictionary, sourceVal as TranslationDictionary)
     } else {
       target[key] = sourceVal!
     }
@@ -86,13 +103,7 @@ function deepMerge(
  * i18n.t('auth:errors.invalid') // looks up "errors.invalid" in "auth" namespace
  */
 export function createI18n(options: I18nOptions): I18nInstance {
-  const {
-    fallbackLocale,
-    loader,
-    defaultNamespace = 'common',
-    pluralRules,
-    onMissingKey,
-  } = options
+  const { fallbackLocale, loader, defaultNamespace = "common", pluralRules, onMissingKey } = options
 
   // ── Reactive state ──────────────────────────────────────────────────
 
@@ -144,11 +155,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
     return nsMap
   }
 
-  function lookupKey(
-    loc: string,
-    namespace: string,
-    keyPath: string,
-  ): string | undefined {
+  function lookupKey(loc: string, namespace: string, keyPath: string): string | undefined {
     const nsMap = store.get(loc)
     if (!nsMap) return undefined
     const dict = nsMap.get(namespace)
@@ -156,10 +163,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
     return resolveKey(dict, keyPath)
   }
 
-  function resolveTranslation(
-    key: string,
-    values?: InterpolationValues,
-  ): string {
+  function resolveTranslation(key: string, values?: InterpolationValues): string {
     // Subscribe to reactive dependencies
     const currentLocale = locale()
     storeVersion()
@@ -168,14 +172,14 @@ export function createI18n(options: I18nOptions): I18nInstance {
     let namespace = defaultNamespace
     let keyPath = key
 
-    const colonIndex = key.indexOf(':')
+    const colonIndex = key.indexOf(":")
     if (colonIndex > 0) {
       namespace = key.slice(0, colonIndex)
       keyPath = key.slice(colonIndex + 1)
     }
 
     // Handle pluralization: if values contain `count`, try plural suffixes
-    if (values && 'count' in values) {
+    if (values && "count" in values) {
       const count = Number(values.count)
       const category = resolvePluralCategory(currentLocale, count, pluralRules)
 
@@ -183,9 +187,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
       const pluralKey = `${keyPath}_${category}`
       const pluralResult =
         lookupKey(currentLocale, namespace, pluralKey) ??
-        (fallbackLocale
-          ? lookupKey(fallbackLocale, namespace, pluralKey)
-          : undefined)
+        (fallbackLocale ? lookupKey(fallbackLocale, namespace, pluralKey) : undefined)
 
       if (pluralResult) {
         return interpolate(pluralResult, values)
@@ -195,9 +197,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
     // Standard lookup: current locale → fallback locale
     const result =
       lookupKey(currentLocale, namespace, keyPath) ??
-      (fallbackLocale
-        ? lookupKey(fallbackLocale, namespace, keyPath)
-        : undefined)
+      (fallbackLocale ? lookupKey(fallbackLocale, namespace, keyPath) : undefined)
 
     if (result !== undefined) {
       return interpolate(result, values)
@@ -219,10 +219,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
     return resolveTranslation(key, values)
   }
 
-  const loadNamespace = async (
-    namespace: string,
-    loc?: string,
-  ): Promise<void> => {
+  const loadNamespace = async (namespace: string, loc?: string): Promise<void> => {
     if (!loader) return
 
     const targetLocale = loc ?? locale.peek()
@@ -260,7 +257,7 @@ export function createI18n(options: I18nOptions): I18nInstance {
 
     let namespace = defaultNamespace
     let keyPath = key
-    const colonIndex = key.indexOf(':')
+    const colonIndex = key.indexOf(":")
     if (colonIndex > 0) {
       namespace = key.slice(0, colonIndex)
       keyPath = key.slice(colonIndex + 1)
@@ -268,27 +265,22 @@ export function createI18n(options: I18nOptions): I18nInstance {
 
     return (
       lookupKey(currentLocale, namespace, keyPath) !== undefined ||
-      (fallbackLocale
-        ? lookupKey(fallbackLocale, namespace, keyPath) !== undefined
-        : false)
+      (fallbackLocale ? lookupKey(fallbackLocale, namespace, keyPath) !== undefined : false)
     )
   }
 
-  const addMessages = (
-    loc: string,
-    messages: TranslationDictionary,
-    namespace?: string,
-  ): void => {
+  const addMessages = (loc: string, messages: TranslationDictionary, namespace?: string): void => {
     const ns = namespace ?? defaultNamespace
     const nsMap = getNamespaceMap(loc)
+    const nested = nestFlatKeys(messages)
     const existing = nsMap.get(ns)
 
     if (existing) {
-      deepMerge(existing, messages)
+      deepMerge(existing, nested)
     } else {
       // Deep-clone to prevent external mutation from corrupting the store
       const cloned: TranslationDictionary = {}
-      deepMerge(cloned, messages)
+      deepMerge(cloned, nested)
       nsMap.set(ns, cloned)
     }
 

package/src/devtools.ts

@@ -56,7 +56,7 @@ function safeRead(
 ): unknown {
   try {
     const val = obj[key]
-    return typeof val === 'function' ? (val as () => unknown)() : fallback
+    return typeof val === "function" ? (val as () => unknown)() : fallback
   } catch {
     return fallback
   }
@@ -65,17 +65,15 @@ function safeRead(
 /**
  * Get a snapshot of an i18n instance's state.
  */
-export function getI18nSnapshot(
-  name: string,
-): Record<string, unknown> | undefined {
+export function getI18nSnapshot(name: string): Record<string, unknown> | undefined {
   const instance = getI18nInstance(name) as Record<string, unknown> | undefined
   if (!instance) return undefined
-  const ns = safeRead(instance, 'loadedNamespaces', new Set())
+  const ns = safeRead(instance, "loadedNamespaces", new Set())
   return {
-    locale: safeRead(instance, 'locale'),
-    availableLocales: safeRead(instance, 'availableLocales', []),
+    locale: safeRead(instance, "locale"),
+    availableLocales: safeRead(instance, "availableLocales", []),
     loadedNamespaces: ns instanceof Set ? [...ns] : [],
-    isLoading: safeRead(instance, 'isLoading', false),
+    isLoading: safeRead(instance, "isLoading", false),
   }
 }
 

package/src/index.ts

@@ -1,10 +1,10 @@
-export type { I18nProviderProps } from './context'
-export { I18nContext, I18nProvider, useI18n } from './context'
-export { createI18n } from './create-i18n'
-export { interpolate } from './interpolation'
-export { resolvePluralCategory } from './pluralization'
-export type { TransProps } from './trans'
-export { parseRichText, Trans } from './trans'
+export type { I18nProviderProps } from "./context"
+export { I18nContext, I18nProvider, useI18n } from "./context"
+export { createI18n } from "./create-i18n"
+export { interpolate } from "./interpolation"
+export { resolvePluralCategory } from "./pluralization"
+export type { TransProps } from "./trans"
+export { parseRichText, Trans } from "./trans"
 export type {
   I18nInstance,
   I18nOptions,
@@ -13,4 +13,4 @@ export type {
   PluralRules,
   TranslationDictionary,
   TranslationMessages,
-} from './types'
+} from "./types"

package/src/interpolation.ts

@@ -1,4 +1,4 @@
-import type { InterpolationValues } from './types'
+import type { InterpolationValues } from "./types"
 
 const INTERPOLATION_RE = /\{\{(\s*\w+\s*)\}\}/g
 
@@ -7,20 +7,15 @@ const INTERPOLATION_RE = /\{\{(\s*\w+\s*)\}\}/g
  * Supports optional whitespace inside braces: `{{ name }}` works too.
  * Unmatched placeholders are left as-is.
  */
-export function interpolate(
-  template: string,
-  values?: InterpolationValues,
-): string {
-  if (!values || !template.includes('{{')) return template
+export function interpolate(template: string, values?: InterpolationValues): string {
+  if (!values || !template.includes("{{")) return template
   return template.replace(INTERPOLATION_RE, (_, key: string) => {
     const trimmed = key.trim()
     const value = values[trimmed]
     if (value === undefined) return `{{${trimmed}}}`
     // Safely coerce — guard against malicious toString/valueOf
     try {
-      return typeof value === 'object' && value !== null
-        ? JSON.stringify(value)
-        : `${value}`
+      return typeof value === "object" && value !== null ? JSON.stringify(value) : `${value}`
     } catch {
       return `{{${trimmed}}}`
     }

package/src/pluralization.ts

@@ -1,4 +1,4 @@
-import type { PluralRules } from './types'
+import type { PluralRules } from "./types"
 
 /**
  * Resolve the plural category for a given count and locale.
@@ -17,7 +17,7 @@ export function resolvePluralCategory(
   }
 
   // Use Intl.PluralRules if available
-  if (typeof Intl !== 'undefined' && Intl.PluralRules) {
+  if (typeof Intl !== "undefined" && Intl.PluralRules) {
     try {
       const pr = new Intl.PluralRules(locale)
       return pr.select(count)
@@ -27,5 +27,5 @@ export function resolvePluralCategory(
   }
 
   // Basic fallback
-  return count === 1 ? 'one' : 'other'
+  return count === 1 ? "one" : "other"
 }