@digitaldefiance/i18n-lib 1.3.11 → 1.3.13

package/src/unified-translator.ts

@@ -0,0 +1,96 @@
+import { PluginI18nEngine } from './plugin-i18n-engine';
+import { I18nEngine } from './i18n-engine';
+
+interface PluginSource {
+  type: 'plugin';
+  engine: PluginI18nEngine<any>;
+  componentId: string;
+}
+
+interface LegacySource {
+  type: 'legacy';
+  engine: I18nEngine<any, any, any, any>;
+}
+
+type TranslationSource = PluginSource | LegacySource;
+
+/**
+ * Unified translator with explicit component/engine specification
+ */
+export class UnifiedTranslator<TLanguage extends string = string> {
+  private sources = new Map<string, TranslationSource>();
+  private defaultLanguage: TLanguage;
+  private defaultSource?: string;
+
+  constructor(defaultLanguage: TLanguage) {
+    this.defaultLanguage = defaultLanguage;
+  }
+
+  /**
+   * Register a plugin component
+   */
+  registerPlugin(
+    id: string,
+    engine: PluginI18nEngine<any>,
+    componentId: string,
+  ): void {
+    this.sources.set(id, { type: 'plugin', engine, componentId });
+    if (!this.defaultSource) this.defaultSource = id;
+  }
+
+  /**
+   * Register a legacy engine
+   */
+  registerLegacy(id: string, engine: I18nEngine<any, any, any, any>): void {
+    this.sources.set(id, { type: 'legacy', engine });
+    if (!this.defaultSource) this.defaultSource = id;
+  }
+
+  /**
+   * Set default source for unqualified keys
+   */
+  setDefaultSource(id: string): void {
+    if (!this.sources.has(id)) {
+      throw new Error(`Source '${id}' not registered`);
+    }
+    this.defaultSource = id;
+  }
+
+  /**
+   * Translate with explicit source: 'source:key' or just 'key' (uses default)
+   */
+  translate(
+    key: string,
+    vars?: Record<string, string | number>,
+    language?: TLanguage,
+  ): string {
+    const lang = language || this.defaultLanguage;
+    const [sourceName, actualKey] = key.includes(':') 
+      ? key.split(':', 2) 
+      : [this.defaultSource, key];
+
+    if (!sourceName) return `[${key}]`;
+    
+    const source = this.sources.get(sourceName);
+    if (!source) return `[${key}]`;
+
+    if (source.type === 'plugin') {
+      return source.engine.safeTranslate(source.componentId, actualKey, vars, lang);
+    } else {
+      return source.engine.safeTranslate(actualKey as any, vars, lang);
+    }
+  }
+
+  setLanguage(language: TLanguage): void {
+    this.defaultLanguage = language;
+  }
+
+  getLanguage(): TLanguage {
+    return this.defaultLanguage;
+  }
+
+  clearSources(): void {
+    this.sources.clear();
+    this.defaultSource = undefined;
+  }
+}

package/src/utils.ts

