@digitaldefiance/i18n-lib 1.3.11 → 1.3.13

package/src/create-translation-adapter.ts

@@ -0,0 +1,47 @@
+import { PluginI18nEngine } from './plugin-i18n-engine';
+import { TranslationEngine } from './translation-engine';
+
+/**
+ * Creates a TranslationEngine adapter from a PluginI18nEngine for a specific component.
+ * This allows PluginI18nEngine to be used where TranslationEngine interface is expected.
+ * 
+ * @param pluginEngine - The PluginI18nEngine instance to wrap
+ * @param componentId - The component ID to use for translations
+ * @returns A TranslationEngine that delegates to the PluginI18nEngine
+ * 
+ * @example
+ * ```typescript
+ * const pluginEngine = getMyPluginI18nEngine();
+ * const adapter = createTranslationAdapter(pluginEngine, 'my-component');
+ * 
+ * // Now can be used where TranslationEngine is expected
+ * const error = new MyError(errorType, adapter);
+ * ```
+ */
+export function createTranslationAdapter<TStringKey extends string, TLanguage extends string>(
+  pluginEngine: PluginI18nEngine<TLanguage>,
+  componentId: string,
+): TranslationEngine<TStringKey> {
+  return {
+    translate: (
+      key: TStringKey,
+      vars?: Record<string, string | number>,
+      lang?: TLanguage,
+    ): string => {
+      try {
+        return pluginEngine.translate(componentId, key, vars, lang);
+      } catch (error) {
+        // Fallback to key if translation fails
+        return String(key);
+      }
+    },
+    
+    safeTranslate: (
+      key: TStringKey,
+      vars?: Record<string, string | number>,
+      lang?: TLanguage,
+    ): string => {
+      return pluginEngine.safeTranslate(componentId, key, vars, lang);
+    },
+  };
+}

package/src/currency-code.ts

@@ -0,0 +1,35 @@
+import { codes } from 'currency-codes';
+import { DefaultCurrencyCode } from './types';
+
+/**
+ * Class representing a validated currency code.
+ */
+export class CurrencyCode {
+  private _value: string = DefaultCurrencyCode;
+  /**
+   * Gets the currency code value.
+   */
+  public get value(): string {
+    return this._value;
+  }
+  /**
+   * Sets the currency code value after validating it.
+   */
+  public set value(value: string) {
+    if (!CurrencyCode.values.includes(value)) {
+      throw new Error('Invalid currency code');
+    }
+    this._value = value;
+  }
+
+  /**
+   * Gets the list of all valid currency codes.
+   */
+  public static get values(): string[] {
+    return codes();
+  }
+
+  constructor(value: string = DefaultCurrencyCode) {
+    this.value = value;
+  }
+}

package/{dist/currency-format.d.ts → src/currency-format.ts}

@@ -1,10 +1,11 @@
 import { CurrencyPosition } from './types';
+
 /**
  * Represents the format details for a specific currency in a given locale.
  */
 export interface CurrencyFormat {
-    symbol: string;
-    position: CurrencyPosition;
-    groupSeparator: string;
-    decimalSeparator: string;
+  symbol: string;
+  position: CurrencyPosition;
+  groupSeparator: string;
+  decimalSeparator: string;
 }

package/src/currency.ts

@@ -0,0 +1,52 @@
+/**
+ * Currency formatting utilities
+ */
+
+import { CurrencyFormat } from './currency-format';
+import { CurrencyPosition } from './types';
+
+/**
+ * Get currency format details for a given locale and currency code.
+ * @param locale The locale string (e.g., 'en-US')
+ * @param currencyCode The ISO 4217 currency code (e.g., 'USD')
+ * @returns The currency format details
+ */
+export function getCurrencyFormat(
+  locale: string,
+  currencyCode: string,
+): CurrencyFormat {
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: currencyCode,
+  });
+
+  const parts = formatter.formatToParts(1234567.89);
+  const symbol = parts.find((part) => part.type === 'currency')?.value || '';
+  const symbolIndex = parts.findIndex((part) => part.type === 'currency');
+  const decimalIndex = parts.findIndex((part) => part.type === 'decimal');
+  const integerIndex = parts.findIndex((part) => part.type === 'integer');
+
+  let position: CurrencyPosition;
+  if (decimalIndex === -1) {
+    // No decimal separator
+    if (symbolIndex < integerIndex) {
+      position = 'prefix';
+    } else {
+      position = 'postfix';
+    }
+  } else if (symbolIndex < decimalIndex && symbolIndex < integerIndex) {
+    position = 'prefix';
+  } else if (symbolIndex > decimalIndex) {
+    position = 'postfix';
+  } else {
+    position = 'infix';
+  }
+
+  return {
+    symbol,
+    position,
+    groupSeparator: parts.find((part) => part.type === 'group')?.value || ',',
+    decimalSeparator:
+      parts.find((part) => part.type === 'decimal')?.value || '.',
+  };
+}

package/src/default-config.ts

@@ -0,0 +1,199 @@
+import { CurrencyCode } from './currency-code';
+import { I18nConfig } from './i18n-config';
+import { I18nContext } from './i18n-context';
+import { I18nEngine } from './i18n-engine';
+import { LanguageCodes } from './language-codes';
+import { Timezone } from './timezone';
+import {
+  DefaultCurrencyCode,
+  LanguageCodeCollection,
+  LanguageContextSpace,
+} from './types';
+
+// Default enum types that can be augmented by consumers
+export enum DefaultStringKey {
+  Common_Test = 'common_test',
+  Error_InstanceAlreadyExistsTemplate = 'error_instanceAlreadyExistsTemplate',
+  Error_InstanceNotFoundTemplate = 'error_instanceNotFoundTemplate',
+  Error_MissingStringCollectionTemplate = 'error_missingStringCollectionTemplate',
+  Error_MissingTranslationTemplate = 'error_missingTranslationTemplate',
+  Error_DefaultLanguageNoCollectionTemplate = 'error_defaultLanguageNoCollectionTemplate',
+  Error_MissingTranslationKeyTemplate = 'error_missingTranslationKeyTemplate',
+}
+
+// Default language codes used by the library
+export type DefaultLanguageCode = 
+  | typeof LanguageCodes.EN_US
+  | typeof LanguageCodes.EN_GB
+  | typeof LanguageCodes.FR
+  | typeof LanguageCodes.ES
+  | typeof LanguageCodes.ZH_CN
+  | typeof LanguageCodes.UK;
+
+export const DefaultLanguageCodes: LanguageCodeCollection<DefaultLanguageCode> = {
+  [LanguageCodes.EN_US]: 'en-US',
+  [LanguageCodes.EN_GB]: 'en-GB',
+  [LanguageCodes.FR]: 'fr',
+  [LanguageCodes.ES]: 'es',
+  [LanguageCodes.ZH_CN]: 'zh-CN',
+  [LanguageCodes.UK]: 'uk',
+};
+
+// Global interface that can be augmented by consumers
+declare global {
+  namespace I18n {
+    interface Config {
+      StringKey: DefaultStringKey;
+      Language: DefaultLanguageCode;
+      LanguageCodes: LanguageCodeCollection<DefaultLanguageCode>;
+      engine: I18nEngine<
+        I18n.Config['StringKey'],
+        I18n.Config['Language'],
+        Record<any, any>
+      >;
+    }
+  }
+}
+
+// Convenient type aliases that automatically pick up augmented types
+export type StringKey = I18n.Config['StringKey'];
+export type Language = I18n.Config['Language'];
+export type Engine = I18n.Config['engine'];
+export type DefaultLanguageCodesType = I18n.Config['LanguageCodes'];
+
+// Singleton instance that uses the augmented types
+export const getI18nEngine = (): Engine => I18nEngine.getInstance() as Engine;
+
+const getConfig = <
+  TConstants extends Record<string, any>,
+>(
+  constants: TConstants,
+  timezone?: Timezone,
+  adminTimezone?: Timezone,
+): I18nConfig<StringKey, Language, TConstants> => ({
+  strings: {
+    [LanguageCodes.EN_US]: {
+      [DefaultStringKey.Common_Test]: 'Test',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "Instance with key '{key}' already exists",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "Instance with key '{key}' not found",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        'Missing string collection for language: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "Missing translation for key '{key}' in language '{language}'",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "Default language '{language}' has no string collection",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        'Missing translation key for type: {type}',
+    },
+    [LanguageCodes.EN_GB]: {
+      [DefaultStringKey.Common_Test]: 'Test',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "Instance with key '{key}' already exists",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "Instance with key '{key}' not found",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        'Missing string collection for language: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "Missing translation for key '{key}' in language '{language}'",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "Default language '{language}' has no string collection",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        'Missing translation key for type: {type}',
+    },
+    [LanguageCodes.FR]: {
+      [DefaultStringKey.Common_Test]: 'Test',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "Instance avec clé '{key}' existe déjà",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "Instance avec clé '{key}' introuvable",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        'Collection de chaînes manquante pour la langue: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "Traduction manquante pour la clé '{key}' dans la langue '{language}'",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "La langue par défaut '{language}' n'a pas de collection de chaînes",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        'Clé de traduction manquante pour le type: {type}',
+    },
+    [LanguageCodes.ZH_CN]: {
+      [DefaultStringKey.Common_Test]: '测试',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "键为'{key}'的实例已存在",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "未找到键为'{key}'的实例",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        '缺少语言的字符串集合: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "在语言'{language}'中缺少键'{key}'的翻译",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "默认语言'{language}'没有字符串集合",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        '类型缺少翻译键: {type}',
+    },
+    [LanguageCodes.ES]: {
+      [DefaultStringKey.Common_Test]: 'Prueba',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "La instancia con clave '{key}' ya existe",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "Instancia con clave '{key}' no encontrada",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        'Falta colección de cadenas para el idioma: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "Falta traducción para la clave '{key}' en el idioma '{language}'",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "El idioma predeterminado '{language}' no tiene colección de cadenas",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        'Falta clave de traducción para el tipo: {type}',
+    },
+    [LanguageCodes.UK]: {
+      [DefaultStringKey.Common_Test]: 'Тест',
+      [DefaultStringKey.Error_InstanceAlreadyExistsTemplate]:
+        "Екземпляр з ключем '{key}' вже існує",
+      [DefaultStringKey.Error_InstanceNotFoundTemplate]:
+        "Екземпляр з ключем '{key}' не знайдено",
+      [DefaultStringKey.Error_MissingStringCollectionTemplate]:
+        'Відсутня колекція рядків для мови: {language}',
+      [DefaultStringKey.Error_MissingTranslationTemplate]:
+        "Відсутній переклад для ключа '{key}' в мові '{language}'",
+      [DefaultStringKey.Error_DefaultLanguageNoCollectionTemplate]:
+        "Мова за замовчуванням '{language}' не має колекції рядків",
+      [DefaultStringKey.Error_MissingTranslationKeyTemplate]:
+        'Відсутній ключ перекладу для типу: {type}',
+    },
+  } as any,
+  stringNames: Object.values(DefaultStringKey),
+  defaultLanguage: LanguageCodes.EN_US,
+  defaultTranslationContext: 'user' as LanguageContextSpace,
+  defaultCurrencyCode: new CurrencyCode(DefaultCurrencyCode),
+  languageCodes: DefaultLanguageCodes,
+  languages: [LanguageCodes.EN_US, LanguageCodes.EN_GB, LanguageCodes.FR, LanguageCodes.ES, LanguageCodes.ZH_CN, LanguageCodes.UK],
+  constants: constants,
+  enumName: 'DefaultStringKey',
+  enumObj: DefaultStringKey as Record<string, DefaultStringKey>,
+  timezone: timezone ?? new Timezone('UTC'),
+  adminTimezone: adminTimezone ?? new Timezone('UTC'),
+});
+
+export const getDefaultI18nEngine = <
+  TConstants extends Record<string, any>,
+  TContext extends I18nContext<DefaultLanguageCode>,
+>(
+  constants: TConstants,
+  timezone?: Timezone,
+  adminTimezone?: Timezone,
+) =>
+  new I18nEngine<
+    DefaultStringKey,
+    DefaultLanguageCode,
+    TConstants,
+    TContext
+  >(
+    getConfig<TConstants>(
+      constants,
+      timezone,
+      adminTimezone,
+    ),
+    'user' as LanguageContextSpace,
+  );

