@happyvertical/smrt-languages 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,247 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+/**
+ * Build the locale fallback chain for a requested locale.
+ *
+ * Example: `fr-CA` with default `en` → `['fr-CA', 'fr', 'en']`.
+ * Duplicates and empty segments are removed.
+ */
+export declare function buildLocaleFallbackChain(requested: string, defaultLocale: string): string[];
+
+/**
+ * Build a glossary string suitable for inclusion in an AI translation prompt.
+ *
+ * Pulls the tenant's existing language overrides for the source/target locales
+ * and renders them as a concise list of "source → target" pairs, restricted to
+ * keys that actually have both sides. The intent is "make AI auto-translations
+ * match tenant voice", not bulk dump every override.
+ *
+ * Returns an empty string when there is nothing useful to add.
+ */
+export declare function buildTenantGlossary(overrides: LanguageOverride[], options: {
+    sourceLocale: string;
+    targetLocale: string;
+    max?: number;
+}): string;
+
+/** Deterministic translation-job ID — used for stampede protection. */
+export declare function buildTranslationJobId(key: string, targetLocale: string): string;
+
+export declare function clearLanguageCache(): void;
+
+/** Stable hash used to gate auto-translation re-runs against a specific source. */
+export declare function computeSourceHash(template: string): string;
+
+export declare function defineLanguageString(input: LanguageStringDefinitionInput): LanguageStringDefinition;
+
+export declare function getLanguageCacheTtlMs(): number;
+
+/**
+ * Drop cached entries that match the given (key, locale).
+ *
+ * - When `tenantId` is provided, only that tenant's entries for this DB are dropped.
+ * - When `tenantId` is null/undefined, every (key, locale, *) entry across tenants
+ *   is dropped — used for app-level writes that affect all tenants.
+ */
+export declare function invalidateLanguageCache(key: string, locale: string, tenantId: string | null | undefined, db: DatabaseInterface | unknown): void;
+
+export declare function invalidateResolvedLanguageCache(key: string, locale: string, tenantId: string | null | undefined, db: unknown): void;
+
+export declare interface LanguageCacheValue {
+    key: string;
+    locale: string;
+    template: string;
+    source: ResolvedLanguageString['source'];
+    resolvedFromLocale: string;
+}
+
+export declare class LanguageOverride extends SmrtObject {
+    key: string;
+    locale: string;
+    tenantId: string | null;
+    template: string;
+    /** True when this row was produced by the AI translation job. */
+    auto_generated: boolean;
+    /** sha256 of the source template at translation time, for re-translation gating. */
+    source_hash: string | null;
+    /** AI model identifier (null for human-edited rows). */
+    ai_model: string | null;
+    /** ISO timestamp marking admin review of an auto-generated row. */
+    reviewed_at: string | null;
+    /** User ID of the reviewer. */
+    reviewed_by: string | null;
+    constructor(options?: LanguageOverrideCtorOptions);
+    save(): Promise<this>;
+    private saveAfterIdentityChange;
+    private saveAfterIdentityChangeInTransaction;
+    private saveAfterIdentityChangeWithDeferredDelete;
+    delete(): Promise<void>;
+    /**
+     * Mark this auto-generated row as reviewed by an admin. Useful for the
+     * admin review queue surfaced via `smrt languages approve <id>`.
+     */
+    approve(reviewerId: string): Promise<this>;
+    private getPersistedIdentity;
+}
+
+export declare class LanguageOverrideCollection extends SmrtCollection<LanguageOverride> {
+    static readonly _itemClass: typeof LanguageOverride;
+    /**
+     * Look up the app-level (tenantId = null) override for a (key, locale) pair.
+     * App-level rows hold AI auto-translations and ops-curated app-wide strings.
+     */
+    getAppOverride(key: string, locale: string): Promise<LanguageOverride | null>;
+    getTenantOverride(key: string, locale: string, tenantId: string): Promise<LanguageOverride | null>;
+    /**
+     * Convenience helper for the resolver: returns the app and (optional) tenant
+     * override rows for a (key, locale).
+     */
+    getResolutionLayers(key: string, locale: string, tenantId?: string | null): Promise<{
+        app: LanguageOverride | null;
+        tenant: LanguageOverride | null;
+    }>;
+    /** All overrides for a tenant (used to build the AI translation glossary). */
+    listTenantOverrides(tenantId: string): Promise<LanguageOverride[]>;
+    /** Auto-generated overrides that no admin has approved yet. */
+    listUnreviewedAutoTranslations(options?: {
+        locale?: string;
+        limit?: number;
+    }): Promise<LanguageOverride[]>;
+}
+
+export declare interface LanguageOverrideCtorOptions extends SmrtObjectOptions, LanguageOverrideOptions {
+}
+
+export declare interface LanguageOverrideOptions {
+    key?: string;
+    locale?: string;
+    tenantId?: string | null;
+    template?: string;
+    auto_generated?: boolean;
+    source_hash?: string | null;
+    ai_model?: string | null;
+    reviewed_at?: string | null;
+    reviewed_by?: string | null;
+}
+
+export declare const LanguageRegistry: {
+    register(input: LanguageStringDefinitionInput): LanguageStringDefinition;
+    get(key: string, locale: string): LanguageStringDefinition | undefined;
+    has(key: string, locale: string): boolean;
+    hasKey(key: string): boolean;
+    /** Return the locales that have a registered code default for the given key. */
+    getLocalesForKey(key: string): string[];
+    /** All registered (key, locale, template) triples. Used by the batch translator. */
+    getAll(): LanguageStringDefinition[];
+    /** Distinct keys currently registered. */
+    getKeys(): string[];
+    clear(): void;
+};
+
+/**
+ * Per-package config bag, read via `getPackageConfig('languages', ...)`.
+ *
+ * `overrides[key][locale]` is a plain string template that takes precedence over
+ * code defaults for that (key, locale) pair. It is the file-config layer in the
+ * 5-layer resolution chain.
+ */
+export declare interface LanguagesPackageConfig {
+    /** Default locale used when none is supplied at resolve-time. Defaults to 'en'. */
+    defaultLocale?: string;
+    /** When set, AI auto-translation jobs are only enqueued for these locales. */
+    supportedLocales?: string[];
+    /** Daily cap on AI translation jobs per tenant (null = no cap). */
+    translationBudgetPerTenantPerDay?: number | null;
+    /** File-config overrides, keyed by (key)(locale). */
+    overrides?: Record<string, Record<string, string>>;
+    [key: string]: unknown;
+}
+
+export declare interface LanguageStringDefinition {
+    key: string;
+    locale: string;
+    template: string;
+    /** sha256 of the template at registration time, used for re-translation gating */
+    sourceHash: string;
+}
+
+/** A registered code default for a single (key, locale) pair. */
+export declare interface LanguageStringDefinitionInput {
+    key: string;
+    locale: string;
+    template: string;
+}
+
+export declare type LanguageVariables = Record<string, unknown>;
+
+/**
+ * Normalize a BCP-47-ish locale tag for consistent matching across the
+ * registry, the cache, and DB lookups.
+ *
+ * Lowercases the language subtag and uppercases everything after it so
+ * `fr-ca`, `fr-CA`, and `Fr-Ca` collapse to the same key. This is **not**
+ * canonical BCP-47 casing (proper BCP-47 lower-cases variants and uses
+ * Title-case for script subtags like `Hans`); it is an internal
+ * normalization shared by every layer in this package and intentionally
+ * stricter than what BCP-47 mandates.
+ */
+export declare function normalizeLocale(locale: string): string;
+
+/* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */
+
+/**
+ * Render `{var}` placeholders against the supplied variables.
+ *
+ * When at least one variable is provided, every `{...}` placeholder in the
+ * template is replaced; missing or `undefined`/`null` variables collapse to
+ * empty strings (callers that pass `name` but not `title` get the `{title}`
+ * placeholder removed).
+ *
+ * When `variables` is `undefined` or `{}` the template is returned unchanged
+ * — that fast path avoids the regex pass for the common "no interpolation
+ * needed" case. If you need every placeholder collapsed regardless, pass at
+ * least one variable (e.g. `{ __forceRender: true }`).
+ */
+export declare function renderTemplate(template: string, variables?: LanguageVariables): string;
+
+export declare interface ResolvedLanguageString {
+    key: string;
+    locale: string;
+    /** The fully-rendered string with variables substituted. */
+    text: string;
+    /** The raw template that produced `text`. */
+    template: string;
+    /** Locale that actually produced the template (may differ from `locale` after fallback). */
+    resolvedFromLocale: string;
+    /**
+     * `'code' | 'config' | 'app' | 'tenant' | 'runtime'`. `'fallback'` indicates
+     * no exact match was found and a fallback locale was used.
+     */
+    source: 'code' | 'config' | 'app' | 'tenant' | 'runtime' | 'fallback' | 'missing';
+}
+
+export declare function resolveLanguageString(key: string, options?: ResolveLanguageStringOptions): Promise<ResolvedLanguageString>;
+
+export declare interface ResolveLanguageStringOptions {
+    db?: SmrtClassOptions['db'];
+    tenantId?: string | null;
+    locale?: string;
+    /** Variables substituted into `{var}` placeholders. */
+    vars?: LanguageVariables;
+    /** Optional per-call override for the rendered template (highest precedence). */
+    overrides?: {
+        template?: string;
+    };
+    /**
+     * When `true`, throw if the resolution chain finishes without producing a
+     * template. When `false` (default), return the key as the rendered string and
+     * enqueue an AI translation job for the missing (key, locale).
+     */
+    strict?: boolean;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,242 @@
+import { ObjectRegistry } from "@happyvertical/smrt-core";
+import { i as invalidateLanguageCache, n as normalizeLocale, r as renderTemplate, e as buildLocaleFallbackChain, L as LanguageOverrideCollection, g as getCachedLanguage, a as LanguageRegistry, s as setCachedLanguage } from "./chunks/language-registry-CgsuwQo6.js";
+import { f, b, d, h, c, j, k } from "./chunks/language-registry-CgsuwQo6.js";
+import { getPackageConfig } from "@happyvertical/smrt-config";
+import { getTenantId } from "@happyvertical/smrt-tenancy";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+const DEFAULT_LOCALE = "en";
+function getLanguagesConfig() {
+  return getPackageConfig("languages", {
+    defaultLocale: DEFAULT_LOCALE,
+    overrides: {}
+  });
+}
+async function resolveBaseForLocale(key, locale, options, config) {
+  const tenantId = options.tenantId !== void 0 ? options.tenantId : getTenantId() ?? null;
+  let collection = null;
+  if (options.db) {
+    collection = await LanguageOverrideCollection.create({
+      db: options.db
+    });
+  }
+  const cacheDb = collection?.db ?? options.db;
+  const cached = getCachedLanguage(key, locale, tenantId, cacheDb);
+  if (cached) {
+    return {
+      template: cached.template,
+      source: cached.source,
+      resolvedFromLocale: cached.resolvedFromLocale
+    };
+  }
+  if (collection && tenantId) {
+    const tenantOverride = await collection.getTenantOverride(
+      key,
+      locale,
+      tenantId
+    );
+    if (tenantOverride) {
+      return finalize({
+        key,
+        locale,
+        tenantId,
+        db: cacheDb,
+        attempt: {
+          template: tenantOverride.template,
+          source: "tenant",
+          resolvedFromLocale: locale
+        }
+      });
+    }
+  }
+  if (collection) {
+    const appOverride = await collection.getAppOverride(key, locale);
+    if (appOverride) {
+      return finalize({
+        key,
+        locale,
+        tenantId,
+        db: cacheDb,
+        attempt: {
+          template: appOverride.template,
+          source: "app",
+          resolvedFromLocale: locale
+        }
+      });
+    }
+  }
+  const configForKey = config.overrides?.[key];
+  const configTemplate = lookupNormalizedLocale(configForKey, locale);
+  if (typeof configTemplate === "string") {
+    return finalize({
+      key,
+      locale,
+      tenantId,
+      db: cacheDb,
+      attempt: {
+        template: configTemplate,
+        source: "config",
+        resolvedFromLocale: locale
+      }
+    });
+  }
+  const definition = LanguageRegistry.get(key, locale);
+  if (definition) {
+    return finalize({
+      key,
+      locale,
+      tenantId,
+      db: cacheDb,
+      attempt: {
+        template: definition.template,
+        source: "code",
+        resolvedFromLocale: locale
+      }
+    });
+  }
+  return {
+    template: null,
+    source: "missing",
+    resolvedFromLocale: locale
+  };
+}
+function lookupNormalizedLocale(bag, locale) {
+  if (!bag) return void 0;
+  if (typeof bag[locale] === "string") return bag[locale];
+  for (const [candidate, template] of Object.entries(bag)) {
+    if (normalizeLocale(candidate) === locale) {
+      return template;
+    }
+  }
+  return void 0;
+}
+function finalize(args) {
+  if (args.attempt.template !== null) {
+    const value = {
+      key: args.key,
+      locale: args.locale,
+      template: args.attempt.template,
+      source: args.attempt.source,
+      resolvedFromLocale: args.attempt.resolvedFromLocale
+    };
+    setCachedLanguage(args.key, args.locale, args.tenantId, args.db, value);
+  }
+  return args.attempt;
+}
+async function resolveLanguageString(key, options = {}) {
+  if (!key || key.trim() === "") {
+    throw new Error("resolveLanguageString requires a non-empty key");
+  }
+  const config = getLanguagesConfig();
+  const defaultLocale = normalizeLocale(config.defaultLocale ?? DEFAULT_LOCALE);
+  const requested = normalizeLocale(options.locale ?? defaultLocale);
+  if (typeof options.overrides?.template === "string") {
+    return {
+      key,
+      locale: requested,
+      template: options.overrides.template,
+      text: renderTemplate(options.overrides.template, options.vars),
+      resolvedFromLocale: requested,
+      source: "runtime"
+    };
+  }
+  const chain = buildLocaleFallbackChain(requested, defaultLocale);
+  let firstHit = null;
+  let firstLocale = requested;
+  for (const locale of chain) {
+    const attempt = await resolveBaseForLocale(key, locale, options, config);
+    if (attempt.template !== null) {
+      firstHit = attempt;
+      firstLocale = locale;
+      break;
+    }
+  }
+  if (!firstHit) {
+    if (options.strict) {
+      throw new Error(
+        `Language string "${key}" has no resolution for locale "${requested}"`
+      );
+    }
+    await tryEnqueueTranslation({
+      key,
+      requestedLocale: requested,
+      defaultLocale,
+      options
+    });
+    return {
+      key,
+      locale: requested,
+      template: key,
+      text: key,
+      resolvedFromLocale: requested,
+      source: "missing"
+    };
+  }
+  if (firstLocale !== requested) {
+    await tryEnqueueTranslation({
+      key,
+      requestedLocale: requested,
+      defaultLocale,
+      options
+    });
+    return {
+      key,
+      locale: requested,
+      template: firstHit.template ?? key,
+      text: renderTemplate(firstHit.template ?? key, options.vars),
+      resolvedFromLocale: firstLocale,
+      source: "fallback"
+    };
+  }
+  return {
+    key,
+    locale: requested,
+    template: firstHit.template ?? key,
+    text: renderTemplate(firstHit.template ?? key, options.vars),
+    resolvedFromLocale: firstLocale,
+    source: firstHit.source
+  };
+}
+async function tryEnqueueTranslation(args) {
+  if (!args.options.db) {
+    return;
+  }
+  if (normalizeLocale(args.requestedLocale) === args.defaultLocale) {
+    return;
+  }
+  try {
+    const { enqueueTranslationJob } = await import("./chunks/translation-job-DHg2E-eH.js");
+    await enqueueTranslationJob({
+      key: args.key,
+      targetLocale: args.requestedLocale,
+      sourceLocale: args.defaultLocale,
+      tenantId: args.options.tenantId ?? getTenantId() ?? null,
+      db: args.options.db
+    });
+  } catch {
+  }
+}
+function invalidateResolvedLanguageCache(key, locale, tenantId, db) {
+  invalidateLanguageCache(key, locale, tenantId, db);
+}
+const PACKAGE_VERSION_INITIALIZED = true;
+export {
+  f as LanguageOverride,
+  LanguageOverrideCollection,
+  LanguageRegistry,
+  PACKAGE_VERSION_INITIALIZED,
+  buildLocaleFallbackChain,
+  b as buildTenantGlossary,
+  d as buildTranslationJobId,
+  h as clearLanguageCache,
+  c as computeSourceHash,
+  j as defineLanguageString,
+  k as getLanguageCacheTtlMs,
+  invalidateLanguageCache,
+  invalidateResolvedLanguageCache,
+  normalizeLocale,
+  renderTemplate,
+  resolveLanguageString
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/__smrt-register__.ts","../src/language-resolver.ts","../src/index.ts"],"sourcesContent":["/**\n * Self-registers this package's build-time manifest before any @smrt()\n * decorator in the package fires. Same pattern as smrt-prompts — see\n * packages/prompts/src/__smrt-register__.ts and issue #1132 for context.\n */\nimport { ObjectRegistry } from '@happyvertical/smrt-core';\n\nObjectRegistry.registerPackageManifest(\n  new URL('./manifest.json', import.meta.url),\n);\n","import { getPackageConfig } from '@happyvertical/smrt-config';\nimport { getTenantId } from '@happyvertical/smrt-tenancy';\nimport {\n  getCachedLanguage,\n  invalidateLanguageCache,\n  setCachedLanguage,\n} from './cache.js';\nimport { LanguageOverrideCollection } from './collections/LanguageOverrideCollection.js';\nimport { LanguageRegistry } from './language-registry.js';\nimport type {\n  LanguageCacheValue,\n  LanguagesPackageConfig,\n  ResolvedLanguageString,\n  ResolveLanguageStringOptions,\n} from './types.js';\nimport {\n  buildLocaleFallbackChain,\n  normalizeLocale,\n  renderTemplate,\n} from './utils.js';\n\nconst DEFAULT_LOCALE = 'en';\n\nfunction getLanguagesConfig(): LanguagesPackageConfig {\n  return getPackageConfig<LanguagesPackageConfig>('languages', {\n    defaultLocale: DEFAULT_LOCALE,\n    overrides: {},\n  });\n}\n\ninterface ResolutionAttempt {\n  template: string | null;\n  source: ResolvedLanguageString['source'];\n  resolvedFromLocale: string;\n}\n\nasync function resolveBaseForLocale(\n  key: string,\n  locale: string,\n  options: ResolveLanguageStringOptions,\n  config: LanguagesPackageConfig,\n): Promise<ResolutionAttempt> {\n  const tenantId =\n    options.tenantId !== undefined ? options.tenantId : (getTenantId() ?? null);\n\n  let collection: LanguageOverrideCollection | null = null;\n  if (options.db) {\n    collection = await (LanguageOverrideCollection as any).create({\n      db: options.db,\n    });\n  }\n\n  const cacheDb = collection?.db ?? options.db;\n  const cached = getCachedLanguage(key, locale, tenantId, cacheDb);\n  if (cached) {\n    return {\n      template: cached.template,\n      source: cached.source,\n      resolvedFromLocale: cached.resolvedFromLocale,\n    };\n  }\n\n  // 1. Tenant override (highest precedence among stored layers).\n  if (collection && tenantId) {\n    const tenantOverride = await collection.getTenantOverride(\n      key,\n      locale,\n      tenantId,\n    );\n    if (tenantOverride) {\n      return finalize({\n        key,\n        locale,\n        tenantId,\n        db: cacheDb,\n        attempt: {\n          template: tenantOverride.template,\n          source: 'tenant',\n          resolvedFromLocale: locale,\n        },\n      });\n    }\n  }\n\n  // 2. App-level override (incl. AI auto-translations).\n  if (collection) {\n    const appOverride = await collection.getAppOverride(key, locale);\n    if (appOverride) {\n      return finalize({\n        key,\n        locale,\n        tenantId,\n        db: cacheDb,\n        attempt: {\n          template: appOverride.template,\n          source: 'app',\n          resolvedFromLocale: locale,\n        },\n      });\n    }\n  }\n\n  // 3. File-config override. Locale keys in user-authored config files\n  // commonly come in mixed case (`fr-ca`, `Fr-CA`, etc.); normalize lookup so\n  // config matches the same way the DB and code-default layers do.\n  const configForKey = config.overrides?.[key];\n  const configTemplate = lookupNormalizedLocale(configForKey, locale);\n  if (typeof configTemplate === 'string') {\n    return finalize({\n      key,\n      locale,\n      tenantId,\n      db: cacheDb,\n      attempt: {\n        template: configTemplate,\n        source: 'config',\n        resolvedFromLocale: locale,\n      },\n    });\n  }\n\n  // 4. Code default.\n  const definition = LanguageRegistry.get(key, locale);\n  if (definition) {\n    return finalize({\n      key,\n      locale,\n      tenantId,\n      db: cacheDb,\n      attempt: {\n        template: definition.template,\n        source: 'code',\n        resolvedFromLocale: locale,\n      },\n    });\n  }\n\n  return {\n    template: null,\n    source: 'missing',\n    resolvedFromLocale: locale,\n  };\n}\n\nfunction lookupNormalizedLocale(\n  bag: Record<string, string> | undefined,\n  locale: string,\n): string | undefined {\n  if (!bag) return undefined;\n  // Fast path: exact match (most file configs use the canonical form).\n  if (typeof bag[locale] === 'string') return bag[locale];\n  for (const [candidate, template] of Object.entries(bag)) {\n    if (normalizeLocale(candidate) === locale) {\n      return template;\n    }\n  }\n  return undefined;\n}\n\nfunction finalize(args: {\n  key: string;\n  locale: string;\n  tenantId: string | null;\n  db: unknown;\n  attempt: ResolutionAttempt;\n}): ResolutionAttempt {\n  if (args.attempt.template !== null) {\n    const value: LanguageCacheValue = {\n      key: args.key,\n      locale: args.locale,\n      template: args.attempt.template,\n      source: args.attempt.source,\n      resolvedFromLocale: args.attempt.resolvedFromLocale,\n    };\n    setCachedLanguage(args.key, args.locale, args.tenantId, args.db, value);\n  }\n  return args.attempt;\n}\n\nexport async function resolveLanguageString(\n  key: string,\n  options: ResolveLanguageStringOptions = {},\n): Promise<ResolvedLanguageString> {\n  if (!key || key.trim() === '') {\n    throw new Error('resolveLanguageString requires a non-empty key');\n  }\n\n  const config = getLanguagesConfig();\n  const defaultLocale = normalizeLocale(config.defaultLocale ?? DEFAULT_LOCALE);\n  const requested = normalizeLocale(options.locale ?? defaultLocale);\n\n  // Runtime override always wins, regardless of locale chain.\n  if (typeof options.overrides?.template === 'string') {\n    return {\n      key,\n      locale: requested,\n      template: options.overrides.template,\n      text: renderTemplate(options.overrides.template, options.vars),\n      resolvedFromLocale: requested,\n      source: 'runtime',\n    };\n  }\n\n  const chain = buildLocaleFallbackChain(requested, defaultLocale);\n\n  let firstHit: ResolutionAttempt | null = null;\n  let firstLocale = requested;\n  for (const locale of chain) {\n    const attempt = await resolveBaseForLocale(key, locale, options, config);\n    if (attempt.template !== null) {\n      firstHit = attempt;\n      firstLocale = locale;\n      break;\n    }\n  }\n\n  if (!firstHit) {\n    if (options.strict) {\n      throw new Error(\n        `Language string \"${key}\" has no resolution for locale \"${requested}\"`,\n      );\n    }\n    // Soft-miss: enqueue translation if the requested locale differs from the\n    // default and a default-locale source exists. Failure of the enqueue path\n    // must never break resolution — we still return the key as the rendered\n    // text so the UI degrades gracefully.\n    await tryEnqueueTranslation({\n      key,\n      requestedLocale: requested,\n      defaultLocale,\n      options,\n    });\n    return {\n      key,\n      locale: requested,\n      template: key,\n      text: key,\n      resolvedFromLocale: requested,\n      source: 'missing',\n    };\n  }\n\n  // Hit at a fallback locale that isn't the requested one — fire-and-forget a\n  // translation job for the requested target.\n  if (firstLocale !== requested) {\n    await tryEnqueueTranslation({\n      key,\n      requestedLocale: requested,\n      defaultLocale,\n      options,\n    });\n    return {\n      key,\n      locale: requested,\n      template: firstHit.template ?? key,\n      text: renderTemplate(firstHit.template ?? key, options.vars),\n      resolvedFromLocale: firstLocale,\n      source: 'fallback',\n    };\n  }\n\n  return {\n    key,\n    locale: requested,\n    template: firstHit.template ?? key,\n    text: renderTemplate(firstHit.template ?? key, options.vars),\n    resolvedFromLocale: firstLocale,\n    source: firstHit.source,\n  };\n}\n\n/**\n * Best-effort enqueue of an AI translation job. Wrapped so resolution never\n * fails because of an enqueue error, missing optional dependency, etc.\n *\n * The actual job machinery lives in `./translation-job.ts` and is loaded\n * lazily so the resolver does not pull `@happyvertical/ai` into the import\n * graph for synchronous resolves that never miss.\n */\nasync function tryEnqueueTranslation(args: {\n  key: string;\n  requestedLocale: string;\n  defaultLocale: string;\n  options: ResolveLanguageStringOptions;\n}): Promise<void> {\n  if (!args.options.db) {\n    // Without a DB we cannot persist a job; skip silently — resolver still\n    // returns a fallback to the caller.\n    return;\n  }\n  if (normalizeLocale(args.requestedLocale) === args.defaultLocale) {\n    return;\n  }\n\n  try {\n    const { enqueueTranslationJob } = await import('./translation-job.js');\n    await enqueueTranslationJob({\n      key: args.key,\n      targetLocale: args.requestedLocale,\n      sourceLocale: args.defaultLocale,\n      tenantId: args.options.tenantId ?? getTenantId() ?? null,\n      db: args.options.db,\n    });\n  } catch {\n    // Enqueueing must never break resolution.\n  }\n}\n\nexport function invalidateResolvedLanguageCache(\n  key: string,\n  locale: string,\n  tenantId: string | null | undefined,\n  db: unknown,\n): void {\n  invalidateLanguageCache(key, locale, tenantId, db);\n}\n","/**\n * @happyvertical/smrt-languages\n *\n * Code-first language strings with config + tenant overrides and AI-driven\n * auto-translation for SMRT applications. Mirrors the architecture of\n * `@happyvertical/smrt-prompts` plus a smrt-jobs handler that fills gaps in\n * non-default locales the first time a string is requested.\n *\n * The package root intentionally exposes only the read path\n * (`defineLanguageString`, `resolveLanguageString`, `LanguageOverride`, the\n * cache helpers, glossary helpers, and shared types/utilities). The\n * translation-worker stack — which depends on `@happyvertical/ai`,\n * smrt-jobs, smrt-features, and smrt-prompts — lives on the\n * `@happyvertical/smrt-languages/jobs` subpath, and the admin CLI helpers\n * live on `@happyvertical/smrt-languages/cli`. Resolver consumers (the vast\n * majority of call sites) never load the worker dependency tree.\n *\n * @packageDocumentation\n */\n\nimport './__smrt-register__.js';\n\nexport {\n  clearLanguageCache,\n  getLanguageCacheTtlMs,\n  invalidateLanguageCache,\n} from './cache.js';\nexport { LanguageOverrideCollection } from './collections/LanguageOverrideCollection.js';\nexport { buildTenantGlossary } from './glossary.js';\n\nexport {\n  defineLanguageString,\n  LanguageRegistry,\n} from './language-registry.js';\n\nexport {\n  invalidateResolvedLanguageCache,\n  resolveLanguageString,\n} from './language-resolver.js';\n\nexport {\n  LanguageOverride,\n  type LanguageOverrideCtorOptions,\n} from './models/LanguageOverride.js';\n\nexport type {\n  LanguageCacheValue,\n  LanguageOverrideOptions,\n  LanguageStringDefinition,\n  LanguageStringDefinitionInput,\n  LanguagesPackageConfig,\n  LanguageVariables,\n  ResolvedLanguageString,\n  ResolveLanguageStringOptions,\n} from './types.js';\n\nexport {\n  buildLocaleFallbackChain,\n  buildTranslationJobId,\n  computeSourceHash,\n  normalizeLocale,\n  renderTemplate,\n} from './utils.js';\n\n/** @internal */\nexport const PACKAGE_VERSION_INITIALIZED = true;\n"],"names":[],"mappings":";;;;;AAOA,eAAe;AAAA,EACb,IAAA,IAAA,mBAAA,YAAA,GAAA;AACF;ACYA,MAAM,iBAAiB;AAEvB,SAAS,qBAA6C;AACpD,SAAO,iBAAyC,aAAa;AAAA,IAC3D,eAAe;AAAA,IACf,WAAW,CAAA;AAAA,EAAC,CACb;AACH;AAQA,eAAe,qBACb,KACA,QACA,SACA,QAC4B;AAC5B,QAAM,WACJ,QAAQ,aAAa,SAAY,QAAQ,WAAY,iBAAiB;AAExE,MAAI,aAAgD;AACpD,MAAI,QAAQ,IAAI;AACd,iBAAa,MAAO,2BAAmC,OAAO;AAAA,MAC5D,IAAI,QAAQ;AAAA,IAAA,CACb;AAAA,EACH;AAEA,QAAM,UAAU,YAAY,MAAM,QAAQ;AAC1C,QAAM,SAAS,kBAAkB,KAAK,QAAQ,UAAU,OAAO;AAC/D,MAAI,QAAQ;AACV,WAAO;AAAA,MACL,UAAU,OAAO;AAAA,MACjB,QAAQ,OAAO;AAAA,MACf,oBAAoB,OAAO;AAAA,IAAA;AAAA,EAE/B;AAGA,MAAI,cAAc,UAAU;AAC1B,UAAM,iBAAiB,MAAM,WAAW;AAAA,MACtC;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAEF,QAAI,gBAAgB;AAClB,aAAO,SAAS;AAAA,QACd;AAAA,QACA;AAAA,QACA;AAAA,QACA,IAAI;AAAA,QACJ,SAAS;AAAA,UACP,UAAU,eAAe;AAAA,UACzB,QAAQ;AAAA,UACR,oBAAoB;AAAA,QAAA;AAAA,MACtB,CACD;AAAA,IACH;AAAA,EACF;AAGA,MAAI,YAAY;AACd,UAAM,cAAc,MAAM,WAAW,eAAe,KAAK,MAAM;AAC/D,QAAI,aAAa;AACf,aAAO,SAAS;AAAA,QACd;AAAA,QACA;AAAA,QACA;AAAA,QACA,IAAI;AAAA,QACJ,SAAS;AAAA,UACP,UAAU,YAAY;AAAA,UACtB,QAAQ;AAAA,UACR,oBAAoB;AAAA,QAAA;AAAA,MACtB,CACD;AAAA,IACH;AAAA,EACF;AAKA,QAAM,eAAe,OAAO,YAAY,GAAG;AAC3C,QAAM,iBAAiB,uBAAuB,cAAc,MAAM;AAClE,MAAI,OAAO,mBAAmB,UAAU;AACtC,WAAO,SAAS;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,MACA,IAAI;AAAA,MACJ,SAAS;AAAA,QACP,UAAU;AAAA,QACV,QAAQ;AAAA,QACR,oBAAoB;AAAA,MAAA;AAAA,IACtB,CACD;AAAA,EACH;AAGA,QAAM,aAAa,iBAAiB,IAAI,KAAK,MAAM;AACnD,MAAI,YAAY;AACd,WAAO,SAAS;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,MACA,IAAI;AAAA,MACJ,SAAS;AAAA,QACP,UAAU,WAAW;AAAA,QACrB,QAAQ;AAAA,QACR,oBAAoB;AAAA,MAAA;AAAA,IACtB,CACD;AAAA,EACH;AAEA,SAAO;AAAA,IACL,UAAU;AAAA,IACV,QAAQ;AAAA,IACR,oBAAoB;AAAA,EAAA;AAExB;AAEA,SAAS,uBACP,KACA,QACoB;AACpB,MAAI,CAAC,IAAK,QAAO;AAEjB,MAAI,OAAO,IAAI,MAAM,MAAM,SAAU,QAAO,IAAI,MAAM;AACtD,aAAW,CAAC,WAAW,QAAQ,KAAK,OAAO,QAAQ,GAAG,GAAG;AACvD,QAAI,gBAAgB,SAAS,MAAM,QAAQ;AACzC,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,SAAS,MAMI;AACpB,MAAI,KAAK,QAAQ,aAAa,MAAM;AAClC,UAAM,QAA4B;AAAA,MAChC,KAAK,KAAK;AAAA,MACV,QAAQ,KAAK;AAAA,MACb,UAAU,KAAK,QAAQ;AAAA,MACvB,QAAQ,KAAK,QAAQ;AAAA,MACrB,oBAAoB,KAAK,QAAQ;AAAA,IAAA;AAEnC,sBAAkB,KAAK,KAAK,KAAK,QAAQ,KAAK,UAAU,KAAK,IAAI,KAAK;AAAA,EACxE;AACA,SAAO,KAAK;AACd;AAEA,eAAsB,sBACpB,KACA,UAAwC,IACP;AACjC,MAAI,CAAC,OAAO,IAAI,KAAA,MAAW,IAAI;AAC7B,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AAEA,QAAM,SAAS,mBAAA;AACf,QAAM,gBAAgB,gBAAgB,OAAO,iBAAiB,cAAc;AAC5E,QAAM,YAAY,gBAAgB,QAAQ,UAAU,aAAa;AAGjE,MAAI,OAAO,QAAQ,WAAW,aAAa,UAAU;AACnD,WAAO;AAAA,MACL;AAAA,MACA,QAAQ;AAAA,MACR,UAAU,QAAQ,UAAU;AAAA,MAC5B,MAAM,eAAe,QAAQ,UAAU,UAAU,QAAQ,IAAI;AAAA,MAC7D,oBAAoB;AAAA,MACpB,QAAQ;AAAA,IAAA;AAAA,EAEZ;AAEA,QAAM,QAAQ,yBAAyB,WAAW,aAAa;AAE/D,MAAI,WAAqC;AACzC,MAAI,cAAc;AAClB,aAAW,UAAU,OAAO;AAC1B,UAAM,UAAU,MAAM,qBAAqB,KAAK,QAAQ,SAAS,MAAM;AACvE,QAAI,QAAQ,aAAa,MAAM;AAC7B,iBAAW;AACX,oBAAc;AACd;AAAA,IACF;AAAA,EACF;AAEA,MAAI,CAAC,UAAU;AACb,QAAI,QAAQ,QAAQ;AAClB,YAAM,IAAI;AAAA,QACR,oBAAoB,GAAG,mCAAmC,SAAS;AAAA,MAAA;AAAA,IAEvE;AAKA,UAAM,sBAAsB;AAAA,MAC1B;AAAA,MACA,iBAAiB;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AACD,WAAO;AAAA,MACL;AAAA,MACA,QAAQ;AAAA,MACR,UAAU;AAAA,MACV,MAAM;AAAA,MACN,oBAAoB;AAAA,MACpB,QAAQ;AAAA,IAAA;AAAA,EAEZ;AAIA,MAAI,gBAAgB,WAAW;AAC7B,UAAM,sBAAsB;AAAA,MAC1B;AAAA,MACA,iBAAiB;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AACD,WAAO;AAAA,MACL;AAAA,MACA,QAAQ;AAAA,MACR,UAAU,SAAS,YAAY;AAAA,MAC/B,MAAM,eAAe,SAAS,YAAY,KAAK,QAAQ,IAAI;AAAA,MAC3D,oBAAoB;AAAA,MACpB,QAAQ;AAAA,IAAA;AAAA,EAEZ;AAEA,SAAO;AAAA,IACL;AAAA,IACA,QAAQ;AAAA,IACR,UAAU,SAAS,YAAY;AAAA,IAC/B,MAAM,eAAe,SAAS,YAAY,KAAK,QAAQ,IAAI;AAAA,IAC3D,oBAAoB;AAAA,IACpB,QAAQ,SAAS;AAAA,EAAA;AAErB;AAUA,eAAe,sBAAsB,MAKnB;AAChB,MAAI,CAAC,KAAK,QAAQ,IAAI;AAGpB;AAAA,EACF;AACA,MAAI,gBAAgB,KAAK,eAAe,MAAM,KAAK,eAAe;AAChE;AAAA,EACF;AAEA,MAAI;AACF,UAAM,EAAE,sBAAA,IAA0B,MAAM,OAAO,sCAAsB;AACrE,UAAM,sBAAsB;AAAA,MAC1B,KAAK,KAAK;AAAA,MACV,cAAc,KAAK;AAAA,MACnB,cAAc,KAAK;AAAA,MACnB,UAAU,KAAK,QAAQ,YAAY,iBAAiB;AAAA,MACpD,IAAI,KAAK,QAAQ;AAAA,IAAA,CAClB;AAAA,EACH,QAAQ;AAAA,EAER;AACF;AAEO,SAAS,gCACd,KACA,QACA,UACA,IACM;AACN,0BAAwB,KAAK,QAAQ,UAAU,EAAE;AACnD;AC1PO,MAAM,8BAA8B;"}

package/dist/jobs.d.ts

@@ -0,0 +1,62 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+
+/** Feature flag key honored as the kill-switch for AI auto-translation. */
+export declare const AUTO_TRANSLATE_FEATURE_KEY = "smrt-languages.auto_translate";
+
+/**
+ * Enqueue a translation job for `(key, targetLocale)`, deduplicated against
+ * any already-pending job for the same target. Returns the (possibly existing)
+ * job's deterministic ID.
+ */
+export declare function enqueueTranslationJob(options: EnqueueTranslationOptions): Promise<{
+    id: string;
+    status: 'enqueued' | 'duplicate' | 'skipped';
+}>;
+
+declare interface EnqueueTranslationOptions {
+    key: string;
+    targetLocale: string;
+    sourceLocale?: string;
+    tenantId?: string | null;
+    db: unknown;
+    /** When true, skip the dedup check and force a fresh job. */
+    force?: boolean;
+}
+
+/**
+ * SmrtObject that owns the translation job's `execute` method. The TaskRunner
+ * resolves jobs by `objectType` so the registered class name needs to match
+ * what `enqueueTranslationJob` writes.
+ */
+export declare class LanguageTranslationTask extends SmrtObject {
+    /**
+     * Job-runner entrypoint. Reads the translation payload, calls
+     * `@happyvertical/ai`, and upserts a `LanguageOverride` row.
+     */
+    execute(args: TranslationJobPayload): Promise<{
+        skipped?: 'feature_disabled' | 'not_supported' | 'budget' | 'stale';
+        template?: string;
+    }>;
+}
+
+/**
+ * Prompt key registered with `smrt-prompts` so ops can tune the AI translation
+ * style without redeploying. The prompt itself is referenced by the job
+ * handler when calling `@happyvertical/ai`.
+ */
+export declare const TRANSLATION_PROMPT_KEY = "smrt-languages.translation";
+
+/** Payload pushed to the smrt-jobs translation handler. */
+export declare interface TranslationJobPayload {
+    key: string;
+    sourceLocale: string;
+    sourceTemplate: string;
+    sourceHash: string;
+    targetLocale: string;
+    tenantId?: string | null;
+    /** Optional model override; defaults to config / @happyvertical/ai default. */
+    model?: string;
+    [key: string]: unknown;
+}
+
+export { }

package/dist/jobs.js

@@ -0,0 +1,8 @@
+import { AUTO_TRANSLATE_FEATURE_KEY, LanguageTranslationTask, TRANSLATION_PROMPT_KEY, enqueueTranslationJob } from "./chunks/translation-job-DHg2E-eH.js";
+export {
+  AUTO_TRANSLATE_FEATURE_KEY,
+  LanguageTranslationTask,
+  TRANSLATION_PROMPT_KEY,
+  enqueueTranslationJob
+};
+//# sourceMappingURL=jobs.js.map

package/dist/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}