@ultimat3/i18n 1.0.0

package/src/context.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Resolve the request locale once, then read it from the ALS context.
+ * No call site passes a locale by hand — `t()` here is the ambient translator.
+ */
+import { type Ctx } from '@ultimat3/core';
+import { type Catalog } from './catalog';
+import { type Direction, type Locale } from './locales';
+import { type TranslateVars, type Translator } from './translator';
+/** The cookie an explicit language switcher writes. */
+export declare const LOCALE_COOKIE = "x_locale";
+export interface LocaleSources {
+    /** Raw `Accept-Language` header value. */
+    header?: string | null;
+    /** Value of the `x_locale` cookie, already URL-decoded. */
+    cookie?: string | null;
+    /** `user.locale` from the authenticated user record. */
+    user?: string | null;
+    /** `?locale=es` — mobile and email preview links pass it per request. */
+    query?: string | null;
+}
+export type LocaleSourceName = keyof LocaleSources;
+export interface LocaleResolution {
+    locale: Locale;
+    direction: Direction;
+    /** Which source won — surfaced in the request log so a wrong locale is debuggable. */
+    source: LocaleSourceName | 'default';
+}
+export interface LocaleConfig {
+    supported: readonly Locale[];
+    fallback: Locale;
+    /** Precedence, highest first. */
+    order: readonly LocaleSourceName[];
+}
+/** Called once at boot from `app.config.ts`. */
+export declare function configureLocales(partial: Partial<LocaleConfig>): LocaleConfig;
+export declare function localeConfig(): LocaleConfig;
+/**
+ * Header → cookie → user record → query → default, per `config.order`.
+ * An unsupported tag is skipped rather than thrown: a stale cookie must not 500 a page.
+ */
+export declare function resolveLocale(sources: LocaleSources, overrides?: Partial<LocaleConfig>): LocaleResolution;
+/** Read `x_locale` out of a raw `Cookie` header. */
+export declare function localeCookieOf(cookieHeader?: string | null): string | undefined;
+/** The HTTP layer calls this once per request, before any render. */
+export declare function attachLocale(ctx: Ctx, locale: Locale): Locale;
+export declare function localeOf(ctx: Ctx): Locale;
+/** Ambient locale for the in-flight request; the configured fallback outside one. */
+export declare function currentLocale(): Locale;
+export declare function currentDirection(): Direction;
+/**
+ * Register a locale's catalog. Called with the framework catalog first and the app
+ * catalog second so app strings override framework strings for the same key.
+ */
+export declare function registerCatalog(locale: Locale, catalog: Catalog): void;
+export declare function registeredLocales(): Locale[];
+export declare function catalogFor(locale: Locale): Catalog;
+/** Memoized per locale — building a translator per render is pure waste. */
+export declare function translatorFor(locale: Locale): Translator;
+export declare function currentTranslator(): Translator;
+/** The ambient `t` — what framework and app code calls. Never takes a locale. */
+export declare function t(key: string, vars?: TranslateVars): string;
+/** Test/CLI seam: drop every registered catalog. */
+export declare function resetCatalogs(): void;
+//# sourceMappingURL=context.d.ts.map

package/src/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,GAAG,EAAc,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,KAAK,OAAO,EAAiB,MAAM,WAAW,CAAC;AACxD,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,MAAM,EAIZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAoB,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAErF,uDAAuD;AACvD,eAAO,MAAM,aAAa,aAAa,CAAC;AAKxC,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,sFAAsF;IACtF,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAUD,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAG7E;AAED,wBAAgB,YAAY,IAAI,YAAY,CAE3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,aAAa,EACtB,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GACpC,gBAAgB,CAYlB;AAED,oDAAoD;AACpD,wBAAgB,cAAc,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAS/E;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAEzC;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAED,wBAAgB,gBAAgB,IAAI,SAAS,CAE5C;AAKD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAItE;AAED,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAMxD;AAED,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAED,iFAAiF;AACjF,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,MAAM,CAE3D;AAED,oDAAoD;AACpD,wBAAgB,aAAa,IAAI,IAAI,CAGpC"}

package/src/context.js

