@happyvertical/smrt-languages 0.30.0

package/dist/smrt-knowledge.json

@@ -0,0 +1,343 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:12:26.327Z",
+  "packageName": "@happyvertical/smrt-languages",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "968f77b838ff801837e5f30a86bbbb51986650dda91319775662c35b296a7f1c",
+    "packageJson": "45ac17b9065adb17dbe98f73374dff00fcd1d27e033b43fd7d54c0697424a46c",
+    "agents": "6dc270bd9bb9c51d48f526396544ab2a54a071c42f60869f4806520818f7e864"
+  },
+  "exports": [
+    ".",
+    "./cli",
+    "./jobs",
+    "./manifest",
+    "./manifest.json"
+  ],
+  "dependencies": {
+    "@happyvertical/ai": "catalog:",
+    "@happyvertical/logger": "catalog:",
+    "@happyvertical/smrt-config": "workspace:*",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-features": "workspace:*",
+    "@happyvertical/smrt-jobs": "workspace:*",
+    "@happyvertical/smrt-prompts": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/smrt-cli": "workspace:*",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@types/node": "24.10.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-cli",
+    "@happyvertical/smrt-config",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-features",
+    "@happyvertical/smrt-jobs",
+    "@happyvertical/smrt-prompts",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/ai",
+    "@happyvertical/logger",
+    "@happyvertical/sql"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "LanguageTranslationTask",
+      "qualifiedName": "@happyvertical/smrt-languages:LanguageTranslationTask",
+      "collection": "languagetranslationtasks",
+      "tableName": "language_translation_tasks",
+      "packageName": "@happyvertical/smrt-languages",
+      "extends": "SmrtObject",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "execute"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LanguageOverrideCollection",
+      "qualifiedName": "@happyvertical/smrt-languages:LanguageOverrideCollection",
+      "collection": "languageoverrides",
+      "tableName": "_smrt_language_overrides",
+      "packageName": "@happyvertical/smrt-languages",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "getAppOverride",
+        "getResolutionLayers",
+        "getTenantOverride",
+        "listTenantOverrides",
+        "listUnreviewedAutoTranslations"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LanguageOverride",
+      "qualifiedName": "@happyvertical/smrt-languages:LanguageOverride",
+      "collection": "languageoverrides",
+      "tableName": "_smrt_language_overrides",
+      "packageName": "@happyvertical/smrt-languages",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "key",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "locale",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "template",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "auto_generated",
+          "type": "boolean",
+          "required": true,
+          "columnType": "BOOLEAN"
+        },
+        {
+          "name": "source_hash",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "ai_model",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewed_at",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "reviewed_by",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "approve",
+        "delete",
+        "save"
+      ],
+      "surfaces": [
+        {
+          "kind": "api",
+          "name": "languageoverrides.list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+          "path": "/languageoverrides",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "languageoverrides.get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+          "path": "/languageoverrides/[id]",
+          "method": "GET"
+        },
+        {
+          "kind": "api",
+          "name": "languageoverrides.create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+          "path": "/languageoverrides",
+          "method": "POST"
+        },
+        {
+          "kind": "api",
+          "name": "languageoverrides.update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+          "path": "/languageoverrides/[id]",
+          "method": "PATCH"
+        },
+        {
+          "kind": "api",
+          "name": "languageoverrides.delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+          "path": "/languageoverrides/[id]",
+          "method": "DELETE"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_create",
+          "operation": "create",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_update",
+          "operation": "update",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_delete",
+          "operation": "delete",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        },
+        {
+          "kind": "cli",
+          "name": "languageoverride_approve",
+          "operation": "approve",
+          "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "api",
+      "name": "languageoverrides.list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+      "path": "/languageoverrides",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "languageoverrides.get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+      "path": "/languageoverrides/[id]",
+      "method": "GET"
+    },
+    {
+      "kind": "api",
+      "name": "languageoverrides.create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+      "path": "/languageoverrides",
+      "method": "POST"
+    },
+    {
+      "kind": "api",
+      "name": "languageoverrides.update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+      "path": "/languageoverrides/[id]",
+      "method": "PATCH"
+    },
+    {
+      "kind": "api",
+      "name": "languageoverrides.delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride",
+      "path": "/languageoverrides/[id]",
+      "method": "DELETE"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_create",
+      "operation": "create",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_update",
+      "operation": "update",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_delete",
+      "operation": "delete",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    },
+    {
+      "kind": "cli",
+      "name": "languageoverride_approve",
+      "operation": "approve",
+      "objectName": "@happyvertical/smrt-languages:LanguageOverride"
+    }
+  ],
+  "prompts": [
+    {
+      "filePath": "src/translation-job.ts"
+    }
+  ],
+  "relationshipsV2": {
+    "foreignKeyFields": 0,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 3
+  },
+  "agentDoc": "# languages\n\nSMRT language string registry with file/config + tenant overrides and AI-driven\nauto-translation for missing locales.\n\n## Core pieces\n\n- `defineLanguageString({ key, locale, template })` registers a code default in\n  a global process registry. Same shape as `definePrompt` but keyed by\n  `(key, locale)` rather than `key` alone.\n- `resolveLanguageString(key, options)` walks the 5-layer chain (code → file\n  config → app override → tenant override → runtime override) and falls back\n  through the locale chain (`fr-CA` → `fr` → default) before giving up.\n- `LanguageOverride` stores app-level and tenant-level overrides in\n  `_smrt_language_overrides`. `auto_generated`, `source_hash`, `ai_model`,\n  `reviewed_at`, `reviewed_by` fields support the AI auto-translation pipeline\n  and admin review queue.\n- `enqueueTranslationJob({ key, targetLocale })` writes a `LanguageTranslationTask`\n  job into the `languages` queue with a deterministic dedup ID so concurrent\n  resolver misses collapse into one job.\n\n## Locale-miss flow\n\nWhen `resolveLanguageString` cannot find an exact `(key, locale, tenantId)`:\n\n1. Walk the locale fallback chain (`buildLocaleFallbackChain`).\n2. Return the first hit — same call returns immediately with\n   `source: 'fallback'`.\n3. Fire-and-forget `enqueueTranslationJob` for the missing target, scoped to\n   the current tenant for glossary purposes. App-level translations are\n   reusable across tenants, so the resulting `LanguageOverride` row is written\n   with `tenantId: null`.\n4. Subsequent requests hit the new app-level row and resolve at the requested\n   locale.\n\nThe translation job:\n\n- Honors the `smrt-languages.auto_translate` feature flag (kill switch).\n- Skips locales outside `supportedLocales` when configured.\n- Skips when `LanguageOverride` already exists with a matching `source_hash`\n  (re-translation is hash-gated, never time-based).\n- Never overwrites a row with `auto_generated: false` — human edits win\n  permanently.\n- Pulls the tenant's existing overrides and renders them as a glossary so\n  auto-translations match tenant voice.\n\n## Conventions\n\n- Keys are namespaced by package: `users.role.member`, `commerce.invoice.dueText`.\n- Locales follow BCP-47 (`en`, `fr-CA`, `pt-BR`) and are normalized to\n  lowercase-language / uppercase-region on persistence.\n- The translation prompt itself is registered with `smrt-prompts` under\n  `smrt-languages.translation` so ops can tune wording without redeploying.\n- `context` column on `_smrt_language_overrides` is set to `tenantId` or\n  `'__app__'` so the `(key, locale, context)` upsert key remains unique even\n  with nullable `tenantId`.\n\n## Public API surface\n\n```typescript\nimport {\n  defineLanguageString,\n  resolveLanguageString,\n  LanguageOverride,\n  LanguageOverrideCollection,\n  clearLanguageCache,\n} from '@happyvertical/smrt-languages';\n\ndefineLanguageString({\n  key: 'users.role.member',\n  locale: 'en',\n  template: 'Member',\n});\n\nconst text = await resolveLanguageString('users.role.member', {\n  db,\n  tenantId: 'tenant-a',\n  locale: 'es',\n  vars: { name: 'Will' },\n});\n```\n"
+}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+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 { }

package/dist/types.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@happyvertical/smrt-languages",
+  "version": "0.30.0",
+  "description": "Code-first language strings with config + tenant overrides and AI auto-translation for SMRT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jobs": {
+      "types": "./dist/jobs.d.ts",
+      "import": "./dist/jobs.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "dependencies": {
+    "@happyvertical/ai": "^0.74.7",
+    "@happyvertical/logger": "^0.74.7",
+    "@happyvertical/sql": "^0.74.7",
+    "@happyvertical/smrt-config": "0.30.0",
+    "@happyvertical/smrt-core": "0.30.0",
+    "@happyvertical/smrt-features": "0.30.0",
+    "@happyvertical/smrt-jobs": "0.30.0",
+    "@happyvertical/smrt-prompts": "0.30.0",
+    "@happyvertical/smrt-tenancy": "0.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17",
+    "@happyvertical/smrt-vitest": "0.30.0",
+    "@happyvertical/smrt-cli": "0.30.0"
+  },
+  "keywords": [
+    "smrt",
+    "languages",
+    "i18n",
+    "translation",
+    "ai",
+    "multi-tenancy"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/languages"
+  },
+  "scripts": {
+    "build": "vite build --mode library",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "vite dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}