@@ -0,0 +1,213 @@
+import moment from 'moment-timezone';
+
+/**
+ * Replaces variables in a string with their corresponding values from vars or constants.
+ * @param str - The string containing variables to replace
+ * @param vars - An object mapping variable names to their replacement values
+ * @param constants - An object containing constant values for replacement
+ * @returns The string with variables replaced
+ */
+export function replaceVariables(
+  str: string,
+  vars?: Record<string, string | number>,
+  constants?: any,
+): string {
+  // Ensure input is a string
+  if (typeof str !== 'string') {
+    str = String(str);
+  }
+
+  const variables = str.match(/\{(.+?)\}/g);
+  if (!variables) return str;
+
+  let result = str;
+  for (const variable of variables) {
+    const varName = variable.slice(1, -1);
+    let replacement = '';
+
+    if (vars && varName in vars) {
+      replacement = String(vars[varName]);
+    } else if (constants && varName in constants) {
+      replacement = String(constants[varName]);
+    }
+
+    if (replacement) {
+      result = result.replace(variable, replacement);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Checks if a given key indicates a template string.
+ * @param key - The key to check
+ * @returns True if the key indicates a template, false otherwise
+ */
+export function isTemplate(key: string): boolean {
+  return key.trim().toLowerCase().endsWith('template');
+}
+
+/**
+ * Checks if a given timezone string is valid.
+ * @param timezone - The timezone string to validate
+ * @returns
+ */
+export function isValidTimezone(timezone: string): boolean {
+  return moment.tz.zone(timezone) !== null;
+}
+
+/**
+ * Converts parts to a single string key, joining with underscores.
+ * @param parts - The parts to join
+ * @returns The joined string key
+ */
+export function toStringKey<TStringKey extends string>(
+  ...parts: string[]
+): TStringKey {
+  return parts.join('_') as TStringKey;
+}
+
+/**
+ * Converts an enum value to a string key by joining parts with underscores and appending the enum value.
+ * @param value - The enum value
+ * @param parts - Additional parts to join
+ * @returns The constructed string key
+ */
+export function toStringKeyFromEnum<TStringKey extends string>(
+  value: string,
+  ...parts: string[]
+): TStringKey {
+  const allParts = [...parts, value];
+  return allParts.join('_') as TStringKey;
+}
+
+/**
+ * Type that constructs string keys from enum values with prefixes and optional template suffix
+ */
+type BuildStringKey<
+  TEnumValue extends string,
+  TPrefixes extends readonly string[],
+  TIsTemplate extends boolean = false,
+> = TPrefixes extends readonly []
+  ? `${TEnumValue}${TIsTemplate extends true ? 'Template' : ''}`
+  : TPrefixes extends readonly [infer First, ...infer Rest]
+  ? First extends string
+    ? Rest extends readonly string[]
+      ? `${First}_${BuildStringKey<TEnumValue, Rest, TIsTemplate>}`
+      : never
+    : never
+  : never;
+
+/**
+ * Type that maps all enum values to their corresponding string keys
+ */
+type ReasonMapFromEnum<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+  TPrefixes extends readonly string[] = [],
+  TTemplateKeys extends Set<TEnum[keyof TEnum]> = never,
+> = {
+  [K in TEnum[keyof TEnum]]: BuildStringKey<
+    K,
+    TPrefixes,
+    TTemplateKeys extends Set<K> ? true : false
+  > extends TStringKey
+    ? BuildStringKey<K, TPrefixes, TTemplateKeys extends Set<K> ? true : false>
+    : never;
+};
+
+/**
+ * Builds a reason map from an enum object, mapping each enum value to a string key.
+ * @param enumObj - The enum object
+ * @param prefixes - Prefixes to prepend to each string key
+ * @param templateKeys - Optional set of enum values that should have 'Template' suffix for template processing
+ * @returns The constructed reason map
+ */
+export function buildReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  prefixes: string[] = [],
+  templateKeys?: Set<TEnum[keyof TEnum]>,
+): Record<TEnum[keyof TEnum], TStringKey> {
+  const map = {} as Record<TEnum[keyof TEnum], TStringKey>;
+
+  Object.values(enumObj).forEach((value) => {
+    const baseKey = [...prefixes, value].join('_');
+    const finalKey = templateKeys?.has(value as TEnum[keyof TEnum])
+      ? baseKey + 'Template'
+      : baseKey;
+    map[value as TEnum[keyof TEnum]] = finalKey as TStringKey;
+  });
+
+  return map;
+}
+
+/**
+ * Type-safe version of buildReasonMap that ensures all enum values are mapped and all string keys exist
+ */
+export function buildTypeSafeReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+  TPrefixes extends readonly string[] = [],
+  TTemplateKeys extends Set<TEnum[keyof TEnum]> = never,
+>(
+  enumObj: TEnum,
+  prefixes: TPrefixes,
+  templateKeys?: TTemplateKeys,
+): ReasonMapFromEnum<TEnum, TStringKey, TPrefixes, TTemplateKeys> {
+  const map = {} as any;
+
+  Object.values(enumObj).forEach((value) => {
+    const baseKey = [...prefixes, value].join('_');
+    const finalKey = templateKeys?.has(value as TEnum[keyof TEnum])
+      ? baseKey + 'Template'
+      : baseKey;
+    map[value as TEnum[keyof TEnum]] = finalKey;
+  });
+
+  return map;
+}
+
+/**
+ * Validates that a reason map has entries for all enum values
+ */
+export function validateReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  reasonMap: Partial<Record<TEnum[keyof TEnum], TStringKey>>,
+): reasonMap is Record<TEnum[keyof TEnum], TStringKey> {
+  return Object.values(enumObj).every(
+    (value) =>
+      value in reasonMap &&
+      reasonMap[value as TEnum[keyof TEnum]] !== undefined,
+  );
+}
+
+/**
+ * Creates a complete reason map ensuring all enum values are covered
+ */
+export function createCompleteReasonMap<
+  TEnum extends Record<string, string>,
+  TStringKey extends string,
+>(
+  enumObj: TEnum,
+  prefixes: readonly string[] = [],
+  templateKeys?: Set<TEnum[keyof TEnum]>,
+): Record<TEnum[keyof TEnum], TStringKey> {
+  const map = buildReasonMap(enumObj, [...prefixes], templateKeys) as Record<
+    TEnum[keyof TEnum],
+    TStringKey
+  >;
+
+  if (!validateReasonMap(enumObj, map)) {
+    const missing = Object.values(enumObj).filter((value) => !(value in map));
+    throw new Error(`Missing reason map entries for: ${missing.join(', ')}`);
+  }
+
+  return map;
+}

package/src/validation-config.ts

@@ -0,0 +1,11 @@
+/**
+ * Configuration for component registration validation
+ */
+export interface ValidationConfig {
+  /** Whether to require all languages to have all strings */
+  readonly requireCompleteStrings: boolean;
+  /** Whether to allow registration with missing strings (will use fallbacks) */
+  readonly allowPartialRegistration: boolean;
+  /** Default language to fall back to for missing strings */
+  readonly fallbackLanguageId: string;
+}

package/src/validation-result.ts

@@ -0,0 +1,12 @@
+/**
+ * Validation result for component registration
+ */
+export interface ValidationResult {
+  readonly isValid: boolean;
+  readonly missingKeys: ReadonlyArray<{
+    readonly languageId: string;
+    readonly componentId: string;
+    readonly stringKey: string;
+  }>;
+  readonly errors: readonly string[];
+}

package/dist/active-context.d.ts

@@ -1,29 +0,0 @@
-import { CurrencyCode } from './currency-code';
-import { Timezone } from './timezone';
-import { LanguageContextSpace } from './types';
-export interface IActiveContext<TLanguage extends string> {
-    /**
-     * The default language for the user facing application
-     */
-    language: TLanguage;
-    /**
-     * The default language for the admin interface
-     */
-    adminLanguage: TLanguage;
-    /**
-     * The default currency code for the user facing application
-     */
-    currencyCode: CurrencyCode;
-    /**
-     * The default language context for the current context
-     */
-    currentContext: LanguageContextSpace;
-    /**
-     * The default timezone for the user facing application
-     */
-    timezone: Timezone;
-    /**
-     * The default timezone for the admin interface
-     */
-    adminTimezone: Timezone;
-}

package/dist/active-context.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component-definition.d.ts

@@ -1,11 +0,0 @@
-/**
- * Component definition with its string keys
- */
-export interface ComponentDefinition<TStringKeys extends string> {
-    /** Unique identifier for the component */
-    readonly id: string;
-    /** Human-readable name for the component */
-    readonly name: string;
-    /** Array of all string keys this component requires */
-    readonly stringKeys: readonly TStringKeys[];
-}

package/dist/component-definition.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component-registration.d.ts

@@ -1,9 +0,0 @@
-import { ComponentDefinition } from './component-definition';
-import { PartialComponentLanguageStrings } from './types';
-/**
- * Registration payload for a component with its strings
- */
-export interface ComponentRegistration<TStringKeys extends string, TLanguages extends string> {
-    readonly component: ComponentDefinition<TStringKeys>;
-    readonly strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>;
-}

package/dist/component-registration.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/component-registry.d.ts

@@ -1,68 +0,0 @@
-/**
- * Component registry for managing internationalization components and their string translations
- */
-import { ComponentDefinition } from './component-definition';
-import { ComponentRegistration } from './component-registration';
-import { TranslationRequest } from './translation-request';
-import { TranslationResponse } from './translation-response';
-import { ComponentLanguageStrings, PartialComponentLanguageStrings } from './types';
-import { ValidationConfig } from './validation-config';
-import { ValidationResult } from './validation-result';
-/**
- * Registry for managing components and their translations
- */
-export declare class ComponentRegistry<TLanguages extends string> {
-    private readonly components;
-    private readonly componentStrings;
-    private readonly validationConfig;
-    private readonly registeredLanguages;
-    constructor(languages: readonly TLanguages[], validationConfig: ValidationConfig);
-    /**
-     * Update the set of registered languages (for dynamic language addition)
-     */
-    updateRegisteredLanguages(languages: readonly TLanguages[]): void;
-    /**
-     * Register a new component with its translations
-     */
-    registerComponent<TStringKeys extends string>(registration: ComponentRegistration<TStringKeys, TLanguages>): ValidationResult;
-    /**
-     * Update strings for an existing component
-     */
-    updateComponentStrings<TStringKeys extends string>(componentId: string, strings: PartialComponentLanguageStrings<TStringKeys, TLanguages>): ValidationResult;
-    /**
-     * Get a translation for a specific component, string key, and language
-     */
-    getTranslation<TStringKeys extends string>(request: TranslationRequest<TStringKeys, TLanguages>): TranslationResponse;
-    /**
-     * Get all registered components
-     */
-    getComponents(): ReadonlyArray<ComponentDefinition<any>>;
-    /**
-     * Get a specific component by ID
-     */
-    getComponent<TStringKeys extends string>(componentId: string): ComponentDefinition<TStringKeys> | undefined;
-    /**
-     * Check if a component is registered
-     */
-    hasComponent(componentId: string): boolean;
-    /**
-     * Get all strings for a component in all languages
-     */
-    getComponentStrings<TStringKeys extends string>(componentId: string): ComponentLanguageStrings<TStringKeys, TLanguages> | undefined;
-    /**
-     * Validate a component registration
-     */
-    private validateComponentRegistration;
-    /**
-     * Complete missing strings with fallbacks
-     */
-    private completeStringsWithFallbacks;
-    /**
-     * Merge existing strings with new strings
-     */
-    private mergeStrings;
-    /**
-     * Clear all components and their strings (useful for testing)
-     */
-    clearAllComponents(): void;
-}