@pyreon/i18n 0.0.1

package/src/context.ts

@@ -0,0 +1,57 @@
+import {
+  createContext,
+  pushContext,
+  popContext,
+  onUnmount,
+  useContext,
+} from '@pyreon/core'
+import type { VNodeChild, VNode, Props } from '@pyreon/core'
+import type { I18nInstance } from './types'
+
+export const I18nContext = createContext<I18nInstance | null>(null)
+
+export interface I18nProviderProps extends Props {
+  instance: I18nInstance
+  children?: VNodeChild
+}
+
+/**
+ * Provide an i18n instance to the component tree.
+ *
+ * @example
+ * const i18n = createI18n({ locale: 'en', messages: { en: { hello: 'Hello' } } })
+ *
+ * // In JSX:
+ * <I18nProvider instance={i18n}>
+ *   <App />
+ * </I18nProvider>
+ */
+export function I18nProvider(props: I18nProviderProps): VNode {
+  const frame = new Map([[I18nContext.id, props.instance]])
+  pushContext(frame)
+
+  onUnmount(() => popContext())
+
+  const ch = props.children
+  return (typeof ch === 'function' ? (ch as () => VNodeChild)() : ch) as VNode
+}
+
+/**
+ * Access the i18n instance from the nearest I18nProvider.
+ * Must be called within a component tree wrapped by I18nProvider.
+ *
+ * @example
+ * function Greeting() {
+ *   const { t, locale } = useI18n()
+ *   return <h1>{t('greeting', { name: 'World' })}</h1>
+ * }
+ */
+export function useI18n(): I18nInstance {
+  const instance = useContext(I18nContext)
+  if (!instance) {
+    throw new Error(
+      '[@pyreon/i18n] useI18n() must be used within an <I18nProvider>.',
+    )
+  }
+  return instance
+}

package/src/create-i18n.ts

