@contractspec/lib.contracts 1.49.0 → 1.51.0

package/dist/translations/registry.js

@@ -0,0 +1,223 @@
+//#region src/translations/registry.ts
+/**
+* Registry for translation specs with locale-aware lookup.
+*/
+var TranslationRegistry = class {
+	specs = /* @__PURE__ */ new Map();
+	latestByLocale = /* @__PURE__ */ new Map();
+	locales = /* @__PURE__ */ new Set();
+	domains = /* @__PURE__ */ new Set();
+	constructor(items) {
+		if (items) for (const spec of items) this.register(spec);
+	}
+	/**
+	* Register a translation spec.
+	*
+	* @param spec - Translation spec to register
+	*/
+	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 a translation spec by key, version, and locale.
+	*
+	* @param key - Translation spec key
+	* @param version - Version string
+	* @param locale - Locale code
+	* @returns Translation spec or undefined
+	*/
+	get(key, version, locale) {
+		return this.specs.get(this.makeKey(key, version, locale));
+	}
+	/**
+	* Get the latest version of a translation spec for a locale.
+	*
+	* @param key - Translation spec key
+	* @param locale - Locale code
+	* @returns Translation spec or undefined
+	*/
+	getLatest(key, locale) {
+		return this.latestByLocale.get(`${key}:${locale}`);
+	}
+	/**
+	* Get a specific message from a translation spec.
+	*
+	* @param specKey - Translation spec key
+	* @param messageKey - Message key within the spec
+	* @param locale - Locale code
+	* @param version - Optional version (uses latest if not specified)
+	* @returns Translation message or undefined
+	*/
+	getMessage(specKey, messageKey, locale, version) {
+		const spec = version ? this.get(specKey, version, locale) : this.getLatest(specKey, locale);
+		if (!spec) return void 0;
+		return spec.messages[messageKey];
+	}
+	/**
+	* Get a message value with fallback chain support.
+	*
+	* @param specKey - Translation spec key
+	* @param messageKey - Message key within the spec
+	* @param locale - Primary locale
+	* @param fallbackLocale - Fallback locale (optional, uses spec's fallback if not provided)
+	* @param version - Optional version (uses latest if not specified)
+	* @returns Translation lookup result or undefined
+	*/
+	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
+				};
+			}
+		}
+	}
+	/**
+	* Get a message value string with fallback.
+	*
+	* Convenience method that returns just the string value or a fallback.
+	*
+	* @param specKey - Translation spec key
+	* @param messageKey - Message key
+	* @param locale - Primary locale
+	* @param fallback - String to return if message not found (default: messageKey)
+	* @returns Message value or fallback
+	*/
+	getValue(specKey, messageKey, locale, fallback) {
+		return this.getWithFallback(specKey, messageKey, locale)?.message.value ?? fallback ?? messageKey;
+	}
+	/**
+	* List all locales available for a spec key.
+	*
+	* @param specKey - Translation spec key
+	* @returns Array of available locales
+	*/
+	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 all translation specs.
+	*
+	* @returns Array of all registered translation specs
+	*/
+	list() {
+		return [...this.specs.values()];
+	}
+	/**
+	* List translation specs by locale.
+	*
+	* @param locale - Locale to filter by
+	* @returns Array of translation specs for the locale
+	*/
+	listByLocale(locale) {
+		return [...this.specs.values()].filter((s) => s.locale === locale);
+	}
+	/**
+	* List translation specs by domain.
+	*
+	* @param domain - Domain to filter by
+	* @returns Array of translation specs for the domain
+	*/
+	listByDomain(domain) {
+		return [...this.specs.values()].filter((s) => s.meta.domain === domain);
+	}
+	/**
+	* Check if a translation spec exists.
+	*
+	* @param key - Translation spec key
+	* @param locale - Locale code
+	* @param version - Optional version
+	* @returns True if spec exists
+	*/
+	has(key, locale, version) {
+		if (version) return this.specs.has(this.makeKey(key, version, locale));
+		return this.latestByLocale.has(`${key}:${locale}`);
+	}
+	/**
+	* Get all registered locales.
+	*
+	* @returns Set of all registered locales
+	*/
+	getLocales() {
+		return this.locales;
+	}
+	/**
+	* Get all registered domains.
+	*
+	* @returns Set of all registered domains
+	*/
+	getDomains() {
+		return this.domains;
+	}
+	/**
+	* Get registry statistics.
+	*
+	* @returns Registry statistics
+	*/
+	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 all registered specs.
+	*/
+	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;
+	}
+};
+
+//#endregion
+export { TranslationRegistry };