@@ -0,0 +1,132 @@
+/**
+ * Resolve the request locale once, then read it from the ALS context.
+ * No call site passes a locale by hand — `t()` here is the ambient translator.
+ */
+import { useContext } from '@ultimat3/core';
+import { mergeCatalogs } from './catalog';
+import { DEFAULT_LOCALE, directionOf, negotiateLocale, normalizeLocale, SUPPORTED_LOCALES, } from './locales';
+import { createTranslator } from './translator';
+/** The cookie an explicit language switcher writes. */
+export const LOCALE_COOKIE = 'x_locale';
+/** Field name on the ALS context. Core owns `Ctx`; it stays a plain string there. */
+const CTX_LOCALE = 'locale';
+const DEFAULT_ORDER = ['header', 'cookie', 'user', 'query'];
+let config = {
+    supported: SUPPORTED_LOCALES,
+    fallback: DEFAULT_LOCALE,
+    order: DEFAULT_ORDER,
+};
+/** Called once at boot from `app.config.ts`. */
+export function configureLocales(partial) {
+    config = { ...config, ...partial };
+    return config;
+}
+export function localeConfig() {
+    return config;
+}
+/**
+ * Header → cookie → user record → query → default, per `config.order`.
+ * An unsupported tag is skipped rather than thrown: a stale cookie must not 500 a page.
+ */
+export function resolveLocale(sources, overrides = {}) {
+    const { supported, fallback, order } = { ...config, ...overrides };
+    for (const name of order) {
+        const raw = sources[name];
+        if (raw === undefined || raw === null || raw === '')
+            continue;
+        const candidate = name === 'header' ? negotiateLocale(raw, supported, '') : normalizeLocale(raw, supported, '');
+        if (candidate !== '') {
+            return { locale: candidate, direction: directionOf(candidate), source: name };
+        }
+    }
+    return { locale: fallback, direction: directionOf(fallback), source: 'default' };
+}
+/** Read `x_locale` out of a raw `Cookie` header. */
+export function localeCookieOf(cookieHeader) {
+    if (!cookieHeader)
+        return undefined;
+    for (const pair of cookieHeader.split(';')) {
+        const index = pair.indexOf('=');
+        if (index === -1)
+            continue;
+        if (pair.slice(0, index).trim() !== LOCALE_COOKIE)
+            continue;
+        return decodeURIComponent(pair.slice(index + 1).trim());
+    }
+    return undefined;
+}
+/** The HTTP layer calls this once per request, before any render. */
+export function attachLocale(ctx, locale) {
+    writeContextField(ctx, CTX_LOCALE, locale);
+    return locale;
+}
+export function localeOf(ctx) {
+    return readField(ctx, CTX_LOCALE) ?? config.fallback;
+}
+/** Ambient locale for the in-flight request; the configured fallback outside one. */
+export function currentLocale() {
+    const ctx = tryContext();
+    return (ctx === undefined ? undefined : readField(ctx, CTX_LOCALE)) ?? config.fallback;
+}
+export function currentDirection() {
+    return directionOf(currentLocale());
+}
+const registry = new Map();
+const translators = new Map();
+/**
+ * Register a locale's catalog. Called with the framework catalog first and the app
+ * catalog second so app strings override framework strings for the same key.
+ */
+export function registerCatalog(locale, catalog) {
+    const existing = registry.get(locale);
+    registry.set(locale, existing === undefined ? catalog : mergeCatalogs(existing, catalog));
+    translators.delete(locale);
+}
+export function registeredLocales() {
+    return [...registry.keys()].sort();
+}
+export function catalogFor(locale) {
+    return registry.get(locale) ?? {};
+}
+/** Memoized per locale — building a translator per render is pure waste. */
+export function translatorFor(locale) {
+    const cached = translators.get(locale);
+    if (cached !== undefined)
+        return cached;
+    const translator = createTranslator(catalogFor(locale), locale);
+    translators.set(locale, translator);
+    return translator;
+}
+export function currentTranslator() {
+    return translatorFor(currentLocale());
+}
+/** The ambient `t` — what framework and app code calls. Never takes a locale. */
+export function t(key, vars) {
+    return currentTranslator()(key, vars);
+}
+/** Test/CLI seam: drop every registered catalog. */
+export function resetCatalogs() {
+    registry.clear();
+    translators.clear();
+}
+function tryContext() {
+    try {
+        return useContext();
+    }
+    catch {
+        // Outside a request scope (boot, a CLI command, a worker tick) — no ambient locale.
+        return undefined;
+    }
+}
+/**
+ * `Ctx` is owned by core (tier 0) and cannot reference i18n's `Locale`, so the field is
+ * read structurally. One place, one cast, validated on the way out.
+ */
+function readField(ctx, field) {
+    const value = ctx[field];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function writeContextField(ctx, field, value) {
+    ctx[field] = value;
+}
+//# sourceMappingURL=context.js.map

package/src/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["context.ts"],"names":[],"mappings":"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"}