@@ -0,0 +1,309 @@
+import { signal, computed } from '@pyreon/reactivity'
+import type {
+  I18nOptions,
+  I18nInstance,
+  TranslationDictionary,
+  InterpolationValues,
+} from './types'
+import { interpolate } from './interpolation'
+import { resolvePluralCategory } from './pluralization'
+
+/**
+ * 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('.')
+  let current: TranslationDictionary | string = dict
+
+  for (const part of parts) {
+    if (current == null || typeof current === 'string') return undefined
+    current = current[part] as TranslationDictionary | string
+  }
+
+  return typeof current === 'string' ? current : undefined
+}
+
+/**
+ * Deep-merge source into target (mutates target).
+ */
+function deepMerge(
+  target: TranslationDictionary,
+  source: TranslationDictionary,
+): void {
+  for (const key of Object.keys(source)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+      continue
+    const sourceVal = source[key]
+    const targetVal = target[key]
+    if (
+      typeof sourceVal === 'object' &&
+      sourceVal !== null &&
+      typeof targetVal === 'object' &&
+      targetVal !== null
+    ) {
+      deepMerge(
+        targetVal as TranslationDictionary,
+        sourceVal as TranslationDictionary,
+      )
+    } else {
+      target[key] = sourceVal!
+    }
+  }
+}
+
+/**
+ * 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
+ */
+export function createI18n(options: I18nOptions): I18nInstance {
+  const {
+    fallbackLocale,
+    loader,
+    defaultNamespace = 'common',
+    pluralRules,
+    onMissingKey,
+  } = options
+
+  // ── Reactive state ──────────────────────────────────────────────────
+
+  const locale = signal(options.locale)
+
+  // Internal store: locale → namespace → dictionary
+  // We use a version counter to trigger reactive updates when messages change,
+  // since the store is mutated in place (Object.is would skip same-reference sets).
+  const store = new Map<string, Map<string, TranslationDictionary>>()
+  const storeVersion = signal(0)
+
+  // Loading state
+  const pendingLoads = signal(0)
+  const loadedNsVersion = signal(0)
+
+  // In-flight load promises — deduplicates concurrent loads for the same locale:namespace
+  const pendingPromises = new Map<string, Promise<void>>()
+
+  const isLoading = computed(() => pendingLoads() > 0)
+  const loadedNamespaces = computed(() => {
+    loadedNsVersion()
+    const currentLocale = locale()
+    const nsMap = store.get(currentLocale)
+    return new Set(nsMap ? nsMap.keys() : [])
+  })
+  const availableLocales = computed(() => {
+    storeVersion() // subscribe to store changes
+    return [...store.keys()]
+  })
+
+  // ── Initialize static messages ──────────────────────────────────────
+
+  if (options.messages) {
+    for (const [loc, dict] of Object.entries(options.messages)) {
+      const nsMap = new Map<string, TranslationDictionary>()
+      nsMap.set(defaultNamespace, dict)
+      store.set(loc, nsMap)
+    }
+  }
+
+  // ── Internal helpers ────────────────────────────────────────────────
+
+  function getNamespaceMap(loc: string): Map<string, TranslationDictionary> {
+    let nsMap = store.get(loc)
+    if (!nsMap) {
+      nsMap = new Map()
+      store.set(loc, nsMap)
+    }
+    return nsMap
+  }
+
+  function lookupKey(
+    loc: string,
+    namespace: string,
+    keyPath: string,
+  ): string | undefined {
+    const nsMap = store.get(loc)
+    if (!nsMap) return undefined
+    const dict = nsMap.get(namespace)
+    if (!dict) return undefined
+    return resolveKey(dict, keyPath)
+  }
+
+  function resolveTranslation(
+    key: string,
+    values?: InterpolationValues,
+  ): string {
+    // Subscribe to reactive dependencies
+    const currentLocale = locale()
+    storeVersion()
+
+    // Parse key: "namespace:key.path" or just "key.path"
+    let namespace = defaultNamespace
+    let keyPath = key
+
+    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) {
+      const count = Number(values.count)
+      const category = resolvePluralCategory(currentLocale, count, pluralRules)
+
+      // Try exact form first (e.g. "items_one"), then fall back to base key
+      const pluralKey = `${keyPath}_${category}`
+      const pluralResult =
+        lookupKey(currentLocale, namespace, pluralKey) ??
+        (fallbackLocale
+          ? lookupKey(fallbackLocale, namespace, pluralKey)
+          : undefined)
+
+      if (pluralResult) {
+        return interpolate(pluralResult, values)
+      }
+    }
+
+    // Standard lookup: current locale → fallback locale
+    const result =
+      lookupKey(currentLocale, namespace, keyPath) ??
+      (fallbackLocale
+        ? lookupKey(fallbackLocale, namespace, keyPath)
+        : undefined)
+
+    if (result !== undefined) {
+      return interpolate(result, values)
+    }
+
+    // Missing key handler
+    if (onMissingKey) {
+      const custom = onMissingKey(currentLocale, key, namespace)
+      if (custom !== undefined) return custom!
+    }
+
+    // Return the key itself as a visual fallback
+    return key
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────
+
+  const t = (key: string, values?: InterpolationValues): string => {
+    return resolveTranslation(key, values)
+  }
+
+  const loadNamespace = async (
+    namespace: string,
+    loc?: string,
+  ): Promise<void> => {
+    if (!loader) return
+
+    const targetLocale = loc ?? locale.peek()
+    const cacheKey = `${targetLocale}:${namespace}`
+    const nsMap = getNamespaceMap(targetLocale)
+
+    // Skip if already loaded
+    if (nsMap.has(namespace)) return
+
+    // Deduplicate concurrent loads for the same locale:namespace
+    const existing = pendingPromises.get(cacheKey)
+    if (existing) return existing
+
+    pendingLoads.update((n) => n + 1)
+
+    const promise = loader(targetLocale, namespace)
+      .then((dict) => {
+        if (dict) {
+          nsMap.set(namespace, dict)
+          storeVersion.update((n) => n + 1)
+          loadedNsVersion.update((n) => n + 1)
+        }
+      })
+      .finally(() => {
+        pendingPromises.delete(cacheKey)
+        pendingLoads.update((n) => n - 1)
+      })
+
+    pendingPromises.set(cacheKey, promise)
+    return promise
+  }
+
+  const exists = (key: string): boolean => {
+    const currentLocale = locale.peek()
+
+    let namespace = defaultNamespace
+    let keyPath = key
+    const colonIndex = key.indexOf(':')
+    if (colonIndex > 0) {
+      namespace = key.slice(0, colonIndex)
+      keyPath = key.slice(colonIndex + 1)
+    }
+
+    return (
+      lookupKey(currentLocale, namespace, keyPath) !== undefined ||
+      (fallbackLocale
+        ? lookupKey(fallbackLocale, namespace, keyPath) !== undefined
+        : false)
+    )
+  }
+
+  const addMessages = (
+    loc: string,
+    messages: TranslationDictionary,
+    namespace?: string,
+  ): void => {
+    const ns = namespace ?? defaultNamespace
+    const nsMap = getNamespaceMap(loc)
+    const existing = nsMap.get(ns)
+
+    if (existing) {
+      deepMerge(existing, messages)
+    } else {
+      // Deep-clone to prevent external mutation from corrupting the store
+      const cloned: TranslationDictionary = {}
+      deepMerge(cloned, messages)
+      nsMap.set(ns, cloned)
+    }
+
+    storeVersion.update((n) => n + 1)
+    loadedNsVersion.update((n) => n + 1)
+  }
+
+  return {
+    t,
+    locale,
+    loadNamespace,
+    isLoading,
+    loadedNamespaces,
+    exists,
+    addMessages,
+    availableLocales,
+  }
+}