package/dist/translations/spec.d.ts

@@ -0,0 +1,126 @@
+import { Owner, Stability, Tag } from "../ownership.js";
+
+//#region src/translations/spec.d.ts
+
+/** ISO 639-1 locale code (e.g., 'en', 'fr', 'de'). */
+type Locale = string;
+/** Message key identifier. */
+type MessageKey = string;
+type PlaceholderType = 'string' | 'number' | 'date' | 'time' | 'datetime' | 'currency' | 'percent' | 'plural' | 'select' | 'selectordinal';
+interface PlaceholderDef {
+  /** Placeholder name (without braces). */
+  name: string;
+  /** Type of the placeholder value. */
+  type: PlaceholderType;
+  /** Format specifier (e.g., 'short', 'long', 'currency'). */
+  format?: string;
+  /** Description for translators. */
+  description?: string;
+  /** Example value for context. */
+  example?: string;
+}
+/**
+ * CLDR plural categories.
+ * @see https://cldr.unicode.org/index/cldr-spec/plural-rules
+ */
+type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+interface PluralRule {
+  category: PluralCategory;
+  value: string;
+}
+interface PluralRuleSet {
+  /** Name of the plural variable. */
+  variable: string;
+  /** Rules for each plural category. */
+  rules: PluralRule[];
+}
+type VariantType = 'gender' | 'formality' | 'context';
+interface MessageVariant {
+  /** Type of variant (gender, formality, context). */
+  type: VariantType;
+  /** Variant key (e.g., 'male', 'female', 'formal', 'informal'). */
+  key: string;
+  /** Variant value (the translated message for this variant). */
+  value: string;
+}
+interface TranslationMessage {
+  /** The translated value (may use ICU message format). */
+  value: string;
+  /** Description for translators explaining context and usage. */
+  description?: string;
+  /** Usage context to help translators understand where this appears. */
+  context?: string;
+  /** Placeholder definitions for dynamic values. */
+  placeholders?: PlaceholderDef[];
+  /** Variants for gender, formality, or other contextual differences. */
+  variants?: MessageVariant[];
+  /** Maximum character length (hint for UI constraints). */
+  maxLength?: number;
+  /** Tags for categorization and filtering. */
+  tags?: string[];
+}
+type TranslationMessages = Record<MessageKey, TranslationMessage>;
+interface TranslationMeta {
+  /** Unique key for this translation spec. */
+  key: string;
+  /** Semantic version (e.g., "1.0.0"). */
+  version: string;
+  /** Business domain this translation belongs to. */
+  domain: string;
+  /** Description of the translation bundle. */
+  description?: string;
+  /** Owners responsible for this translation spec. */
+  owners: Owner[];
+  /** Stability marker. */
+  stability?: Stability;
+  /** Tags for categorization. */
+  tags?: Tag[];
+}
+interface TranslationSpec {
+  /** Metadata about this translation spec. */
+  meta: TranslationMeta;
+  /** Primary locale for this translation spec. */
+  locale: Locale;
+  /** Fallback locale when a message is missing. */
+  fallback?: Locale;
+  /** Translation messages keyed by message key. */
+  messages: TranslationMessages;
+  /** Plural rules for the locale. */
+  pluralRules?: PluralRuleSet[];
+  /** Tags for categorization. */
+  tags?: string[];
+}
+interface TranslationRef {
+  key: string;
+  version: string;
+  locale?: Locale;
+}
+/**
+ * Helper to define a Translation spec.
+ *
+ * @param spec - Translation specification
+ * @returns The same spec with type inference
+ *
+ * @example
+ * ```typescript
+ * const messages = defineTranslation({
+ *   meta: {
+ *     key: 'auth.messages',
+ *     version: '1.0.0',
+ *     domain: 'auth',
+ *     owners: [{ team: 'platform' }],
+ *   },
+ *   locale: 'en',
+ *   messages: {
+ *     'login.success': {
+ *       value: 'Welcome back, {name}!',
+ *       description: 'Shown after successful login',
+ *       placeholders: [{ name: 'name', type: 'string' }],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare const defineTranslation: (spec: TranslationSpec) => TranslationSpec;
+//#endregion
+export { Locale, MessageKey, MessageVariant, PlaceholderDef, PlaceholderType, PluralCategory, PluralRule, PluralRuleSet, TranslationMessage, TranslationMessages, TranslationMeta, TranslationRef, TranslationSpec, VariantType, defineTranslation };

package/dist/translations/spec.js

@@ -0,0 +1,31 @@
+//#region src/translations/spec.ts
+/**
+* Helper to define a Translation spec.
+*
+* @param spec - Translation specification
+* @returns The same spec with type inference
+*
+* @example
+* ```typescript
+* const messages = defineTranslation({
+*   meta: {
+*     key: 'auth.messages',
+*     version: '1.0.0',
+*     domain: 'auth',
+*     owners: [{ team: 'platform' }],
+*   },
+*   locale: 'en',
+*   messages: {
+*     'login.success': {
+*       value: 'Welcome back, {name}!',
+*       description: 'Shown after successful login',
+*       placeholders: [{ name: 'name', type: 'string' }],
+*     },
+*   },
+* });
+* ```
+*/
+const defineTranslation = (spec) => spec;
+
+//#endregion
+export { defineTranslation };