package/src/context.ts

@@ -0,0 +1,195 @@
+/**
+ * Resolve the request locale once, then read it from the ALS context.
+ * No call site passes a locale by hand — `t()` here is the ambient translator.
+ */
+
+import { type Ctx, useContext } from '@ultimat3/core';
+import { type Catalog, mergeCatalogs } from './catalog';
+import {
+  DEFAULT_LOCALE,
+  type Direction,
+  directionOf,
+  type Locale,
+  negotiateLocale,
+  normalizeLocale,
+  SUPPORTED_LOCALES,
+} from './locales';
+import { createTranslator, type TranslateVars, type Translator } from './translator';
+
+/** The cookie an explicit language switcher writes. */
+export const LOCALE_COOKIE = 'x_locale';
+
+/** Field name on the ALS context. Core owns `Ctx`; it stays a plain string there. */
+const CTX_LOCALE = 'locale';
+
+export interface LocaleSources {
+  /** Raw `Accept-Language` header value. */
+  header?: string | null;
+  /** Value of the `x_locale` cookie, already URL-decoded. */
+  cookie?: string | null;
+  /** `user.locale` from the authenticated user record. */
+  user?: string | null;
+  /** `?locale=es` — mobile and email preview links pass it per request. */
+  query?: string | null;
+}
+
+export type LocaleSourceName = keyof LocaleSources;
+
+export interface LocaleResolution {
+  locale: Locale;
+  direction: Direction;
+  /** Which source won — surfaced in the request log so a wrong locale is debuggable. */
+  source: LocaleSourceName | 'default';
+}
+
+export interface LocaleConfig {
+  supported: readonly Locale[];
+  fallback: Locale;
+  /** Precedence, highest first. */
+  order: readonly LocaleSourceName[];
+}
+
+const DEFAULT_ORDER: readonly LocaleSourceName[] = ['header', 'cookie', 'user', 'query'];
+
+let config: LocaleConfig = {
+  supported: SUPPORTED_LOCALES,
+  fallback: DEFAULT_LOCALE,
+  order: DEFAULT_ORDER,
+};
+
+/** Called once at boot from `app.config.ts`. */
+export function configureLocales(partial: Partial<LocaleConfig>): LocaleConfig {
+  config = { ...config, ...partial };
+  return config;
+}
+
+export function localeConfig(): LocaleConfig {
+  return config;
+}
+
+/**
+ * Header → cookie → user record → query → default, per `config.order`.
+ * An unsupported tag is skipped rather than thrown: a stale cookie must not 500 a page.
+ */
+export function resolveLocale(
+  sources: LocaleSources,
+  overrides: Partial<LocaleConfig> = {},
+): LocaleResolution {
+  const { supported, fallback, order } = { ...config, ...overrides };
+  for (const name of order) {
+    const raw = sources[name];
+    if (raw === undefined || raw === null || raw === '') continue;
+    const candidate =
+      name === 'header' ? negotiateLocale(raw, supported, '') : normalizeLocale(raw, supported, '');
+    if (candidate !== '') {
+      return { locale: candidate, direction: directionOf(candidate), source: name };
+    }
+  }
+  return { locale: fallback, direction: directionOf(fallback), source: 'default' };
+}
+
+/** Read `x_locale` out of a raw `Cookie` header. */
+export function localeCookieOf(cookieHeader?: string | null): string | undefined {
+  if (!cookieHeader) return undefined;
+  for (const pair of cookieHeader.split(';')) {
+    const index = pair.indexOf('=');
+    if (index === -1) continue;
+    if (pair.slice(0, index).trim() !== LOCALE_COOKIE) continue;
+    return decodeURIComponent(pair.slice(index + 1).trim());
+  }
+  return undefined;
+}
+
+/** The HTTP layer calls this once per request, before any render. */
+export function attachLocale(ctx: Ctx, locale: Locale): Locale {
+  writeContextField(ctx, CTX_LOCALE, locale);
+  return locale;
+}
+
+export function localeOf(ctx: Ctx): Locale {
+  return readField(ctx, CTX_LOCALE) ?? config.fallback;
+}
+
+/** Ambient locale for the in-flight request; the configured fallback outside one. */
+export function currentLocale(): Locale {
+  const ctx = tryContext();
+  return (ctx === undefined ? undefined : readField(ctx, CTX_LOCALE)) ?? config.fallback;
+}
+
+export function currentDirection(): Direction {
+  return directionOf(currentLocale());
+}
+
+const registry = new Map<Locale, Catalog>();
+const translators = new Map<Locale, Translator>();
+
+/**
+ * Register a locale's catalog. Called with the framework catalog first and the app
+ * catalog second so app strings override framework strings for the same key.
+ */
+export function registerCatalog(locale: Locale, catalog: Catalog): void {
+  const existing = registry.get(locale);
+  registry.set(locale, existing === undefined ? catalog : mergeCatalogs(existing, catalog));
+  translators.delete(locale);
+}
+
+export function registeredLocales(): Locale[] {
+  return [...registry.keys()].sort();
+}
+
+export function catalogFor(locale: Locale): Catalog {
+  return registry.get(locale) ?? {};
+}
+
+/**
+ * Memoized per locale — building a translator per render is pure waste.
+ * `TCatalog` narrows the key type only; the runtime catalog is whatever is registered.
+ */
+export function translatorFor<TCatalog = Catalog>(locale: Locale): Translator<TCatalog> {
+  let translator = translators.get(locale);
+  if (translator === undefined) {
+    translator = createTranslator(catalogFor(locale), locale);
+    translators.set(locale, translator);
+  }
+  // One cast, one place. `TCatalog` narrows the key parameter and nothing else, so the memoized
+  // object already is the right value — the registry cannot be keyed by an app's catalog type.
+  return translator as unknown as Translator<TCatalog>;
+}
+
+/** The ambient translator for the in-flight request. Pass the app's catalog type to get typed keys. */
+export function useI18n<TCatalog = Catalog>(): Translator<TCatalog> {
+  return translatorFor<TCatalog>(currentLocale());
+}
+
+/** The ambient `t` — what framework and app code calls. Never takes a locale. */
+export function t(key: string, vars?: TranslateVars): string {
+  return useI18n()(key, vars);
+}
+
+/** Test/CLI seam: drop every registered catalog. */
+export function resetCatalogs(): void {
+  registry.clear();
+  translators.clear();
+}
+
+function tryContext(): Ctx | undefined {
+  try {
+    return useContext();
+  } catch {
+    // Outside a request scope (boot, a CLI command, a worker tick) — no ambient locale.
+    return undefined;
+  }
+}
+
+/**
+ * `Ctx` is owned by core (tier 0) and cannot reference i18n's `Locale`, so the field is
+ * read structurally. One place, one cast, validated on the way out.
+ */
+function readField(ctx: Ctx, field: string): string | undefined {
+  const value = (ctx as unknown as Record<string, unknown>)[field];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function writeContextField(ctx: Ctx, field: string, value: string): void {
+  (ctx as unknown as Record<string, unknown>)[field] = value;
+}

package/src/define-catalogs.ts

@@ -0,0 +1,56 @@
+/**
+ * The one call an app makes to declare its catalogs: validate and flatten every locale,
+ * register it under the framework's own strings, and configure the supported set.
+ * Boot-time only — nothing here runs per request.
+ */
+
+import { type Catalog, catalogKeys, loadCatalog, mergeCatalogs } from './catalog';
+import { configureLocales, registerCatalog } from './context';
+import { localeUnsupported } from './errors';
+import { registerFrameworkCatalog } from './framework';
+
+/** Locale tag → the catalog file's parsed contents, nested exactly as authored. */
+export type CatalogSources = Readonly<Record<string, unknown>>;
+
+export interface DefineCatalogsInput<TLocales extends CatalogSources> {
+  /** The locale an unresolved request falls back to. Must be a key of `locales`. */
+  readonly default: keyof TLocales & string;
+  /** One entry per shipped locale — `{ en, es }` after importing the JSON files. */
+  readonly locales: TLocales;
+}
+
+export interface CatalogSet<TLocales extends CatalogSources> {
+  readonly default: keyof TLocales & string;
+  readonly locales: readonly (keyof TLocales & string)[];
+  /** Flattened app strings only. Framework strings are registered, never copied in here. */
+  readonly catalogs: Readonly<Record<keyof TLocales & string, Catalog>>;
+  /** Every dot-key across every locale, sorted — the app's key space. */
+  keys(): string[];
+}
+
+export function defineCatalogs<TLocales extends CatalogSources>(
+  input: DefineCatalogsInput<TLocales>,
+): CatalogSet<TLocales> {
+  const locales = Object.keys(input.locales) as (keyof TLocales & string)[];
+  if (!locales.includes(input.default)) throw localeUnsupported(input.default, locales);
+
+  // Load everything before registering anything: a malformed catalog must fail the boot
+  // whole, not leave half the locales live and the other half missing.
+  const loaded = locales.map((locale) => [locale, loadCatalog(input.locales[locale])] as const);
+
+  for (const [locale, catalog] of loaded) {
+    // Framework first, app second. `registerCatalog` merges and the later call wins, which is
+    // how an app overrides `errors.notFound.title` without forking the framework catalog.
+    registerFrameworkCatalog(locale);
+    registerCatalog(locale, catalog);
+  }
+  configureLocales({ supported: locales, fallback: input.default });
+
+  const catalogs = Object.fromEntries(loaded) as Readonly<Record<keyof TLocales & string, Catalog>>;
+  return {
+    default: input.default,
+    locales,
+    catalogs,
+    keys: () => catalogKeys(mergeCatalogs(...loaded.map(([, catalog]) => catalog))),
+  };
+}

package/src/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The X_* error codes owned by @ultimat3/i18n.
+ * Every throw carries a stable code, a cause, and a command that fixes it.
+ */
+import { UltimateError } from '@ultimat3/core';
+export declare const I18N_ERROR_CODES: readonly ['X_LOCALE_UNSUPPORTED', 'X_CATALOG_MISSING_KEYS', 'X_CATALOG_INVALID'];
+export type I18nErrorCode = (typeof I18N_ERROR_CODES)[number];
+export declare class I18nError extends UltimateError {
+    constructor(init: {
+        code: I18nErrorCode;
+        cause: string;
+        fix: string;
+    });
+}
+export declare function localeUnsupported(tag: string, supported: readonly string[]): I18nError;
+/**
+ * `fix` must name the locale file and the exact keys — an agent reading this
+ * error should not have to diff two catalogs to learn what to write.
+ */
+export declare function catalogMissingKeys(locale: string, keys: readonly string[]): I18nError;
+export declare function catalogInvalid(path: string, cause: string): I18nError;
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,eAAO,MAAM,gBAAgB,YAC3B,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,CACX,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,qBAAa,SAAU,SAAQ,aAAa;IAC1C,YAAY,IAAI,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAOpE;CACF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAMtF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAQrF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAMrE"}

package/src/errors.js

@@ -0,0 +1,52 @@
+/**
+ * The X_* error codes owned by @ultimat3/i18n.
+ * Every throw carries a stable code, a cause, and a command that fixes it.
+ */
+import { UltimateError } from '@ultimat3/core';
+export const I18N_ERROR_CODES = [
+    'X_LOCALE_UNSUPPORTED',
+    'X_CATALOG_MISSING_KEYS',
+    'X_CATALOG_INVALID',
+];
+export class I18nError extends UltimateError {
+    constructor(init) {
+        super({
+            code: init.code,
+            cause: init.cause,
+            fix: init.fix,
+            docs: `https://ultimate.dev/errors/${init.code}`,
+        });
+    }
+}
+export function localeUnsupported(tag, supported) {
+    return new I18nError({
+        code: 'X_LOCALE_UNSUPPORTED',
+        cause: `locale "${tag}" is not in the supported set [${supported.join(', ')}]`,
+        fix: `x i18n add ${normalizeForFix(tag)}`,
+    });
+}
+/**
+ * `fix` must name the locale file and the exact keys — an agent reading this
+ * error should not have to diff two catalogs to learn what to write.
+ */
+export function catalogMissingKeys(locale, keys) {
+    const shown = keys.slice(0, 12);
+    const suffix = keys.length > shown.length ? `, +${keys.length - shown.length} more` : '';
+    return new I18nError({
+        code: 'X_CATALOG_MISSING_KEYS',
+        cause: `packages/i18n/catalogs/${locale}.json is missing ${keys.length} key(s) used in source: ${shown.join(', ')}${suffix}`,
+        fix: `x i18n sync ${locale}`,
+    });
+}
+export function catalogInvalid(path, cause) {
+    return new I18nError({
+        code: 'X_CATALOG_INVALID',
+        cause: `catalog entry "${path}": ${cause}`,
+        fix: 'x i18n check --json',
+    });
+}
+function normalizeForFix(tag) {
+    const primary = tag.split('-')[0] ?? tag;
+    return primary.toLowerCase().replace(/[^a-z]/g, '') || 'xx';
+}
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,sBAAsB;IACtB,wBAAwB;IACxB,mBAAmB;CACX,CAAC;AAIX,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C,YAAY,IAAyD;QACnE,KAAK,CAAC;YACJ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,+BAA+B,IAAI,CAAC,IAAI,EAAE;SACjD,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,SAA4B;IACzE,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,sBAAsB;QAC5B,KAAK,EAAE,WAAW,GAAG,kCAAkC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC9E,GAAG,EAAE,cAAc,eAAe,CAAC,GAAG,CAAC,EAAE;KAC1C,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,IAAuB;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACzF,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,0BAA0B,MAAM,oBAAoB,IAAI,CAAC,MAAM,2BAA2B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE;QAC5H,GAAG,EAAE,eAAe,MAAM,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAa;IACxD,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,kBAAkB,IAAI,MAAM,KAAK,EAAE;QAC1C,GAAG,EAAE,qBAAqB;KAC3B,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IACzC,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC;AAC9D,CAAC"}

package/src/errors.ts

@@ -0,0 +1,73 @@
+/**
+ * The X_* error codes owned by @ultimat3/i18n.
+ * Every throw carries a stable code, a cause, and a command that fixes it.
+ */
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const I18N_ERROR_CODES = [
+  'X_LOCALE_UNSUPPORTED',
+  'X_CATALOG_MISSING_KEYS',
+  'X_CATALOG_INVALID',
+] as const;
+
+export type I18nErrorCode = (typeof I18N_ERROR_CODES)[number];
+
+export const I18N_ERROR_TITLES: Readonly<Record<I18nErrorCode, string>> = {
+  X_LOCALE_UNSUPPORTED: 'locale is not in the supported set',
+  X_CATALOG_MISSING_KEYS: 'a catalog is missing keys used in source',
+  X_CATALOG_INVALID: 'a catalog entry is malformed',
+};
+
+// Titles must be registered for format() to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(I18N_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export class I18nError extends UltimateError {
+  constructor(init: { code: I18nErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+  }
+}
+
+export function localeUnsupported(tag: string, supported: readonly string[]): I18nError {
+  return new I18nError({
+    code: 'X_LOCALE_UNSUPPORTED',
+    cause: `locale "${tag}" is not in the supported set [${supported.join(', ')}]`,
+    fix: `x i18n add ${normalizeForFix(tag)}`,
+  });
+}
+
+/**
+ * `fix` must name the locale file and the exact keys — an agent reading this
+ * error should not have to diff two catalogs to learn what to write.
+ */
+export function catalogMissingKeys(locale: string, keys: readonly string[]): I18nError {
+  const shown = keys.slice(0, 12);
+  const suffix = keys.length > shown.length ? `, +${keys.length - shown.length} more` : '';
+  return new I18nError({
+    code: 'X_CATALOG_MISSING_KEYS',
+    cause: `packages/i18n/catalogs/${locale}.json is missing ${keys.length} key(s) used in source: ${shown.join(', ')}${suffix}`,
+    fix: `x i18n sync ${locale}`,
+  });
+}
+
+export function catalogInvalid(path: string, cause: string): I18nError {
+  return new I18nError({
+    code: 'X_CATALOG_INVALID',
+    cause: `catalog entry "${path}": ${cause}`,
+    fix: 'x i18n check --json',
+  });
+}
+
+function normalizeForFix(tag: string): string {
+  const primary = tag.split('-')[0] ?? tag;
+  return primary.toLowerCase().replace(/[^a-z]/g, '') || 'xx';
+}