@nexpress/core 0.1.0

package/dist/i18n.d.ts

@@ -0,0 +1,301 @@
+import { G as NpI18nConfig } from './types-TlsbXS0T.js';
+
+declare function setI18nConfig(config: NpI18nConfig | null): void;
+declare function getI18nConfig(): NpI18nConfig | null;
+declare function resetI18nConfig(): void;
+
+interface NpResolveLocaleInput {
+    /**
+     * Request pathname (e.g. `/en/blog/post-1` or `/blog/post-1`).
+     * The first segment is checked against the configured locale
+     * list — if it matches, that locale wins. This is the
+     * primary signal: themes / page authors building under
+     * `app/(site)/*` always have a pathname.
+     */
+    pathname?: string;
+    /**
+     * `Accept-Language` header value. Used as a fallback when the
+     * pathname doesn't carry a locale prefix. The first
+     * comma-separated tag whose primary subtag matches a configured
+     * locale wins. Quality factors are honored.
+     */
+    acceptLanguage?: string;
+}
+interface NpResolveLocaleResult {
+    /**
+     * The resolved locale code (e.g. `"en"`, `"ko"`). Always one
+     * of the configured locales; never an arbitrary user-supplied
+     * string.
+     */
+    locale: string;
+    /**
+     * Where the locale came from. Useful when the page wants to
+     * decide whether to issue a 301 (redirect bare `/blog` to
+     * `/{defaultLocale}/blog` for SEO) or render in place.
+     */
+    source: "path" | "header" | "default";
+    /**
+     * The pathname with the locale prefix stripped, when the
+     * locale came from the path. Same as the input pathname
+     * otherwise. Useful for downstream slug lookups that store
+     * paths without the locale segment.
+     */
+    pathnameWithoutLocale: string | undefined;
+}
+/**
+ * Resolve the current request's locale using the same conventions
+ * the reference app's `[[...slug]]` route uses, so theme / page
+ * authors don't have to reimplement the logic.
+ *
+ *  1. Pathname prefix (`/en/...`) — wins if present and matches
+ *     a configured locale.
+ *  2. `Accept-Language` header — first tag whose primary subtag
+ *     (or full tag) matches a configured locale.
+ *  3. The site's default locale.
+ *
+ * Returns `null` only when i18n hasn't been configured for the
+ * site (no `nexpressConfig.i18n` set). Page authors should treat
+ * that as "monolingual site" and ignore locale entirely.
+ */
+declare function resolveLocale(input?: NpResolveLocaleInput): NpResolveLocaleResult | null;
+/**
+ * Convenience wrapper that returns just the locale string.
+ * Returns the default locale when i18n isn't configured (instead
+ * of null) so call sites can blindly chain `.toLowerCase()` etc.
+ * without a null check. Use `resolveLocale` directly when you
+ * need the source / stripped path.
+ */
+declare function getCurrentLocale(input?: NpResolveLocaleInput): string;
+
+/**
+ * Phase 12.5 — UI string translation registry.
+ *
+ * Plugins and themes ship key → string bundles per locale; the
+ * framework merges them at boot and exposes a `t()` helper that
+ * the runtime calls with `(key, locale?, params?)`. Lookup
+ * order: requested locale → default locale → key itself
+ * (so missing translations don't crash; they surface the key
+ * to the operator who can fill it in).
+ *
+ * Distinct from Phase 12.1 collection content i18n: that's
+ * about USER-AUTHORED content (page bodies, blog posts);
+ * THIS is about FRAMEWORK + PLUGIN + THEME chrome ("Read
+ * more", "min read", "Submit", error messages, dashboard
+ * widget labels, etc.).
+ *
+ * No DB persistence in 12.5 — bundles are loaded from
+ * plugins / themes / app at boot. Admin-overridable bundles
+ * are a follow-up; the registry already supports
+ * `addStrings(locale, bundle)` so an admin-side override
+ * loader can layer on top without changing this surface.
+ *
+ * Phase 12.7 — message format upgraded from a private
+ * `{{name}}` regex to ICU MessageFormat via
+ * `intl-messageformat`. Plain strings still work unchanged
+ * ("Read more"); `{name}` interpolation replaces the old
+ * `{{name}}`; plural / select / date / number formatting
+ * follow ICU syntax. Compiled message instances are cached
+ * keyed by `(locale, template)` so a hot path doesn't re-parse
+ * every call.
+ */
+/** A flat key → translated string map for a single locale. */
+type NpTranslationBundle = Record<string, string>;
+/**
+ * Merge a translation bundle into the registry for the given
+ * locale. Keys not in the existing bundle are added; keys
+ * already present are overwritten by the new value (last
+ * writer wins). Plugins / themes call this from their
+ * registration code via the `i18n` manifest field; sites
+ * call it directly for app-level overrides.
+ */
+declare function addStrings(locale: string, bundle: NpTranslationBundle): void;
+/** Replace (not merge) a locale's bundle. Tests use this between cases. */
+declare function setStrings(locale: string, bundle: NpTranslationBundle): void;
+/** Wipe every locale's bundle. Tests use this between cases. */
+declare function resetStrings(): void;
+/** Read a single locale's merged bundle (frozen view). */
+declare function getStrings(locale: string): NpTranslationBundle;
+/** Read the full registry, keyed by locale. Useful for export / admin tooling. */
+declare function getAllStrings(): Record<string, NpTranslationBundle>;
+/**
+ * Acceptable param value types for ICU MessageFormat. Beyond
+ * primitives, `Date` is accepted because ICU's `{x, date, ...}`
+ * and `{x, time, ...}` formatters expect them. `boolean` is
+ * accepted because ICU's `{x, select, true {...} false {...}}`
+ * pattern is occasionally useful even though `select` keys are
+ * stringified in matching.
+ */
+type NpTranslationParams = Record<string, string | number | boolean | Date | null | undefined>;
+/**
+ * Resolve a translated string.
+ *
+ *   await t("readingTime", "ko", { minutes: 5 })
+ *     → "5분 읽기"
+ *   await t("items.count", "en", { count: 3 })
+ *     → "3 items"  (ICU plural)
+ *   await t("missing")
+ *     → "missing"
+ *
+ * Lookup order (Phase D):
+ *   1. site-scoped admin override for the requested locale
+ *   2. requested-locale plugin / theme bundle
+ *   3. site-scoped admin override for defaultLocale
+ *   4. defaultLocale plugin / theme bundle
+ *   5. the key itself (last-resort identity fallback)
+ *
+ * The locale-locality rule: a requested-locale BUNDLE wins
+ * over a default-locale OVERRIDE. That keeps an English
+ * override from accidentally bleeding into a fully-translated
+ * Korean page — the override is only the cross-locale
+ * fallback when the requested locale has nothing at all.
+ *
+ * Async because the override cache loads from DB on first
+ * access. Subsequent calls within the same process hit the
+ * in-memory cache for free; admin writes invalidate the
+ * site's cache so the next call reloads.
+ *
+ * Phase 12.7 — message format is ICU MessageFormat. Plain
+ * strings work unchanged; `{name}` interpolation replaces the
+ * old `{{name}}`; plural / select / date / number formatters
+ * are available via the standard ICU syntax. The locale used
+ * for plural rules / number formatting is the locale the
+ * matched template came from (so an English fallback message
+ * gets English plural rules even on a Korean request).
+ */
+declare function t(key: string, locale?: string, params?: NpTranslationParams): Promise<string>;
+/**
+ * Synchronous variant for non-async contexts (rare). Skips
+ * the override layer entirely and resolves only against the
+ * in-memory plugin/theme bundles. Use `t()` everywhere
+ * possible — that's the surface admins control via the
+ * Strings settings tab.
+ */
+declare function tSync(key: string, locale?: string, params?: NpTranslationParams): string;
+/** Drop the compile cache. Tests use this between cases. */
+declare function resetTranslationCache(): void;
+
+/**
+ * Phase 12.8 — locale-to-text-direction lookup.
+ *
+ * Uses `Intl.Locale.prototype.textInfo` (ECMA-402 stage 3,
+ * supported in Node 18+ and every evergreen browser) to
+ * resolve a BCP-47 tag to its CLDR-canonical script direction.
+ * `ar`, `he`, `fa`, `ur` etc. → `rtl`; everything else → `ltr`.
+ *
+ * Returning a static `"ltr"` on lookup failure (unknown tag,
+ * older runtimes that haven't shipped textInfo) keeps the
+ * call-side tolerant — a misconfigured locale shouldn't take
+ * the page render down. Operators see the wrong direction
+ * (which is fixable in config) instead of a 500.
+ */
+type NpLocaleDirection = "ltr" | "rtl";
+declare function getLocaleDirection(locale: string): NpLocaleDirection;
+
+/**
+ * Format a number for display. Returns the input as-is when
+ * `value` isn't a finite number — defending the caller against
+ * `NaN` / `Infinity` from upstream parsing failures so the page
+ * renders something readable instead of "NaN".
+ */
+declare function formatNumber(value: number, locale?: string, options?: Intl.NumberFormatOptions): string;
+/**
+ * Format a date for display. Accepts the three shapes a CMS
+ * caller typically has on hand:
+ *   - `Date` (already parsed)
+ *   - ISO string (`updatedAt` from the API)
+ *   - epoch milliseconds
+ * Returns an empty string for unparseable inputs so a stale
+ * "Invalid Date" never lands in the page.
+ */
+declare function formatDate(value: Date | string | number, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Format a relative time difference (`-2 days`, `in 3 hours`).
+ * Wraps `Intl.RelativeTimeFormat`; the unit is constrained to
+ * the standard set the platform supports.
+ */
+declare function formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, locale?: string, options?: Intl.RelativeTimeFormatOptions): string;
+/**
+ * Test hook — clear the formatter caches between tests so a
+ * stale `Intl.*Format` instance from a previous test doesn't
+ * survive into a new locale registration. Production code never
+ * needs to call this.
+ */
+declare function resetIntlFormatterCache(): void;
+
+/**
+ * Phase D — admin-overridable UI string layer on top of the
+ * Phase 12.5 plugin/theme bundle registry.
+ *
+ * Plugins and themes ship base translations via
+ * `addStrings()`; admins layer overrides on top via the
+ * `np_string_overrides` table without editing plugin/theme
+ * code. Per-site composite key (siteId, locale, key) so each
+ * tenant can override the same plugin's string differently.
+ *
+ * The override map is held in-memory per process, keyed by
+ * site, populated lazily by `loadStringOverridesForSite()`
+ * and busted by `clearStringOverrideCacheForSite()` after
+ * admin writes. Multi-process deployments live with eventual
+ * consistency — workers reload from DB on their own
+ * cache-miss path; that's acceptable because override edits
+ * are infrequent. Sites that need strict consistency add a
+ * pubsub channel later.
+ */
+type OverrideMap = Map<string, Record<string, string | null>>;
+/**
+ * Read every override row for a site and rebuild that site's
+ * cache entry from the DB. Idempotent; safe to call
+ * concurrently (the writers are admin actions, not hot
+ * paths).
+ */
+declare function loadStringOverridesForSite(siteId: string): Promise<OverrideMap>;
+/**
+ * Get the cached override map for a site, loading it on a
+ * cache miss. Async because the cache miss has to round-trip
+ * to the DB.
+ */
+declare function getStringOverridesForSite(siteId: string): Promise<OverrideMap>;
+declare function clearStringOverrideCacheForSite(siteId: string): void;
+/** Tests use this between cases. Production never wipes globally. */
+declare function resetStringOverrideCache(): void;
+/**
+ * Resolve an override for a single (locale, key) on the
+ * current site, or null if no override is set. Synchronous
+ * after the cache is warm; the async wrapper used by `t()`
+ * ensures the cache is loaded before this is called.
+ */
+declare function getStringOverride(siteId: string, locale: string, key: string): string | null;
+/**
+ * Persist an override row. Pass `null` for `value` to mark
+ * the key as explicitly reverted (the resolution result is
+ * the same as if no row existed; the row itself stays as a
+ * marker for audit trails).
+ */
+declare function setStringOverride(locale: string, key: string, value: string | null, options?: {
+    siteId?: string;
+    updatedBy?: string | null;
+}): Promise<void>;
+/**
+ * Delete an override row (vs. setting value=null which
+ * preserves the audit trail). Useful when an admin
+ * explicitly wants to "stop tracking" an override.
+ */
+declare function deleteStringOverride(locale: string, key: string, options?: {
+    siteId?: string;
+}): Promise<void>;
+/**
+ * List every override row for a site (used by the admin UI
+ * and by exporters). Returns the raw rows including null-
+ * valued markers so the UI can show "this WAS overridden".
+ */
+interface NpStringOverrideRow {
+    siteId: string;
+    locale: string;
+    key: string;
+    value: string | null;
+    updatedAt: Date;
+    updatedBy: string | null;
+}
+declare function listStringOverridesForSite(siteId: string): Promise<NpStringOverrideRow[]>;
+
+export { type NpLocaleDirection, type NpResolveLocaleInput, type NpResolveLocaleResult, type NpStringOverrideRow, type NpTranslationBundle, type NpTranslationParams, addStrings, clearStringOverrideCacheForSite, deleteStringOverride, formatDate, formatNumber, formatRelativeTime, getAllStrings, getCurrentLocale, getI18nConfig, getLocaleDirection, getStringOverride, getStringOverridesForSite, getStrings, listStringOverridesForSite, loadStringOverridesForSite, resetI18nConfig, resetIntlFormatterCache, resetStringOverrideCache, resetStrings, resetTranslationCache, resolveLocale, setI18nConfig, setStringOverride, setStrings, t, tSync };