package/dist/translations/validation.d.ts

@@ -0,0 +1,85 @@
+import { Locale, MessageKey, TranslationMessage, TranslationSpec } from "./spec.js";
+import { TranslationRegistry } from "./registry.js";
+
+//#region src/translations/validation.d.ts
+
+type TranslationValidationLevel = 'error' | 'warning' | 'info';
+interface TranslationValidationIssue {
+  level: TranslationValidationLevel;
+  message: string;
+  path?: string;
+  context?: Record<string, unknown>;
+}
+interface TranslationValidationResult {
+  valid: boolean;
+  issues: TranslationValidationIssue[];
+}
+interface ICUValidationResult {
+  valid: boolean;
+  error?: string;
+  placeholders: string[];
+  plurals: string[];
+  selects: string[];
+}
+interface MissingTranslation {
+  messageKey: MessageKey;
+  sourceLocale: Locale;
+  targetLocale: Locale;
+  sourceMessage: TranslationMessage;
+}
+/**
+ * Validate a translation spec for internal consistency.
+ *
+ * @param spec - Translation spec to validate
+ * @returns Validation result with any issues found
+ */
+declare function validateTranslationSpec(spec: TranslationSpec): TranslationValidationResult;
+/**
+ * Validate ICU message format syntax.
+ *
+ * This is a simplified validator that checks for balanced braces
+ * and extracts placeholders, plurals, and selects.
+ *
+ * @param message - Message string to validate
+ * @returns Validation result with extracted components
+ */
+declare function validateICUFormat(message: string): ICUValidationResult;
+/**
+ * Find messages that exist in source but not in target.
+ *
+ * @param sourceSpec - Source translation spec (usually base locale like 'en')
+ * @param targetSpec - Target translation spec to check
+ * @returns Array of missing translations
+ */
+declare function findMissingTranslations(sourceSpec: TranslationSpec, targetSpec: TranslationSpec): MissingTranslation[];
+/**
+ * Find all missing translations across a registry.
+ *
+ * Compares each locale against a base locale to find missing keys.
+ *
+ * @param registry - Translation registry
+ * @param specKey - Translation spec key to check
+ * @param baseLocale - Base locale to compare against
+ * @returns Map of locale to missing translations
+ */
+declare function findAllMissingTranslations(registry: TranslationRegistry, specKey: string, baseLocale: Locale): Map<Locale, MissingTranslation[]>;
+/**
+ * Validate all translation specs in a registry.
+ *
+ * @param registry - Translation registry to validate
+ * @returns Validation result
+ */
+declare function validateTranslationRegistry(registry: TranslationRegistry): TranslationValidationResult;
+declare class TranslationValidationError extends Error {
+  readonly issues: TranslationValidationIssue[];
+  constructor(message: string, issues: TranslationValidationIssue[]);
+}
+/**
+ * Assert that a translation spec is valid, throwing if not.
+ *
+ * @param spec - Translation spec to validate
+ * @throws {TranslationValidationError} If validation fails
+ */
+declare function assertTranslationSpecValid(spec: TranslationSpec): void;
+//#endregion
+export { ICUValidationResult, MissingTranslation, TranslationValidationError, TranslationValidationIssue, TranslationValidationLevel, TranslationValidationResult, assertTranslationSpecValid, findAllMissingTranslations, findMissingTranslations, validateICUFormat, validateTranslationRegistry, validateTranslationSpec };