package/src/devtools.ts

@@ -0,0 +1,94 @@
+/**
+ * @pyreon/i18n devtools introspection API.
+ * Import: `import { ... } from "@pyreon/i18n/devtools"`
+ */
+
+const _activeInstances = new Map<string, WeakRef<object>>()
+const _listeners = new Set<() => void>()
+
+function _notify(): void {
+  for (const listener of _listeners) listener()
+}
+
+/**
+ * Register an i18n instance for devtools inspection.
+ *
+ * @example
+ * const i18n = createI18n({ ... })
+ * registerI18n("app", i18n)
+ */
+export function registerI18n(name: string, instance: object): void {
+  _activeInstances.set(name, new WeakRef(instance))
+  _notify()
+}
+
+/** Unregister an i18n instance. */
+export function unregisterI18n(name: string): void {
+  _activeInstances.delete(name)
+  _notify()
+}
+
+/** Get all registered i18n instance names. Cleans up garbage-collected instances. */
+export function getActiveI18nInstances(): string[] {
+  for (const [name, ref] of _activeInstances) {
+    if (ref.deref() === undefined) _activeInstances.delete(name)
+  }
+  return [..._activeInstances.keys()]
+}
+
+/** Get an i18n instance by name (or undefined if GC'd or not registered). */
+export function getI18nInstance(name: string): object | undefined {
+  const ref = _activeInstances.get(name)
+  if (!ref) return undefined
+  const instance = ref.deref()
+  if (!instance) {
+    _activeInstances.delete(name)
+    return undefined
+  }
+  return instance
+}
+
+/** Safely read a property that may be a signal (callable). */
+function safeRead(
+  obj: Record<string, unknown>,
+  key: string,
+  fallback: unknown = undefined,
+): unknown {
+  try {
+    const val = obj[key]
+    return typeof val === 'function' ? (val as () => unknown)() : fallback
+  } catch {
+    return fallback
+  }
+}
+
+/**
+ * Get a snapshot of an i18n instance's state.
+ */
+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())
+  return {
+    locale: safeRead(instance, 'locale'),
+    availableLocales: safeRead(instance, 'availableLocales', []),
+    loadedNamespaces: ns instanceof Set ? [...ns] : [],
+    isLoading: safeRead(instance, 'isLoading', false),
+  }
+}
+
+/** Subscribe to i18n registry changes. Returns unsubscribe function. */
+export function onI18nChange(listener: () => void): () => void {
+  _listeners.add(listener)
+  return () => {
+    _listeners.delete(listener)
+  }
+}
+
+/** @internal — reset devtools registry (for tests). */
+export function _resetDevtools(): void {
+  _activeInstances.clear()
+  _listeners.clear()
+}

