@contractspec/lib.contracts-spec 2.0.0

package/dist/translations/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Translation module for i18n contract system.
+ *
+ * Provides comprehensive types, registry, and validation for
+ * translatable content with support for pluralization, ICU message
+ * format, locale fallback, and context-aware translations.
+ *
+ * @module translations
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   defineTranslation,
+ *   TranslationRegistry,
+ *   validateTranslationSpec,
+ * } from '@contractspec/lib.contracts-spec';
+ *
+ * // Define a translation spec
+ * const messages = defineTranslation({
+ *   meta: {
+ *     key: 'payments.messages',
+ *     version: '1.0.0',
+ *     domain: 'payments',
+ *     owners: [{ team: 'payments' }],
+ *   },
+ *   locale: 'en',
+ *   messages: {
+ *     'payment.success': {
+ *       value: 'Payment completed successfully',
+ *       description: 'Shown after successful payment',
+ *     },
+ *   },
+ * });
+ *
+ * // Register and lookup
+ * const registry = new TranslationRegistry([messages]);
+ * const msg = registry.getMessage('payments.messages', 'payment.success', 'en');
+ * ```
+ */
+export * from './spec';
+export * from './registry';
+export * from './validation';
+export type { TranslationEntry, TranslationCatalogMeta, PlatformTranslationCatalog, BlueprintTranslationCatalog, } from './catalog';
+export * from './tenant';

package/dist/translations/index.js

@@ -0,0 +1,533 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+// src/translations/spec.ts
+var defineTranslation = (spec) => spec;
+
+// src/translations/registry.ts
+class TranslationRegistry {
+  specs = new Map;
+  latestByLocale = new Map;
+  locales = new Set;
+  domains = new Set;
+  constructor(items) {
+    if (items) {
+      for (const spec of items) {
+        this.register(spec);
+      }
+    }
+  }
+  register(spec) {
+    const fullKey = this.makeKey(spec.meta.key, spec.meta.version, spec.locale);
+    this.specs.set(fullKey, spec);
+    const localeKey = `${spec.meta.key}:${spec.locale}`;
+    const existing = this.latestByLocale.get(localeKey);
+    if (!existing || this.isNewerVersion(spec.meta.version, existing.meta.version)) {
+      this.latestByLocale.set(localeKey, spec);
+    }
+    this.locales.add(spec.locale);
+    this.domains.add(spec.meta.domain);
+  }
+  get(key, version, locale) {
+    return this.specs.get(this.makeKey(key, version, locale));
+  }
+  getLatest(key, locale) {
+    return this.latestByLocale.get(`${key}:${locale}`);
+  }
+  getMessage(specKey, messageKey, locale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (!spec)
+      return;
+    return spec.messages[messageKey];
+  }
+  getWithFallback(specKey, messageKey, locale, fallbackLocale, version) {
+    const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+    if (spec) {
+      const message = spec.messages[messageKey];
+      if (message) {
+        return { spec, message, locale, fromFallback: false };
+      }
+      fallbackLocale = fallbackLocale ?? spec.fallback;
+    }
+    if (fallbackLocale && fallbackLocale !== locale) {
+      const fallbackSpec = version ? this.get(specKey, version, fallbackLocale) : this.getLatest(specKey, fallbackLocale);
+      if (fallbackSpec) {
+        const message = fallbackSpec.messages[messageKey];
+        if (message) {
+          return {
+            spec: fallbackSpec,
+            message,
+            locale: fallbackLocale,
+            fromFallback: true
+          };
+        }
+      }
+    }
+    return;
+  }
+  getValue(specKey, messageKey, locale, fallback) {
+    const result = this.getWithFallback(specKey, messageKey, locale);
+    return result?.message.value ?? fallback ?? messageKey;
+  }
+  listLocales(specKey) {
+    const locales = [];
+    for (const [key, spec] of this.specs.entries()) {
+      if (key.startsWith(`${specKey}:`)) {
+        if (!locales.includes(spec.locale)) {
+          locales.push(spec.locale);
+        }
+      }
+    }
+    return locales;
+  }
+  list() {
+    return [...this.specs.values()];
+  }
+  listByLocale(locale) {
+    return [...this.specs.values()].filter((s) => s.locale === locale);
+  }
+  listByDomain(domain) {
+    return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+  }
+  has(key, locale, version) {
+    if (version) {
+      return this.specs.has(this.makeKey(key, version, locale));
+    }
+    return this.latestByLocale.has(`${key}:${locale}`);
+  }
+  getLocales() {
+    return this.locales;
+  }
+  getDomains() {
+    return this.domains;
+  }
+  getStats() {
+    let totalMessages = 0;
+    for (const spec of this.specs.values()) {
+      totalMessages += Object.keys(spec.messages).length;
+    }
+    return {
+      totalSpecs: this.specs.size,
+      locales: [...this.locales],
+      domains: [...this.domains],
+      totalMessages
+    };
+  }
+  clear() {
+    this.specs.clear();
+    this.latestByLocale.clear();
+    this.locales.clear();
+    this.domains.clear();
+  }
+  makeKey(key, version, locale) {
+    return `${key}:${version}:${locale}`;
+  }
+  isNewerVersion(a, b) {
+    const parseVersion = (v) => {
+      const parts = v.split(".").map(Number);
+      return {
+        major: parts[0] ?? 0,
+        minor: parts[1] ?? 0,
+        patch: parts[2] ?? 0
+      };
+    };
+    const va = parseVersion(a);
+    const vb = parseVersion(b);
+    if (va.major !== vb.major)
+      return va.major > vb.major;
+    if (va.minor !== vb.minor)
+      return va.minor > vb.minor;
+    return va.patch > vb.patch;
+  }
+}
+
+// src/translations/validation.ts
+function validateTranslationSpec(spec) {
+  const issues = [];
+  validateMeta(spec, issues);
+  validateLocale(spec, issues);
+  validateMessages(spec, issues);
+  validatePluralRules(spec, issues);
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+function validateMeta(spec, issues) {
+  const { meta } = spec;
+  if (!meta.key?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Translation spec must have a non-empty key",
+      path: "meta.key"
+    });
+  }
+  if (!meta.version?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Translation spec must have a non-empty version",
+      path: "meta.version"
+    });
+  }
+  if (!meta.domain?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Translation spec must have a non-empty domain",
+      path: "meta.domain"
+    });
+  }
+  if (!meta.owners?.length) {
+    issues.push({
+      level: "warning",
+      message: "Translation spec should specify owners",
+      path: "meta.owners"
+    });
+  }
+}
+function validateLocale(spec, issues) {
+  if (!spec.locale?.trim()) {
+    issues.push({
+      level: "error",
+      message: "Translation spec must specify a locale",
+      path: "locale"
+    });
+  } else if (!isValidLocaleFormat(spec.locale)) {
+    issues.push({
+      level: "warning",
+      message: `Locale "${spec.locale}" may not be a valid ISO 639-1 code`,
+      path: "locale"
+    });
+  }
+  if (spec.fallback && !isValidLocaleFormat(spec.fallback)) {
+    issues.push({
+      level: "warning",
+      message: `Fallback locale "${spec.fallback}" may not be a valid ISO 639-1 code`,
+      path: "fallback"
+    });
+  }
+  if (spec.fallback === spec.locale) {
+    issues.push({
+      level: "warning",
+      message: "Fallback locale is the same as primary locale",
+      path: "fallback"
+    });
+  }
+}
+function validateMessages(spec, issues) {
+  const { messages } = spec;
+  if (!messages || Object.keys(messages).length === 0) {
+    issues.push({
+      level: "warning",
+      message: "Translation spec has no messages",
+      path: "messages"
+    });
+    return;
+  }
+  for (const [key, message] of Object.entries(messages)) {
+    const path = `messages.${key}`;
+    if (!message.value?.trim()) {
+      issues.push({
+        level: "error",
+        message: `Message "${key}" has an empty value`,
+        path: `${path}.value`
+      });
+    }
+    const valueParams = extractPlaceholders(message.value);
+    const declaredPlaceholders = message.placeholders ?? [];
+    for (const placeholder of declaredPlaceholders) {
+      if (!valueParams.includes(placeholder.name)) {
+        issues.push({
+          level: "warning",
+          message: `Placeholder "${placeholder.name}" is defined but not used in message "${key}"`,
+          path: `${path}.placeholders`
+        });
+      }
+    }
+    if (message.placeholders !== undefined) {
+      for (const param of valueParams) {
+        const declared = declaredPlaceholders.find((p) => p.name === param);
+        if (!declared) {
+          issues.push({
+            level: "info",
+            message: `Placeholder "{${param}}" used in message "${key}" but not declared`,
+            path: `${path}.placeholders`
+          });
+        }
+      }
+    }
+    const icuResult = validateICUFormat(message.value);
+    if (!icuResult.valid) {
+      issues.push({
+        level: "error",
+        message: `Message "${key}" has invalid ICU format: ${icuResult.error}`,
+        path: `${path}.value`
+      });
+    }
+    if (message.variants?.length) {
+      const seenVariants = new Set;
+      for (const variant of message.variants) {
+        const variantKey = `${variant.type}:${variant.key}`;
+        if (seenVariants.has(variantKey)) {
+          issues.push({
+            level: "warning",
+            message: `Duplicate variant "${variantKey}" in message "${key}"`,
+            path: `${path}.variants`
+          });
+        }
+        seenVariants.add(variantKey);
+        if (!variant.value?.trim()) {
+          issues.push({
+            level: "error",
+            message: `Variant "${variantKey}" has an empty value in message "${key}"`,
+            path: `${path}.variants`
+          });
+        }
+      }
+    }
+    if (message.maxLength !== undefined) {
+      if (message.maxLength <= 0) {
+        issues.push({
+          level: "error",
+          message: `Message "${key}" has invalid maxLength (must be positive)`,
+          path: `${path}.maxLength`
+        });
+      } else if (message.value.length > message.maxLength) {
+        issues.push({
+          level: "warning",
+          message: `Message "${key}" value exceeds maxLength (${message.value.length} > ${message.maxLength})`,
+          path: `${path}.value`
+        });
+      }
+    }
+  }
+}
+function validatePluralRules(spec, issues) {
+  if (!spec.pluralRules?.length)
+    return;
+  for (let i = 0;i < spec.pluralRules.length; i++) {
+    const rule = spec.pluralRules[i];
+    if (!rule)
+      continue;
+    const path = `pluralRules[${i}]`;
+    if (!rule.variable?.trim()) {
+      issues.push({
+        level: "error",
+        message: "Plural rule must specify a variable name",
+        path: `${path}.variable`
+      });
+    }
+    if (!rule.rules?.length) {
+      issues.push({
+        level: "error",
+        message: "Plural rule must have at least one category",
+        path: `${path}.rules`
+      });
+    } else {
+      const hasOther = rule.rules.some((r) => r.category === "other");
+      if (!hasOther) {
+        issues.push({
+          level: "error",
+          message: `Plural rule "${rule.variable}" must have an "other" category`,
+          path: `${path}.rules`
+        });
+      }
+    }
+  }
+}
+function validateICUFormat(message) {
+  const placeholders = [];
+  const plurals = [];
+  const selects = [];
+  let braceDepth = 0;
+  let currentPlaceholder = "";
+  let inPlaceholder = false;
+  try {
+    for (let i = 0;i < message.length; i++) {
+      const char = message[i];
+      const prevChar = i > 0 ? message[i - 1] : "";
+      if (char === "'" && i + 1 < message.length) {
+        const nextChar = message[i + 1];
+        if (nextChar === "{" || nextChar === "}") {
+          i++;
+          continue;
+        }
+      }
+      if (char === "{") {
+        if (prevChar !== "'") {
+          braceDepth++;
+          if (braceDepth === 1) {
+            inPlaceholder = true;
+            currentPlaceholder = "";
+          }
+        }
+      } else if (char === "}") {
+        if (prevChar !== "'") {
+          braceDepth--;
+          if (braceDepth === 0 && inPlaceholder) {
+            const placeholder = currentPlaceholder.trim();
+            processPlaceholder(placeholder, placeholders, plurals, selects);
+            inPlaceholder = false;
+          }
+          if (braceDepth < 0) {
+            return {
+              valid: false,
+              error: "Unbalanced closing brace",
+              placeholders: [],
+              plurals: [],
+              selects: []
+            };
+          }
+        }
+      } else if (inPlaceholder) {
+        currentPlaceholder += char;
+      }
+    }
+    if (braceDepth !== 0) {
+      return {
+        valid: false,
+        error: "Unbalanced opening brace",
+        placeholders: [],
+        plurals: [],
+        selects: []
+      };
+    }
+    return {
+      valid: true,
+      placeholders,
+      plurals,
+      selects
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+      placeholders: [],
+      plurals: [],
+      selects: []
+    };
+  }
+}
+function processPlaceholder(placeholder, placeholders, plurals, selects) {
+  const parts = placeholder.split(",").map((p) => p.trim());
+  const name = parts[0];
+  const type = parts[1]?.toLowerCase();
+  if (name && !placeholders.includes(name)) {
+    placeholders.push(name);
+  }
+  if (type === "plural" || type === "selectordinal") {
+    if (name && !plurals.includes(name)) {
+      plurals.push(name);
+    }
+  } else if (type === "select") {
+    if (name && !selects.includes(name)) {
+      selects.push(name);
+    }
+  }
+}
+function findMissingTranslations(sourceSpec, targetSpec) {
+  const missing = [];
+  for (const [key, message] of Object.entries(sourceSpec.messages)) {
+    if (!targetSpec.messages[key]) {
+      missing.push({
+        messageKey: key,
+        sourceLocale: sourceSpec.locale,
+        targetLocale: targetSpec.locale,
+        sourceMessage: message
+      });
+    }
+  }
+  return missing;
+}
+function findAllMissingTranslations(registry, specKey, baseLocale) {
+  const result = new Map;
+  const baseSpec = registry.getLatest(specKey, baseLocale);
+  if (!baseSpec)
+    return result;
+  const locales = registry.listLocales(specKey);
+  for (const locale of locales) {
+    if (locale === baseLocale)
+      continue;
+    const targetSpec = registry.getLatest(specKey, locale);
+    if (targetSpec) {
+      const missing = findMissingTranslations(baseSpec, targetSpec);
+      if (missing.length > 0) {
+        result.set(locale, missing);
+      }
+    }
+  }
+  return result;
+}
+function validateTranslationRegistry(registry) {
+  const issues = [];
+  for (const spec of registry.list()) {
+    const specResult = validateTranslationSpec(spec);
+    issues.push(...specResult.issues.map((i) => ({
+      ...i,
+      path: `${spec.meta.key}.v${spec.meta.version}:${spec.locale}${i.path ? `.${i.path}` : ""}`
+    })));
+  }
+  return {
+    valid: issues.filter((i) => i.level === "error").length === 0,
+    issues
+  };
+}
+
+class TranslationValidationError extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.issues = issues;
+    this.name = "TranslationValidationError";
+  }
+}
+function assertTranslationSpecValid(spec) {
+  const result = validateTranslationSpec(spec);
+  if (!result.valid) {
+    throw new TranslationValidationError(`Translation ${spec.meta.key}.v${spec.meta.version}:${spec.locale} is invalid`, result.issues);
+  }
+}
+function isValidLocaleFormat(locale) {
+  return /^[a-z]{2}(-[A-Z]{2})?$/.test(locale);
+}
+function extractPlaceholders(value) {
+  const result = validateICUFormat(value);
+  return result.placeholders;
+}
+export {
+  validateTranslationSpec,
+  validateTranslationRegistry,
+  validateICUFormat,
+  findMissingTranslations,
+  findAllMissingTranslations,
+  defineTranslation,
+  assertTranslationSpecValid,
+  TranslationValidationError,
+  TranslationRegistry
+};