@happyvertical/smrt-languages

npm install @happyvertical/smrt-languages

import {
  defineLanguageString,
  resolveLanguageString,
  LanguageOverride,
  LanguageOverrideCollection,
  clearLanguageCache,
} from '@happyvertical/smrt-languages';

// 1. Register code defaults (typically at module load time)
defineLanguageString({
  key: 'users.role.member',
  locale: 'en',
  template: 'Member',
});

defineLanguageString({
  key: 'commerce.invoice.dueText',
  locale: 'en',
  template: 'Due by {{ date }}',
});

// 2. Resolve a string for the current tenant + locale
const text = await resolveLanguageString('users.role.member', {
  db,
  tenantId: 'tenant-a',
  locale: 'es',                // not registered — walks fallback chain
  vars: { name: 'Will' },
});
// First call: returns 'Member' with source: 'fallback'
// Async: enqueues translation job; result becomes app-level override
// Next call: returns the Spanish translation

Priority (low to high)
  1. Code default       defineLanguageString({ key, locale, template })
  2. File / config      package config 'languages' overrides
  3. App-level stored   LanguageOverride row with tenantId = null
  4. Tenant-level       LanguageOverride row with current tenant
  5. Runtime override   resolveLanguageString({ overrides })

If no row exists for the exact (key, locale, tenantId), fall through to:
  - Same key with the requested locale's fallback chain (fr-CA -> fr -> default)
  - Return the first hit with source: 'fallback'
  - Fire-and-forget AI translation job for the missing target

// When resolveLanguageString cannot find (key, locale, tenantId):

// 1. Walk locale fallback chain (buildLocaleFallbackChain)
//    fr-CA -> fr -> en (configured default)

// 2. Return the first hit immediately:
//    { text, source: 'fallback', resolvedFromLocale }

// 3. Fire-and-forget enqueueTranslationJob:
//    - Scoped to current tenant for glossary purposes
//    - Result is written app-level (tenantId: null) — reusable across tenants
//    - Job ID is deterministic, so concurrent misses collapse into one job

// 4. Subsequent requests hit the new app-level row at the requested locale.

// LanguageOverride model fields for the pipeline:
class LanguageOverride extends SmrtObject {
  key: string
  locale: string                  // BCP-47, normalized (lowercase lang / uppercase region)
  tenantId: string | null
  template: string
  auto_generated: boolean         // true if produced by translation worker
  source_hash: string | null      // sha256 of source template at translation time
  ai_model: string | null         // which model produced the translation
  reviewed_at: string | null      // ISO timestamp of admin review
  reviewed_by: string | null      // userId of reviewer (admin review queue)
  // Note: 'context' is inherited from SmrtObject and set in save() to
  // (tenantId ?? '__app__'); it backs the (key, locale, context) upsert key.
}