package/src/index.ts

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

package/src/interpolation.ts

@@ -0,0 +1,28 @@
+import type { InterpolationValues } from './types'
+
+const INTERPOLATION_RE = /\{\{(\s*\w+\s*)\}\}/g
+
+/**
+ * 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.
+ */
+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}`
+    } catch {
+      return `{{${trimmed}}}`
+    }
+  })
+}

package/src/pluralization.ts

@@ -0,0 +1,31 @@
+import type { PluralRules } from './types'
+
+/**
+ * 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".
+ */
+export function resolvePluralCategory(
+  locale: string,
+  count: number,
+  customRules?: PluralRules,
+): string {
+  // Custom rules take priority
+  if (customRules?.[locale]) {
+    return customRules[locale](count)
+  }
+
+  // Use Intl.PluralRules if available
+  if (typeof Intl !== 'undefined' && Intl.PluralRules) {
+    try {
+      const pr = new Intl.PluralRules(locale)
+      return pr.select(count)
+    } catch {
+      // Invalid locale — fall through
+    }
+  }
+
+  // Basic fallback
+  return count === 1 ? 'one' : 'other'
+}

package/src/tests/devtools.test.ts

@@ -0,0 +1,166 @@
+import { createI18n } from '../create-i18n'
+import {
+  registerI18n,
+  unregisterI18n,
+  getActiveI18nInstances,
+  getI18nInstance,
+  getI18nSnapshot,
+  onI18nChange,
+  _resetDevtools,
+} from '../devtools'
+
+afterEach(() => _resetDevtools())
+
+describe('i18n devtools', () => {
+  test('getActiveI18nInstances returns empty initially', () => {
+    expect(getActiveI18nInstances()).toEqual([])
+  })
+
+  test('registerI18n makes instance visible', () => {
+    const i18n = createI18n({ locale: 'en', messages: { en: { hi: 'Hello' } } })
+    registerI18n('app', i18n)
+    expect(getActiveI18nInstances()).toEqual(['app'])
+  })
+
+  test('getI18nInstance returns the registered instance', () => {
+    const i18n = createI18n({ locale: 'en', messages: { en: { hi: 'Hello' } } })
+    registerI18n('app', i18n)
+    expect(getI18nInstance('app')).toBe(i18n)
+  })
+
+  test('getI18nInstance returns undefined for unregistered name', () => {
+    expect(getI18nInstance('nope')).toBeUndefined()
+  })
+
+  test('unregisterI18n removes the instance', () => {
+    const i18n = createI18n({ locale: 'en' })
+    registerI18n('app', i18n)
+    unregisterI18n('app')
+    expect(getActiveI18nInstances()).toEqual([])
+  })
+
+  test('getI18nSnapshot returns current state', () => {
+    const i18n = createI18n({
+      locale: 'en',
+      messages: { en: { hi: 'Hello' }, de: { hi: 'Hallo' } },
+    })
+    registerI18n('app', i18n)
+    const snapshot = getI18nSnapshot('app')
+    expect(snapshot).toBeDefined()
+    expect(snapshot!.locale).toBe('en')
+    expect(snapshot!.availableLocales).toEqual(
+      expect.arrayContaining(['en', 'de']),
+    )
+    expect(snapshot!.isLoading).toBe(false)
+  })
+
+  test('getI18nSnapshot handles instance with non-function properties', () => {
+    // Register a plain object where properties are NOT functions
+    // This covers the false branches of typeof checks in getI18nSnapshot
+    const plainInstance = {
+      locale: 'not-a-function',
+      availableLocales: 42,
+      loadedNamespaces: null,
+      isLoading: undefined,
+    }
+    registerI18n('plain', plainInstance)
+    const snapshot = getI18nSnapshot('plain')
+    expect(snapshot).toBeDefined()
+    expect(snapshot!.locale).toBeUndefined()
+    expect(snapshot!.availableLocales).toEqual([])
+    expect(snapshot!.loadedNamespaces).toEqual([])
+    expect(snapshot!.isLoading).toBe(false)
+  })
+
+  test('getI18nSnapshot reflects locale change', () => {
+    const i18n = createI18n({ locale: 'en', messages: { en: {}, de: {} } })
+    registerI18n('app', i18n)
+    i18n.locale.set('de')
+    const snapshot = getI18nSnapshot('app')
+    expect(snapshot!.locale).toBe('de')
+  })
+
+  test('getI18nSnapshot returns undefined for unregistered name', () => {
+    expect(getI18nSnapshot('nope')).toBeUndefined()
+  })
+
+  test('onI18nChange fires on register', () => {
+    const calls: number[] = []
+    const unsub = onI18nChange(() => calls.push(1))
+
+    registerI18n('app', createI18n({ locale: 'en' }))
+    expect(calls.length).toBe(1)
+
+    unsub()
+  })
+
+  test('onI18nChange fires on unregister', () => {
+    registerI18n('app', createI18n({ locale: 'en' }))
+
+    const calls: number[] = []
+    const unsub = onI18nChange(() => calls.push(1))
+    unregisterI18n('app')
+    expect(calls.length).toBe(1)
+
+    unsub()
+  })
+
+  test('onI18nChange unsubscribe stops notifications', () => {
+    const calls: number[] = []
+    const unsub = onI18nChange(() => calls.push(1))
+    unsub()
+
+    registerI18n('app', createI18n({ locale: 'en' }))
+    expect(calls.length).toBe(0)
+  })
+
+  test('multiple instances are tracked', () => {
+    registerI18n('app', createI18n({ locale: 'en' }))
+    registerI18n('admin', createI18n({ locale: 'en' }))
+    expect(getActiveI18nInstances().sort()).toEqual(['admin', 'app'])
+  })
+
+  test('getI18nInstance cleans up and returns undefined when WeakRef is dead', () => {
+    const instance = createI18n({ locale: 'en' })
+    const originalWeakRef = globalThis.WeakRef
+    let mockDerefResult: object | undefined = instance
+    const MockWeakRef = class {
+      deref() {
+        return mockDerefResult
+      }
+    }
+    globalThis.WeakRef = MockWeakRef as any
+
+    _resetDevtools()
+    registerI18n('mock-instance', instance)
+    expect(getI18nInstance('mock-instance')).toBe(instance)
+
+    // Simulate GC
+    mockDerefResult = undefined
+    expect(getI18nInstance('mock-instance')).toBeUndefined()
+
+    globalThis.WeakRef = originalWeakRef
+  })
+
+  test('getActiveI18nInstances cleans up garbage-collected WeakRefs', () => {
+    const instance = createI18n({ locale: 'en' })
+    const originalWeakRef = globalThis.WeakRef
+    let mockDerefResult: object | undefined = instance
+    const MockWeakRef = class {
+      deref() {
+        return mockDerefResult
+      }
+    }
+    globalThis.WeakRef = MockWeakRef as any
+
+    _resetDevtools()
+    registerI18n('gc-instance', instance)
+    expect(getActiveI18nInstances()).toEqual(['gc-instance'])
+
+    // Simulate GC
+    mockDerefResult = undefined
+    expect(getActiveI18nInstances()).toEqual([])
+
+    globalThis.WeakRef = originalWeakRef
+  })
+})