@happyvertical/smrt-languages 0.51.32 → 0.51.34

package/dist/types.d.ts

@@ -1,111 +1,96 @@
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
-
-export declare interface LanguageCacheValue {
-    key: string;
-    locale: string;
-    template: string;
-    source: ResolvedLanguageString['source'];
-    resolvedFromLocale: string;
-}
-
-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;
-}
-
-/**
- * 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>;
-
-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 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;
-}
-
-/** 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 { }
-
-
-declare global {
-    var __smrtLanguageRegistry: Map<string, Map<string, LanguageStringDefinition>> | undefined;
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+/** A registered code default for a single (key, locale) pair. */
+export interface LanguageStringDefinitionInput {
+    key: string;
+    locale: string;
+    template: string;
 }
+export interface LanguageStringDefinition {
+    key: string;
+    locale: string;
+    template: string;
+    /** sha256 of the template at registration time, used for re-translation gating */
+    sourceHash: string;
+}
+/**
+ * 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 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 type LanguageVariables = Record<string, unknown>;
+export 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 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 interface LanguageCacheValue {
+    key: string;
+    locale: string;
+    template: string;
+    source: ResolvedLanguageString['source'];
+    resolvedFromLocale: string;
+}
+export 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;
+}
+/** Payload pushed to the smrt-jobs translation handler. */
+export 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils.d.ts

@@ -0,0 +1,40 @@
+import type { LanguageVariables } from './types.js';
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Stable hash used to gate auto-translation re-runs against a specific source. */
+export declare function computeSourceHash(template: string): string;
+/**
+ * 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;
+/**
+ * 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[];
+/**
+ * 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;
+/** Deterministic translation-job ID — used for stampede protection. */
+export declare function buildTranslationJobId(key: string, targetLocale: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElC;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,EAAE,CAwBV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,MAAM,CA2BR;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,GACnB,MAAM,CAER"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-languages",
-  "version": "0.51.32",
+  "version": "0.51.34",
   "description": "Code-first language strings with config + tenant overrides and AI auto-translation for SMRT",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,19 +29,19 @@
   "dependencies": {
     "@happyvertical/ai": "^0.94.1",
     "@happyvertical/logger": "^0.94.1",
-    "@happyvertical/smrt-config": "0.51.32",
-    "@happyvertical/smrt-core": "0.51.32",
-    "@happyvertical/smrt-features": "0.51.32",
-    "@happyvertical/smrt-jobs": "0.51.32",
-    "@happyvertical/smrt-prompts": "0.51.32",
-    "@happyvertical/smrt-tenancy": "0.51.32",
+    "@happyvertical/smrt-config": "0.51.34",
+    "@happyvertical/smrt-core": "0.51.34",
+    "@happyvertical/smrt-features": "0.51.34",
+    "@happyvertical/smrt-jobs": "0.51.34",
+    "@happyvertical/smrt-prompts": "0.51.34",
+    "@happyvertical/smrt-tenancy": "0.51.34",
     "@happyvertical/sql": "^0.94.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-cli": "0.51.32",
-    "@happyvertical/smrt-vitest": "0.51.32",
+    "@happyvertical/smrt-cli": "0.51.34",
+    "@happyvertical/smrt-vitest": "0.51.34",
     "@types/node": "24.13.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },