@digitaldefiance/i18n-lib 3.7.5 → 3.8.1

package/src/{index.d.ts → index.ts}

@@ -1,24 +1,44 @@
+// V2 Exports (primary)
 export * from './builders';
 export * from './core';
 export * from './errors';
+export * from './gender';
 export * from './interfaces';
-export * from './utils';
-export * from './types';
 export * from './pluralization';
-export * from './gender';
+export * from './types';
+export * from './utils';
 export * from './validation';
-export { Timezone, isValidTimezone } from './utils/timezone';
-export { CurrencyCode, getCurrencyFormat } from './utils/currency';
-export type { CurrencyData, CurrencyFormat, CurrencyPosition } from './utils/currency';
-export { createPluralString, createGenderedString } from './utils/plural-helpers';
-export type { PluralString } from './types/plural-types';
+
+// Explicit exports for type safety
 export type { GenderedString } from './gender/gender-categories';
-export { I18nEngine as I18n } from './core/i18n-engine';
+export type { PluralString } from './types/plural-types';
+export { CurrencyCode, getCurrencyFormat } from './utils/currency';
+export type {
+  CurrencyData,
+  CurrencyFormat,
+  CurrencyPosition,
+} from './utils/currency';
+export {
+  createGenderedString,
+  createPluralString,
+} from './utils/plural-helpers';
+export { isValidTimezone, Timezone } from './utils/timezone';
+
+// Convenience aliases
 export { I18nBuilder as Builder } from './builders/i18n-builder';
-export declare function resetAll(): void;
+export { I18nEngine as I18n } from './core/i18n-engine';
+
+// Reset utility
+import { I18nEngine } from './core/i18n-engine';
+export function resetAll(): void {
+  I18nEngine.resetAll();
+}
+
+// Legacy exports (deprecated - for backwards compatibility)
 export * from './active-context';
 export * from './component-definition';
 export * from './global-active-context';
+// export * from './language-registry'; // Removed - conflicts with v2 core/language-registry
 export * from './component-registration';
 export * from './component-registry';
 export * from './context-error-type';
@@ -39,8 +59,20 @@ export * from './translation-request';
 export * from './translation-response';
 export * from './types';
 export * from './validation-config';
-export { createCorePluginI18nEngine as createCoreI18n, createCorePluginI18nEngine as createCoreI18nEngine } from './core-i18n';
-export { getCorePluginTranslation as getCoreTranslation, safeCorePluginTranslation as safeCoreTranslation } from './core-i18n';
+
+// Legacy convenience exports
+export {
+  createCorePluginI18nEngine as createCoreI18n,
+  createCorePluginI18nEngine as createCoreI18nEngine,
+  getCorePluginTranslation as getCoreTranslation,
+  safeCorePluginTranslation as safeCoreTranslation,
+} from './core-plugin-factory';
+// Export core plugin factory functions
+export * from './core-plugin-factory';
 export { PluginI18nEngine as PluginI18n } from './plugin-i18n-engine';
-export declare function resetAllI18nEngines(): void;
-//# sourceMappingURL=index.d.ts.map
+
+// Legacy testing utilities
+import { PluginI18nEngine } from './plugin-i18n-engine';
+export function resetAllI18nEngines(): void {
+  PluginI18nEngine.resetAll();
+}

package/src/interfaces/active-context.interface.ts

@@ -0,0 +1,41 @@
+import type { LanguageContextSpace } from '../types';
+import type { CurrencyCode } from '../utils/currency';
+import type { Timezone } from '../utils/timezone';
+
+/**
+ * Represents the active internationalization context for user and admin interfaces,
+ * including language, currency, and timezone settings.
+ *
+ * @template TLanguage The type of language codes (e.g., 'en-US', 'fr').
+ */
+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 current language context space (e.g., 'user' or 'admin').
+   */
+  currentContext: LanguageContextSpace;
+
+  /**
+   * The default timezone for the user-facing application.
+   */
+  timezone: Timezone;
+
+  /**
+   * The default timezone for the admin interface.
+   */
+  adminTimezone: Timezone;
+}

package/src/interfaces/component-config.interface.ts

@@ -0,0 +1,17 @@
+/**
+ * Simplified component configuration
+ */
+
+import { PluralString } from '../types/plural-types';
+
+/**
+ * Configuration for registering a component with the i18n system.
+ */
+export interface ComponentConfig {
+  /** Unique identifier for the component */
+  readonly id: string;
+  /** Translation strings organized by language and key */
+  readonly strings: Record<string, Record<string, string | PluralString>>;
+  /** Optional alternative names for referencing this component */
+  readonly aliases?: readonly string[];
+}

package/src/interfaces/engine-config.interface.ts

@@ -0,0 +1,22 @@
+/**
+ * Engine configuration interface
+ */
+
+/**
+ * Configuration options for the I18n engine.
+ */
+export interface EngineConfig {
+  /** Default language to use when none is specified */
+  defaultLanguage?: string;
+  /** Fallback language to use when a translation is missing */
+  fallbackLanguage?: string;
+  /** Constants available for variable replacement in templates */
+  constants?: Record<string, any>;
+  /** Validation configuration */
+  validation?: {
+    /** Whether all string keys must be provided for all languages */
+    requireCompleteStrings?: boolean;
+    /** Whether to allow component registration with missing translations */
+    allowPartialRegistration?: boolean;
+  };
+}

package/src/interfaces/global-active-context.ts

@@ -0,0 +1,39 @@
+import type { LanguageContextSpace } from '../types';
+import type { CurrencyCode } from '../utils/currency';
+import type { Timezone } from '../utils/timezone';
+import type { IActiveContext } from './active-context.interface';
+
+export interface IGlobalActiveContext<
+  TLanguage extends string,
+  TActiveContext extends IActiveContext<TLanguage>,
+> {
+  context: TActiveContext;
+  userLanguage: TLanguage;
+  currencyCode: CurrencyCode;
+  adminLanguage: TLanguage;
+  languageContextSpace: LanguageContextSpace;
+  userTimezone: Timezone;
+  adminTimezone: Timezone;
+
+  createContext(
+    defaultLanguage: TLanguage,
+    defaultAdminLanguage?: TLanguage,
+    key?: string,
+  ): TActiveContext;
+
+  getContext(key?: string): TActiveContext;
+
+  setUserLanguage(language: TLanguage, key?: string): void;
+
+  setCurrencyCode(code: CurrencyCode, key?: string): void;
+
+  setAdminLanguage(language: TLanguage, key?: string): void;
+
+  setLanguageContextSpace(context: LanguageContextSpace, key?: string): void;
+
+  getLanguageContextSpace(key?: string): LanguageContextSpace;
+
+  setUserTimezone(tz: Timezone, key?: string): void;
+
+  setAdminTimezone(tz: Timezone, key?: string): void;
+}

package/src/interfaces/handleable-error-options.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for creating a HandleableError.
+ */
+export interface HandleableErrorOptions {
+  /** The original error that caused this error */
+  cause?: Error;
+  /** Whether this error has been handled */
+  handled?: boolean;
+  /** HTTP status code associated with this error */
+  statusCode?: number;
+  /** Optional source data related to the error */
+  sourceData?: unknown;
+}

package/src/interfaces/handleable.ts

@@ -0,0 +1,20 @@
+/**
+ * Interface for errors that can be marked as handled and serialized to JSON.
+ */
+export interface IHandleable {
+  /**
+   * Converts the error to a JSON-serializable object.
+   * @returns A plain object representation of the error
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Gets the handled state of this error.
+   * @returns True if the error has been handled, false otherwise
+   */
+  get handled(): boolean;
+  /**
+   * Sets the handled state of this error.
+   * @param value - The new handled state
+   */
+  set handled(value: boolean);
+}

package/src/interfaces/i18n-engine.interface.ts

@@ -0,0 +1,57 @@
+/**
+ * Core I18n Engine interface
+ */
+
+import { ComponentConfig } from './component-config.interface';
+import { LanguageDefinition } from './language-definition.interface';
+import { TranslationOptions } from './translation-options.interface';
+import { ValidationResult } from './validation-result.interface';
+
+/**
+ * Main interface for the I18n engine, defining all translation and management operations.
+ */
+export interface II18nEngine {
+  // Component management
+  /** Registers a new component with its translations */
+  register(config: ComponentConfig): ValidationResult;
+  /** Registers a component only if it doesn't already exist */
+  registerIfNotExists(config: ComponentConfig): ValidationResult;
+  /** Updates strings for an existing component */
+  updateStrings(componentId: string, strings: Record<string, Record<string, string>>): ValidationResult;
+  /** Checks if a component is registered */
+  hasComponent(componentId: string): boolean;
+  /** Gets all registered components */
+  getComponents(): readonly ComponentConfig[];
+
+  // Translation
+  /** Translates a string key for a component */
+  translate(componentId: string, key: string, variables?: Record<string, any>, language?: string): string;
+  /** Safely translates a string key, returning a fallback on error */
+  safeTranslate(componentId: string, key: string, variables?: Record<string, any>, language?: string): string;
+  /** Template processor that handles embedded component.key patterns */
+  t(template: string, variables?: Record<string, any>, language?: string): string;
+
+  // Language management
+  /** Registers a new language */
+  registerLanguage(language: LanguageDefinition): void;
+  /** Sets the current user-facing language */
+  setLanguage(language: string): void;
+  /** Sets the administrative language */
+  setAdminLanguage(language: string): void;
+  /** Gets all registered languages */
+  getLanguages(): readonly LanguageDefinition[];
+  /** Checks if a language is registered */
+  hasLanguage(language: string): boolean;
+
+  // Context management
+  /** Switches to admin context */
+  switchToAdmin(): void;
+  /** Switches to user context */
+  switchToUser(): void;
+  /** Gets the currently active language based on context */
+  getCurrentLanguage(): string;
+
+  // Validation
+  /** Validates all registered components */
+  validate(): ValidationResult;
+}