package/dist/i18n.js

@@ -0,0 +1,68 @@
+import {
+  formatDate,
+  formatNumber,
+  formatRelativeTime,
+  getCurrentLocale,
+  getLocaleDirection,
+  resetIntlFormatterCache,
+  resolveLocale
+} from "./chunk-MEJAHXIO.js";
+import {
+  addStrings,
+  clearStringOverrideCacheForSite,
+  deleteStringOverride,
+  getAllStrings,
+  getStringOverride,
+  getStringOverridesForSite,
+  getStrings,
+  listStringOverridesForSite,
+  loadStringOverridesForSite,
+  resetStringOverrideCache,
+  resetStrings,
+  resetTranslationCache,
+  setStringOverride,
+  setStrings,
+  t,
+  tSync
+} from "./chunk-QVJ2HCAX.js";
+import {
+  getI18nConfig,
+  resetI18nConfig,
+  setI18nConfig
+} from "./chunk-4ZLMEKFX.js";
+import "./chunk-FZ7O6DWI.js";
+import "./chunk-SBCVAC2Z.js";
+import "./chunk-ZCINJSS4.js";
+import "./chunk-JJL74ZPK.js";
+import "./chunk-XANPEOJC.js";
+import "./chunk-M43PGOQY.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  addStrings,
+  clearStringOverrideCacheForSite,
+  deleteStringOverride,
+  formatDate,
+  formatNumber,
+  formatRelativeTime,
+  getAllStrings,
+  getCurrentLocale,
+  getI18nConfig,
+  getLocaleDirection,
+  getStringOverride,
+  getStringOverridesForSite,
+  getStrings,
+  listStringOverridesForSite,
+  loadStringOverridesForSite,
+  resetI18nConfig,
+  resetIntlFormatterCache,
+  resetStringOverrideCache,
+  resetStrings,
+  resetTranslationCache,
+  resolveLocale,
+  setI18nConfig,
+  setStringOverride,
+  setStrings,
+  t,
+  tSync
+};
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}