package/src/enum-registry.ts

@@ -0,0 +1,138 @@
+import { EnumLanguageTranslation } from './types';
+
+/**
+ * Registry for managing enum translations across multiple languages.
+ */
+export class EnumTranslationRegistry<
+  TStringKey extends string,
+  TLanguage extends string,
+> {
+  protected translations = new Map<
+    any,
+    EnumLanguageTranslation<any, TLanguage>
+  >();
+  protected enumNames = new WeakMap<any, string>();
+  protected availableLanguages: Set<TLanguage>;
+  protected translateFn?: (
+    key: TStringKey,
+    vars?: Record<string, any>,
+  ) => string;
+
+  constructor(
+    availableLanguages: TLanguage[],
+    translateFn?: (key: TStringKey, vars?: Record<string, any>) => string,
+  ) {
+    this.availableLanguages = new Set(availableLanguages);
+    this.translateFn = translateFn;
+  }
+
+  /**
+   * Registers an enumeration with its translations and a name.
+   * @param enumObj The enumeration object
+   * @param translations The translations for the enumeration
+   * @param enumName The name of the enumeration
+   */
+  public register<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    translations: EnumLanguageTranslation<TEnum, TLanguage>,
+    enumName: string,
+  ): void {
+    this.validateTranslations(translations, enumName);
+    this.translations.set(enumObj, translations);
+    this.enumNames.set(enumObj, enumName);
+  }
+
+  /**
+   * Translates a value from the given enumeration to the specified language.
+   * @param enumObj The enumeration object
+   * @param value The value to translate
+   * @param language The target language for translation
+   * @returns The translated string
+   */
+  public translate<TEnum extends string | number>(
+    enumObj: Record<string, TEnum>,
+    value: TEnum,
+    language: TLanguage,
+  ): string {
+    const translations = this.translations.get(enumObj);
+    if (!translations) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumNotFoundTemplate' as TStringKey, {
+            enumName: this.getEnumName(enumObj),
+          })
+        : `No translations found for enum: ${this.getEnumName(enumObj)}`;
+      throw new Error(message);
+    }
+
+    const langTranslations = translations[language];
+    if (!langTranslations) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumLanguageNotFoundTemplate' as TStringKey, {
+            language,
+          })
+        : `No translations found for language: ${language}`;
+      throw new Error(message);
+    }
+
+    let result = langTranslations[value];
+    if (!result && typeof value === 'number') {
+      const stringKey = Object.keys(enumObj).find(
+        (key) => enumObj[key] === value,
+      );
+      if (stringKey) {
+        result = langTranslations[stringKey as TEnum];
+      }
+    }
+
+    if (!result) {
+      const message = this.translateFn
+        ? this.translateFn('Error_EnumValueNotFoundTemplate' as TStringKey, {
+            value: String(value),
+          })
+        : `No translation found for value: ${String(value)}`;
+      throw new Error(message);
+    }
+
+    return result;
+  }
+
+  /**
+   * Gets the name of the enumeration.
+   * @param enumObj The enumeration object
+   * @returns The name of the enumeration
+   */
+  private getEnumName(enumObj: any): string {
+    return this.enumNames.get(enumObj) || 'UnknownEnum';
+  }
+
+  /**
+   * Checks if the registry has translations for the given enumeration.
+   * @param enumObj The enumeration object
+   * @returns True if translations exist, false otherwise
+   */
+  has(enumObj: any): boolean {
+    return this.translations.has(enumObj);
+  }
+
+  /**
+   * Validates that enum translations only contain available languages.
+   * @param translations The translations to validate
+   * @param enumName The name of the enumeration for error messages
+   */
+  private validateTranslations<TEnum extends string | number>(
+    translations: EnumLanguageTranslation<TEnum, TLanguage>,
+    enumName: string,
+  ): void {
+    for (const language of Object.keys(translations) as TLanguage[]) {
+      if (!this.availableLanguages.has(language)) {
+        const message = this.translateFn
+          ? this.translateFn(
+              'Error_EnumLanguageNotAvailableTemplate' as TStringKey,
+              { language, enumName },
+            )
+          : `Language '${language}' in enum '${enumName}' is not available in this engine instance`;
+        throw new Error(message);
+      }
+    }
+  }
+}