@digitaldefiance/i18n-lib 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,112 @@
+# @digitaldefiance/i18n-lib
+
+A generic TypeScript i18n library with enum translation support and template variable replacement.
+
+## Features
+
+- **Generic Design**: Works with any string and language enums
+- **Template Variables**: Replace `{variable}` placeholders in strings
+- **Enum Translation**: Translate enum values with type safety
+- **Context Support**: Admin vs user translation contexts
+- **Fallback Languages**: Graceful degradation when translations missing
+- **Zero Dependencies**: Lightweight with no external dependencies
+
+## Installation
+
+```bash
+npm install @digitaldefiance/i18n-lib
+```
+
+## Quick Start
+
+```typescript
+import { I18nEngine, I18nConfig, createContext } from '@digitaldefiance/i18n-lib';
+
+// Define your enums
+enum MyStrings {
+  Welcome = 'welcome',
+  UserGreetingTemplate = 'userGreetingTemplate'
+}
+
+enum MyLanguages {
+  English = 'English',
+  Spanish = 'Español'
+}
+
+// Configure the engine
+const config: I18nConfig<MyStrings, MyLanguages> = {
+  strings: {
+    [MyLanguages.English]: {
+      [MyStrings.Welcome]: 'Welcome!',
+      [MyStrings.UserGreetingTemplate]: 'Hello, {name}!'
+    },
+    [MyLanguages.Spanish]: {
+      [MyStrings.Welcome]: '¡Bienvenido!',
+      [MyStrings.UserGreetingTemplate]: '¡Hola, {name}!'
+    }
+  },
+  defaultLanguage: MyLanguages.English,
+  languageCodes: {
+    [MyLanguages.English]: 'en',
+    [MyLanguages.Spanish]: 'es'
+  }
+};
+
+// Create engine and context
+const i18n = new I18nEngine(config);
+const context = createContext(MyLanguages.English);
+
+// Translate strings
+const welcome = i18n.translate(MyStrings.Welcome, context);
+// "Welcome!"
+
+const greeting = i18n.translate(MyStrings.UserGreetingTemplate, context, { name: 'John' });
+// "Hello, John!"
+```
+
+## Enum Translation
+```typescript
+enum Status {
+  Active = 'active',
+  Inactive = 'inactive'
+}
+
+// Register enum translations
+i18n.registerEnum(Status, {
+  [MyLanguages.English]: {
+    [Status.Active]: 'Active',
+    [Status.Inactive]: 'Inactive'
+  },
+  [MyLanguages.Spanish]: {
+    [Status.Active]: 'Activo',
+    [Status.Inactive]: 'Inactivo'
+  }
+}, 'Status');
+
+// Translate enum values
+const statusText = i18n.translateEnum(Status, Status.Active, MyLanguages.Spanish);
+// "Activo"
+```
+
+## API Reference
+### i18nEngine
+ - translate(key, context, vars?, language?, fallback?) - Translate string with optional variables
+
+ - translateEnum(enumObj, value, language) - Translate enum value
+
+ - registerEnum(enumObj, translations, name) - Register enum translations
+
+ - getLanguageCode(language) - Get language code for language
+
+### Context Management
+ - createContext(defaultLanguage) - Create new context
+
+ - setLanguage(context, language) - Set user language
+
+ - setAdminLanguage(context, language) - Set admin language
+
+ - setContext(context, 'admin' | 'user') - Set context type
+
+## License
+
+MIT

package/dist/enum-registry.d.ts

