@pyreon/i18n 0.0.1

package/src/tests/setup.ts

@@ -0,0 +1 @@
+import '@happy-dom/global-registrator'

package/src/trans.ts

@@ -0,0 +1,111 @@
+import { h, Fragment } from '@pyreon/core'
+import type { VNode, Props } from '@pyreon/core'
+import type { InterpolationValues } from './types'
+
+const TAG_RE = /<(\w+)>(.*?)<\/\1>/gs
+
+interface RichPart {
+  tag: string
+  children: string
+}
+
+/**
+ * Parse a translated string into an array of plain text and rich tag segments.
+ *
+ * @example
+ * parseRichText("Hello <bold>world</bold>, click <link>here</link>")
+ * // → ["Hello ", { tag: "bold", children: "world" }, ", click ", { tag: "link", children: "here" }]
+ */
+export function parseRichText(text: string): (string | RichPart)[] {
+  const parts: (string | RichPart)[] = []
+  let lastIndex = 0
+
+  for (const match of text.matchAll(TAG_RE)) {
+    const before = text.slice(lastIndex, match.index)
+    if (before) parts.push(before)
+    parts.push({ tag: match[1]!, children: match[2]! })
+    lastIndex = match.index! + match[0].length
+  }
+
+  const after = text.slice(lastIndex)
+  if (after) parts.push(after)
+
+  return parts
+}
+
+export interface TransProps extends Props {
+  /** Translation key (supports namespace:key syntax). */
+  i18nKey: string
+  /** Interpolation values for {{placeholder}} syntax. */
+  values?: InterpolationValues
+  /**
+   * Component map for rich interpolation.
+   * Keys match tag names in the translation string.
+   * Values are component functions: `(children: any) => VNode`
+   *
+   * @example
+   * // Translation: "Read the <terms>terms</terms> and <privacy>policy</privacy>"
+   * components={{
+   *   terms: (children) => <a href="/terms">{children}</a>,
+   *   privacy: (children) => <a href="/privacy">{children}</a>,
+   * }}
+   */
+  components?: Record<string, (children: any) => any>
+  /**
+   * The i18n instance's `t` function.
+   * Can be obtained from `useI18n()` or passed directly.
+   */
+  t: (key: string, values?: InterpolationValues) => string
+}
+
+/**
+ * Rich JSX interpolation component for translations.
+ *
+ * Allows embedding JSX components within translated strings using XML-like tags.
+ * The `t` function resolves the translation and interpolates `{{values}}` first,
+ * then `<tag>content</tag>` patterns are mapped to the provided components.
+ *
+ * @example
+ * // Translation: "You have <bold>{{count}}</bold> unread messages"
+ * const { t } = useI18n()
+ * <Trans
+ *   t={t}
+ *   i18nKey="messages.unread"
+ *   values={{ count: 5 }}
+ *   components={{
+ *     bold: (children) => <strong>{children}</strong>,
+ *   }}
+ * />
+ * // Renders: You have <strong>5</strong> unread messages
+ *
+ * @example
+ * // Translation: "Read our <terms>terms of service</terms> and <privacy>privacy policy</privacy>"
+ * <Trans
+ *   t={t}
+ *   i18nKey="legal"
+ *   components={{
+ *     terms: (children) => <a href="/terms">{children}</a>,
+ *     privacy: (children) => <a href="/privacy">{children}</a>,
+ *   }}
+ * />
+ */
+export function Trans(props: TransProps): VNode | string {
+  const translated = props.t(props.i18nKey, props.values)
+
+  if (!props.components) return translated
+
+  const parts = parseRichText(translated)
+
+  // If the result is a single plain string, return it directly
+  if (parts.length === 1 && typeof parts[0] === 'string') return parts[0]
+
+  const children = parts.map((part) => {
+    if (typeof part === 'string') return part
+    const component = props.components![part.tag]
+    // Unmatched tags: render children as plain text (no raw HTML markup)
+    if (!component) return part.children
+    return component(part.children)
+  })
+
+  return h(Fragment, null, ...children)
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+import type { Signal, Computed } from '@pyreon/reactivity'
+
+/** A nested dictionary of translation strings. */
+export type TranslationDictionary = {
+  [key: string]: string | TranslationDictionary
+}
+
+/** Map of locale → dictionary (or namespace → dictionary). */
+export 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.
+ */
+export type NamespaceLoader = (
+  locale: string,
+  namespace: string,
+) => Promise<TranslationDictionary | undefined>
+
+/** Interpolation values for translation strings. */
+export type InterpolationValues = Record<string, string | number>
+
+/** Pluralization rules map — locale → function that picks the plural form. */
+export type PluralRules = Record<string, (count: number) => string>
+
+/** Options for creating an i18n instance. */
+export 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()`. */
+export 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[]>
+}