package/src/interfaces/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Interface exports
+ * Using type-only exports to prevent runtime circular dependencies
+ */
+
+export type * from './active-context.interface';
+export type * from './component-config.interface';
+export type * from './engine-config.interface';
+export type * from './global-active-context';
+export type * from './i18n-engine.interface';
+export type * from './language-definition.interface';
+export type * from './translation-options.interface';
+export type * from './validation-result.interface';

package/src/interfaces/language-definition.interface.ts

@@ -0,0 +1,17 @@
+/**
+ * Language definition interface
+ */
+
+/**
+ * Defines a language with its metadata.
+ */
+export interface LanguageDefinition {
+  /** Unique identifier for the language (e.g., 'en-US') */
+  readonly id: string;
+  /** Display name in the native language */
+  readonly name: string;
+  /** ISO language code */
+  readonly code: string;
+  /** Whether this is the default/fallback language */
+  readonly isDefault?: boolean;
+}

package/src/interfaces/translation-options.interface.ts

@@ -0,0 +1,15 @@
+/**
+ * Translation options interface
+ */
+
+/**
+ * Options that can be passed when requesting a translation.
+ */
+export interface TranslationOptions {
+  /** Variables to replace in template strings */
+  readonly variables?: Record<string, any>;
+  /** Language code to use for the translation */
+  readonly language?: string;
+  /** Fallback value to return if translation fails */
+  readonly fallback?: string;
+}

package/src/interfaces/validation-result.interface.ts

@@ -0,0 +1,24 @@
+/**
+ * Validation result interface
+ */
+
+/**
+ * Result of validating a component registration or the entire engine.
+ */
+export interface ValidationResult {
+  /** Whether the validation passed */
+  readonly isValid: boolean;
+  /** Array of validation errors */
+  readonly errors: readonly string[];
+  /** Array of validation warnings */
+  readonly warnings: readonly string[];
+  /** Detailed information about missing translation keys */
+  readonly missingKeys?: readonly {
+    /** The language ID where the key is missing */
+    languageId: string;
+    /** The component ID where the key is missing */
+    componentId: string;
+    /** The string key that is missing */
+    stringKey: string;
+  }[];
+}

package/src/language-codes.ts

@@ -0,0 +1,40 @@
+/**
+ * Common language codes following BCP 47 standard.
+ * These are provided as constants for convenience, but any string can be used as a language code.
+ * Site builders can use these or define their own custom language codes.
+ */
+export const LanguageCodes = {
+  EN_US: 'en-US',
+  EN_GB: 'en-GB',
+  FR: 'fr',
+  ES: 'es',
+  DE: 'de',
+  ZH_CN: 'zh-CN',
+  JA: 'ja',
+  UK: 'uk',
+} as const;
+
+/**
+ * Type representing any language code (string)
+ */
+export type LanguageCode = string;
+
+/**
+ * Type representing the common language codes provided by this library
+ */
+export type CommonLanguageCode =
+  (typeof LanguageCodes)[keyof typeof LanguageCodes];
+
+/**
+ * Helper to get display names for common language codes
+ */
+export const LanguageDisplayNames: Record<CommonLanguageCode, string> = {
+  [LanguageCodes.EN_US]: 'English (US)',
+  [LanguageCodes.EN_GB]: 'English (UK)',
+  [LanguageCodes.FR]: 'Français',
+  [LanguageCodes.ES]: 'Español',
+  [LanguageCodes.DE]: 'Deutsch',
+  [LanguageCodes.ZH_CN]: '中文',
+  [LanguageCodes.JA]: '日本語',
+  [LanguageCodes.UK]: 'Українська',
+};

package/src/language-definition.ts

@@ -0,0 +1,13 @@
+/**
+ * Language definition with its properties
+ */
+export interface LanguageDefinition {
+  /** Unique identifier for the language */
+  readonly id: string;
+  /** Display name in the native language */
+  readonly name: string;
+  /** ISO language code (e.g., 'en', 'fr', 'zh-CN') */
+  readonly code: string;
+  /** Whether this is the fallback/default language */
+  readonly isDefault?: boolean;
+}