@@ -1,8 +1,8 @@
-import { EnumTranslationMap } from './types';
+import { EnumLanguageTranslation } from './types';
 export declare class EnumTranslationRegistry<TLanguage extends string> {
     private translations;
     private enumNames;
-    register<TEnum extends string | number>(enumObj: Record<string, TEnum>, translations: EnumTranslationMap<TEnum, TLanguage>, enumName: string): void;
+    register<TEnum extends string | number>(enumObj: Record<string, TEnum>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
     translate<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
     private getEnumName;
     has(enumObj: any): boolean;

package/dist/i18n-engine.d.ts

@@ -1,11 +1,11 @@
-import { I18nConfig, I18nContext } from './types';
+import { I18nConfig, I18nContext, EnumLanguageTranslation } from './types';
 export declare class I18nEngine<TStringKey extends string, TLanguage extends string> {
     private config;
     private enumRegistry;
     constructor(config: I18nConfig<TStringKey, TLanguage>);
     translate(key: TStringKey, context: I18nContext<TLanguage>, vars?: Record<string, string | number>, language?: TLanguage, fallbackLanguage?: TLanguage): string;
     translateEnum<TEnum extends string | number>(enumObj: Record<string, TEnum>, value: TEnum, language: TLanguage): string;
-    registerEnum<TEnum extends string | number>(enumObj: Record<string, TEnum>, translations: Record<TLanguage, Record<TEnum, string>>, enumName: string): void;
+    registerEnum<TEnum extends string | number>(enumObj: Record<string, TEnum>, translations: EnumLanguageTranslation<TEnum, TLanguage>, enumName: string): void;
     private getString;
     getLanguageCode(language: TLanguage): string;
 }

package/dist/types.d.ts

@@ -1,9 +1,9 @@
 export type LanguageContext = 'admin' | 'user';
 export type CurrencyPosition = 'prefix' | 'postfix' | 'infix';
-export type StringsCollection<TStringKey extends string> = Record<TStringKey, string>;
-export type MasterStringsCollection<TStringKey extends string, TLanguage extends string> = Record<TLanguage, StringsCollection<TStringKey>>;
-export type LanguageCodeCollection<TLanguage extends string> = Record<TLanguage, string>;
-export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Record<TLanguage, Record<TEnum, string>>;
+export type StringsCollection<TStringKey extends string> = Partial<Record<TStringKey, string>>;
+export type MasterStringsCollection<TStringKey extends string, TLanguage extends string> = Partial<Record<TLanguage, StringsCollection<TStringKey>>>;
+export type LanguageCodeCollection<TLanguage extends string> = Partial<Record<TLanguage, string>>;
+export type EnumTranslationMap<TEnum extends string | number, TLanguage extends string> = Partial<Record<TLanguage, Partial<Record<TEnum, string>>>>;
 export interface I18nConfig<TStringKey extends string, TLanguage extends string> {
     strings: MasterStringsCollection<TStringKey, TLanguage>;
     defaultLanguage: TLanguage;
@@ -15,3 +15,19 @@ export interface I18nContext<TLanguage extends string> {
     adminLanguage: TLanguage;
     currentContext: LanguageContext;
 }
+/**
+ * Generic translation type for any enumeration
+ */
+export type EnumTranslation<T extends string | number> = {
+    [K in T]: string;
+};
+/**
+ * Generic language translation type for any enumeration
+ */
+export type EnumLanguageTranslation<T extends string | number, TLanguage extends string = string> = {
+    [L in TLanguage]: EnumTranslation<T>;
+};
+/**
+ * Helper function to create typed translations for an enumeration
+ */
+export declare function createTranslations<T extends string | number, TLanguage extends string>(translations: EnumLanguageTranslation<T, TLanguage>): EnumLanguageTranslation<T, TLanguage>;

package/dist/types.js

@@ -1,2 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTranslations = createTranslations;
+/**
+ * Helper function to create typed translations for an enumeration
+ */
+function createTranslations(translations) {
+    return translations;
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@digitaldefiance/i18n-lib",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Generic i18n library with enum translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "yarn tsc",
-    "test": "jest",
-    "prepublishOnly": "yarn build"
+    "test": "yarn jest",
+    "prepublishOnly": "yarn build",
+    "publish": "npm publish --access public"
   },
   "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "jest": "^29.0.0",
+    "jest-util": "^30.0.5",
+    "ts-jest": "^29.0.0",
     "typescript": "^5.9.2"
   },
   "files": [
@@ -25,5 +30,5 @@
   ],
   "author": "Digital Defiance",
   "license": "MIT",
-  "packageManager": "yarn@4.9.2+sha512.1fc009bc09d13cfd0e19efa44cbfc2b9cf6ca61482725eb35bbc5e257e093ebf4130db6dfe15d604ff4b79efd8e1e8e99b25fa7d0a6197c9f9826358d4d65c3c"
+  "packageManager": "yarn@4.10.3"
 }