@umituz/web-localization 1.1.0 → 1.1.4

package/dist/domain/entities/translation.entity.d.ts

@@ -27,4 +27,3 @@ export interface TranslationStats {
     skippedCount: number;
     translatedKeys: TranslationItem[];
 }
-//# sourceMappingURL=translation.entity.d.ts.map

package/dist/domain/interfaces/translation-service.interface.d.ts

@@ -18,4 +18,3 @@ export interface ITranslationService {
     translateBatch(requests: TranslationRequest[]): Promise<TranslationStats>;
     translateObject(sourceObject: Record<string, unknown>, targetObject: Record<string, unknown>, targetLanguage: string, path?: string, stats?: TranslationStats, onTranslate?: (key: string, from: string, to: string) => void): Promise<void>;
 }
-//# sourceMappingURL=translation-service.interface.d.ts.map

package/dist/index.d.ts

@@ -8,4 +8,4 @@ export * from "./infrastructure/services/google-translate.service";
 export * from "./infrastructure/constants";
 export * from "./infrastructure/utils/text-validator.util";
 export * from "./infrastructure/utils/rate-limit.util";
-//# sourceMappingURL=index.d.ts.map
+export * from "./integrations/i18n.setup";

package/dist/index.js

@@ -8,3 +8,4 @@ export * from "./infrastructure/services/google-translate.service";
 export * from "./infrastructure/constants";
 export * from "./infrastructure/utils/text-validator.util";
 export * from "./infrastructure/utils/rate-limit.util";
+export * from "./integrations/i18n.setup";

package/dist/infrastructure/constants/index.d.ts

@@ -8,4 +8,3 @@ export declare const DEFAULT_TIMEOUT = 10000;
 export declare const DEFAULT_LOCALES_DIR = "src/locales";
 export declare const DEFAULT_SOURCE_DIR = "src";
 export declare const DEFAULT_BASE_LANGUAGE = "en-US";
-//# sourceMappingURL=index.d.ts.map

package/dist/infrastructure/services/cli.service.d.ts

@@ -2,10 +2,10 @@ export interface SyncOptions {
     localesDir?: string;
     sourceDir?: string;
     baseLang?: string;
+    force?: boolean;
 }
 export declare class CLIService {
     sync(options?: SyncOptions): Promise<void>;
     translate(options?: SyncOptions): Promise<void>;
 }
 export declare const cliService: CLIService;
-//# sourceMappingURL=cli.service.d.ts.map

package/dist/infrastructure/services/cli.service.js

@@ -81,7 +81,7 @@ export class CLIService {
             await googleTranslateService.translateObject(baseData, targetData, langCode.split("-")[0], // ISO 639-1
             "", stats, (key, from, to) => {
                 process.stdout.write(chalk.gray(`   • ${key}: ${from.substring(0, 15)}... → ${to.substring(0, 15)}...\r`));
-            });
+            }, options.force);
             if (stats.successCount > 0) {
                 fs.writeFileSync(targetPath, generateTypeScriptContent(targetData, langCode));
                 console.log(chalk.green(`   ✅ Successfully translated ${stats.successCount} keys.`));

package/dist/infrastructure/services/google-translate.service.d.ts

@@ -12,9 +12,8 @@ declare class GoogleTranslateService implements ITranslationService {
     private ensureInitialized;
     translate(request: TranslationRequest): Promise<TranslationResponse>;
     translateBatch(requests: TranslationRequest[]): Promise<TranslationStats>;
-    translateObject(sourceObject: Record<string, unknown>, targetObject: Record<string, unknown>, targetLanguage: string, path?: string, stats?: TranslationStats, onTranslate?: (key: string, from: string, to: string) => void): Promise<void>;
+    translateObject(sourceObject: Record<string, unknown>, targetObject: Record<string, unknown>, targetLanguage: string, path?: string, stats?: TranslationStats, onTranslate?: (key: string, from: string, to: string) => void, force?: boolean): Promise<void>;
     private callTranslateAPI;
 }
 export declare const googleTranslateService: GoogleTranslateService;
 export { GoogleTranslateService };
-//# sourceMappingURL=google-translate.service.d.ts.map

package/dist/infrastructure/services/google-translate.service.js

@@ -118,7 +118,7 @@ class GoogleTranslateService {
         failureCount: 0,
         skippedCount: 0,
         translatedKeys: [],
-    }, onTranslate) {
+    }, onTranslate, force = false) {
         if (!sourceObject || typeof sourceObject !== "object")
             return;
         if (!targetObject || typeof targetObject !== "object")
@@ -135,11 +135,11 @@ class GoogleTranslateService {
                 if (!targetObject[key] || typeof targetObject[key] !== "object") {
                     targetObject[key] = {};
                 }
-                await this.translateObject(enValue, targetObject[key], targetLanguage, currentPath, stats, onTranslate);
+                await this.translateObject(enValue, targetObject[key], targetLanguage, currentPath, stats, onTranslate, force);
             }
             else if (typeof enValue === "string") {
                 stats.totalCount++;
-                if (needsTranslation(targetValue, enValue)) {
+                if (force || needsTranslation(targetValue, enValue)) {
                     textsToTranslate.push({ key, enValue, currentPath });
                 }
                 else {
@@ -161,10 +161,14 @@ class GoogleTranslateService {
                     const translatedItem = results.translatedKeys[resultIndex];
                     if (translatedItem && translatedItem.from === enValue && translatedItem.to !== enValue) {
                         targetObject[key] = translatedItem.to;
+                        stats.successCount++;
                         if (onTranslate)
                             onTranslate(currentPath, enValue, translatedItem.to);
                         resultIndex++;
                     }
+                    else {
+                        stats.failureCount++;
+                    }
                 }
             }
         }

package/dist/infrastructure/utils/file.util.d.ts

@@ -7,4 +7,3 @@ export declare function parseTypeScriptFile(filePath: string): Record<string, un
  * Generates a TypeScript file content from an object
  */
 export declare function generateTypeScriptContent(obj: Record<string, unknown>, langCode?: string): string;
-//# sourceMappingURL=file.util.d.ts.map

package/dist/infrastructure/utils/rate-limit.util.d.ts

@@ -8,4 +8,3 @@ export declare class RateLimiter {
     constructor(minDelay?: number);
     waitForSlot(): Promise<void>;
 }
-//# sourceMappingURL=rate-limit.util.d.ts.map

package/dist/infrastructure/utils/text-validator.util.d.ts

@@ -13,4 +13,3 @@ export declare function shouldSkipWord(text: string): boolean;
  * Determines if a key needs translation
  */
 export declare function needsTranslation(targetValue: unknown, sourceValue: string): boolean;
-//# sourceMappingURL=text-validator.util.d.ts.map

package/dist/integrations/i18n.setup.d.ts

@@ -0,0 +1,22 @@
+import i18n from 'i18next';
+export interface SetupI18nOptions {
+    resources: Record<string, {
+        translation: any;
+    }>;
+    defaultLng?: string;
+    fallbackLng?: string;
+    onInit?: (instance: typeof i18n) => void;
+    detection?: any;
+    seo?: {
+        titleKey: string;
+        descriptionKey: string;
+        defaultImage?: string;
+        twitterHandle?: string;
+    };
+}
+/**
+ * Static i18n initialization to simplify main app code.
+ * @description All common configuration including SEO integration is hidden inside this package.
+ */
+export declare function setupI18n(options: SetupI18nOptions): import("i18next").i18n;
+export default i18n;

package/dist/integrations/i18n.setup.js

@@ -0,0 +1,38 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import { initSEO } from '@umituz/web-seo';
+/**
+ * Static i18n initialization to simplify main app code.
+ * @description All common configuration including SEO integration is hidden inside this package.
+ */
+export function setupI18n(options) {
+    const { resources, defaultLng = 'en-US', fallbackLng = 'en-US', onInit, detection = {
+        order: ['localStorage', 'navigator'],
+        caches: ['localStorage'],
+    }, seo, } = options;
+    i18n
+        .use(LanguageDetector)
+        .use(initReactI18next)
+        .init({
+        resources,
+        lng: defaultLng,
+        fallbackLng,
+        interpolation: {
+            escapeValue: false,
+        },
+        detection,
+    })
+        .then(() => {
+        if (seo) {
+            initSEO({
+                i18n,
+                ...seo,
+            });
+        }
+        if (onInit)
+            onInit(i18n);
+    });
+    return i18n;
+}
+export default i18n;

package/dist/scripts/cli.d.ts

@@ -3,4 +3,3 @@
  * CLI Tool for @umituz/web-localization
  */
 export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/scripts/cli.js

@@ -29,6 +29,7 @@ program
     .description("Automatically translate missing strings using Google Translate")
     .option("-d, --locales-dir <dir>", "Directory containing locale files", "src/locales")
     .option("-b, --base-lang <lang>", "Base language code", "en-US")
+    .option("-f, --force", "Force re-translation of all strings", false)
     .action(async (options) => {
     try {
         await cliService.translate(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-localization",
-  "version": "1.1.0",
+  "version": "1.1.4",
   "description": "Google Translate integrated localization package for web applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -11,8 +11,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./services": "./src/infrastructure/services/index.ts",
-    "./utils": "./src/infrastructure/utils/index.ts",
+    "./setup": "./src/integrations/i18n.setup.ts",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -37,8 +36,10 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "dotenv": "^16.4.5",
-    "ts-morph": "^27.0.2"
+    "i18next": "^23.11.2",
+    "react-i18next": "^14.1.1",
+    "i18next-browser-languagedetector": "^7.2.1",
+    "@umituz/web-seo": "file:../web-seo"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",

package/src/domain/interfaces/translation-service.interface.ts

@@ -28,6 +28,7 @@ export interface ITranslationService {
     targetLanguage: string,
     path?: string,
     stats?: TranslationStats,
-    onTranslate?: (key: string, from: string, to: string) => void
+    onTranslate?: (key: string, from: string, to: string) => void,
+    force?: boolean
   ): Promise<void>;
 }

package/src/index.ts

@@ -9,3 +9,4 @@ export * from "./infrastructure/services/google-translate.service";
 export * from "./infrastructure/constants";
 export * from "./infrastructure/utils/text-validator.util";
 export * from "./infrastructure/utils/rate-limit.util";
+export * from "./integrations/i18n.setup";

package/src/infrastructure/constants/index.ts

@@ -11,3 +11,7 @@ export const DEFAULT_TIMEOUT = 10000;
 export const DEFAULT_LOCALES_DIR = "src/locales";
 export const DEFAULT_SOURCE_DIR = "src";
 export const DEFAULT_BASE_LANGUAGE = "en-US";
+
+// Rate limiter defaults
+export const RATE_LIMIT_DEFAULT_DELAY = 100;
+export const RATE_LIMIT_MIN_DELAY = 0;

package/src/infrastructure/services/cli.service.ts

@@ -1,19 +1,47 @@
 import fs from "fs";
 import path from "path";
 import chalk from "chalk";
+import type { TranslationStats } from "../../domain/entities/translation.entity.js";
 import { googleTranslateService } from "./google-translate.service.js";
 import { parseTypeScriptFile, generateTypeScriptContent } from "../utils/file.util.js";
-import { 
-  DEFAULT_LOCALES_DIR, 
-  DEFAULT_BASE_LANGUAGE 
+import {
+  DEFAULT_LOCALES_DIR,
+  DEFAULT_BASE_LANGUAGE
 } from "../constants/index.js";
 
 export interface SyncOptions {
   localesDir?: string;
   sourceDir?: string;
   baseLang?: string;
+  force?: boolean;
 }
 
+// Extracted outside loop for better performance
+const syncObject = (
+  source: Record<string, unknown>,
+  target: Record<string, unknown>
+): Record<string, unknown> => {
+  const result = { ...target };
+  for (const key in source) {
+    if (typeof source[key] === "object" && source[key] !== null) {
+      result[key] = syncObject(
+        source[key] as Record<string, unknown>,
+        (target[key] as Record<string, unknown>) || {}
+      );
+    } else if (target[key] === undefined) {
+      // Let empty string indicate untranslated state
+      result[key] = typeof source[key] === "string" ? "" : source[key];
+    }
+  }
+  // Remove extra keys
+  for (const key in target) {
+    if (source[key] === undefined) {
+      delete result[key];
+    }
+  }
+  return result;
+};
+
 export class CLIService {
   async sync(options: SyncOptions = {}): Promise<void> {
     const localesDir = path.resolve(process.cwd(), options.localesDir || DEFAULT_LOCALES_DIR);
@@ -32,7 +60,7 @@ export class CLIService {
 
     const baseData = parseTypeScriptFile(baseLangPath);
     const files = fs.readdirSync(localesDir)
-      .filter(f => f.match(/^[a-z]{2}-[A-Z]{2}\.ts$/) && f !== `${baseLang}.ts`)
+      .filter(f => f.match(/^[a-z]{2}(-[A-Z]{2})?\.ts$/) && f !== `${baseLang}.ts`)
       .sort();
 
     console.log(chalk.blue(`📊 Found ${files.length} languages to sync with ${baseLang}.\n`));
@@ -40,30 +68,7 @@ export class CLIService {
     for (const file of files) {
       const targetPath = path.join(localesDir, file);
       const targetData = parseTypeScriptFile(targetPath);
-      const langCode = file.replace(".ts", "");
-
-      // Deep merge with base data structure
-      const syncObject = (source: Record<string, unknown>, target: Record<string, unknown>): Record<string, unknown> => {
-        const result = { ...target };
-        for (const key in source) {
-          if (typeof source[key] === "object" && source[key] !== null) {
-            result[key] = syncObject(
-              source[key] as Record<string, unknown>, 
-              (target[key] as Record<string, unknown>) || {}
-            );
-          } else if (target[key] === undefined) {
-             // Let empty string indicate untranslated state
-            result[key] = typeof source[key] === "string" ? "" : source[key];
-          }
-        }
-        // Remove extra keys
-        for (const key in target) {
-          if (source[key] === undefined) {
-            delete result[key];
-          }
-        }
-        return result;
-      };
+      const langCode = path.basename(file, ".ts");
 
       const syncedData = syncObject(baseData, targetData);
       fs.writeFileSync(targetPath, generateTypeScriptContent(syncedData, langCode));
@@ -86,7 +91,7 @@ export class CLIService {
     googleTranslateService.initialize({});
     const baseData = parseTypeScriptFile(baseLangPath);
     const files = fs.readdirSync(localesDir)
-      .filter(f => f.match(/^[a-z]{2}-[A-Z]{2}\.ts$/) && f !== `${baseLang}.ts`)
+      .filter(f => f.match(/^[a-z]{2}(-[A-Z]{2})?\.ts$/) && f !== `${baseLang}.ts`)
       .sort();
 
     console.log(chalk.blue.bold(`🚀 Starting automatic translation for ${files.length} languages...\n`));
@@ -94,9 +99,9 @@ export class CLIService {
     for (const file of files) {
       const targetPath = path.join(localesDir, file);
       const targetData = parseTypeScriptFile(targetPath);
-      const langCode = file.replace(".ts", "");
-      
-      const stats = {
+      const langCode = path.basename(file, ".ts");
+
+      const stats: TranslationStats = {
         totalCount: 0,
         successCount: 0,
         failureCount: 0,
@@ -106,15 +111,19 @@ export class CLIService {
 
       console.log(chalk.yellow(`🌍 Translating ${langCode}...`));
 
+      // Extract ISO 639-1 language code (e.g., "en" from "en-US")
+      const targetLang = langCode.includes("-") ? langCode.split("-")[0] : langCode;
+
       await googleTranslateService.translateObject(
         baseData,
         targetData,
-        langCode.split("-")[0], // ISO 639-1
+        targetLang,
         "",
         stats,
         (key, from, to) => {
           process.stdout.write(chalk.gray(`   • ${key}: ${from.substring(0, 15)}... → ${to.substring(0, 15)}...\r`));
-        }
+        },
+        options.force
       );
 
       if (stats.successCount > 0) {

package/src/infrastructure/services/google-translate.service.ts

@@ -22,11 +22,12 @@ import {
   GOOGLE_TRANSLATE_API_URL,
   DEFAULT_MIN_DELAY,
   DEFAULT_TIMEOUT,
+  DEFAULT_MAX_RETRIES,
 } from "../constants/index.js";
 
 class GoogleTranslateService implements ITranslationService {
   private config: TranslationServiceConfig | null = null;
-  private rateLimiter: RateLimiter | null = null;
+  private _rateLimiter: RateLimiter | null = null;
 
   initialize(config: TranslationServiceConfig): void {
     this.config = {
@@ -34,11 +35,18 @@ class GoogleTranslateService implements ITranslationService {
       timeout: DEFAULT_TIMEOUT,
       ...config,
     };
-    this.rateLimiter = new RateLimiter(this.config.minDelay);
+    this._rateLimiter = new RateLimiter(this.config.minDelay);
   }
 
   isInitialized(): boolean {
-    return this.config !== null && this.rateLimiter !== null;
+    return this.config !== null && this._rateLimiter !== null;
+  }
+
+  private get rateLimiter(): RateLimiter {
+    if (!this._rateLimiter) {
+      throw new Error("RateLimiter not initialized");
+    }
+    return this._rateLimiter;
   }
 
   private ensureInitialized(): void {
@@ -75,7 +83,7 @@ class GoogleTranslateService implements ITranslationService {
       };
     }
 
-    await this.rateLimiter!.waitForSlot();
+    await this.rateLimiter.waitForSlot();
 
     try {
       const translatedText = await this.callTranslateAPI(
@@ -127,9 +135,9 @@ class GoogleTranslateService implements ITranslationService {
     }
 
     for (const chunk of chunks) {
-      const results = await Promise.all(
+      const results = await Promise.allSettled(
         chunk.map(async (request) => {
-          await this.rateLimiter!.waitForSlot();
+          await this.rateLimiter.waitForSlot();
           return this.callTranslateAPI(
             request.text,
             request.targetLanguage,
@@ -140,19 +148,22 @@ class GoogleTranslateService implements ITranslationService {
 
       for (let i = 0; i < chunk.length; i++) {
         const request = chunk[i];
-        const translatedText = results[i];
-
-        if (translatedText && translatedText !== request.text) {
-          stats.successCount++;
-          stats.translatedKeys.push({
-            key: request.text,
-            from: request.text,
-            to: translatedText,
-          });
-        } else if (!translatedText) {
-          stats.failureCount++;
+        const result = results[i];
+
+        if (result.status === "fulfilled") {
+          const translatedText = result.value;
+          if (translatedText && translatedText !== request.text) {
+            stats.successCount++;
+            stats.translatedKeys.push({
+              key: request.text,
+              from: request.text,
+              to: translatedText,
+            });
+          } else {
+            stats.skippedCount++;
+          }
         } else {
-          stats.skippedCount++;
+          stats.failureCount++;
         }
       }
     }
@@ -172,7 +183,8 @@ class GoogleTranslateService implements ITranslationService {
       skippedCount: 0,
       translatedKeys: [],
     },
-    onTranslate?: (key: string, from: string, to: string) => void
+    onTranslate?: (key: string, from: string, to: string) => void,
+    force = false
   ): Promise<void> {
     if (!sourceObject || typeof sourceObject !== "object") return;
     if (!targetObject || typeof targetObject !== "object") return;
@@ -196,11 +208,12 @@ class GoogleTranslateService implements ITranslationService {
           targetLanguage,
           currentPath,
           stats,
-          onTranslate
+          onTranslate,
+          force
         );
       } else if (typeof enValue === "string") {
         stats.totalCount++;
-        if (needsTranslation(targetValue, enValue)) {
+        if (force || needsTranslation(targetValue, enValue)) {
           textsToTranslate.push({key, enValue, currentPath});
         } else {
           stats.skippedCount++;
@@ -219,15 +232,22 @@ class GoogleTranslateService implements ITranslationService {
           }))
         );
 
-        let resultIndex = 0;
+        // Create a map for quick lookup of translations
+        const translationMap = new Map<string, string>();
+        for (const item of results.translatedKeys) {
+          translationMap.set(item.from, item.to);
+        }
+
         for (let j = 0; j < batch.length; j++) {
           const {key, enValue, currentPath} = batch[j];
-          const translatedItem = results.translatedKeys[resultIndex];
-
-          if (translatedItem && translatedItem.from === enValue && translatedItem.to !== enValue) {
-            targetObject[key] = translatedItem.to;
-            if (onTranslate) onTranslate(currentPath, enValue, translatedItem.to);
-            resultIndex++;
+          const translatedText = translationMap.get(enValue);
+
+          if (translatedText && translatedText !== enValue) {
+            targetObject[key] = translatedText;
+            stats.successCount++;
+            if (onTranslate) onTranslate(currentPath, enValue, translatedText);
+          } else {
+            stats.failureCount++;
           }
         }
       }
@@ -238,7 +258,7 @@ class GoogleTranslateService implements ITranslationService {
     text: string,
     targetLanguage: string,
     sourceLanguage: string,
-    retries = 3,
+    retries = DEFAULT_MAX_RETRIES,
     backoffMs = 2000
   ): Promise<string> {
     // 1. Variable Protection (Extract {{variables}})
@@ -246,7 +266,7 @@ class GoogleTranslateService implements ITranslationService {
     let counter = 0;
     
     // Find all {{something}} patterns
-    let safeText = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
+    const safeText = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
       const placeholder = `_VAR${counter}_`; // Using a simple token less likely to be split
       varMap.set(placeholder, match);
       counter++;
@@ -257,7 +277,7 @@ class GoogleTranslateService implements ITranslationService {
     const encodedText = encodeURIComponent(safeText);
     const url = `${GOOGLE_TRANSLATE_API_URL}?client=gtx&sl=${sourceLanguage}&tl=${targetLanguage}&dt=t&q=${encodedText}`;
 
-    for (let attempt = 0; attempt <= retries; attempt++) {
+    for (let attempt = 0; attempt < retries; attempt++) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeout);
 
@@ -268,7 +288,7 @@ class GoogleTranslateService implements ITranslationService {
 
         if (!response.ok) {
           if (response.status === 429 || response.status >= 500) {
-            if (attempt < retries) {
+            if (attempt < retries - 1) {
               clearTimeout(timeoutId);
               // Exponential backoff
               const delay = backoffMs * Math.pow(2, attempt);
@@ -289,7 +309,7 @@ class GoogleTranslateService implements ITranslationService {
           data[0].length > 0 &&
         typeof data[0][0][0] === "string"
         ) {
-          translatedStr = data[0].map((item: any) => item[0]).join('');
+          translatedStr = data[0].map((item: unknown[]) => item[0] as string).join('');
         }
 
         // 2. Re-inject Variables

package/src/infrastructure/utils/file.util.ts

@@ -1,13 +1,21 @@
 import fs from "fs";
+import path from "path";
 
 /**
  * Parses a TypeScript file containing an object export
  * @description Simplistic parser for 'export default { ... }' or 'export const data = { ... }'
+ * @security Note: Uses Function constructor - only use with trusted local files
  */
 export function parseTypeScriptFile(filePath: string): Record<string, unknown> {
-  if (!fs.existsSync(filePath)) return {};
+  // Validate file path is within project directory
+  const resolvedPath = path.resolve(filePath);
+  if (!resolvedPath.startsWith(process.cwd())) {
+    throw new Error(`Security: File path outside project directory: ${filePath}`);
+  }
+
+  if (!fs.existsSync(resolvedPath)) return {};
   
-  const content = fs.readFileSync(filePath, "utf-8");
+  const content = fs.readFileSync(resolvedPath, "utf-8");
   
   // Extract the object part
   // This is a naive implementation, but matches the pattern used in the project

package/src/infrastructure/utils/rate-limit.util.ts

@@ -3,23 +3,31 @@
  * @description Controls the frequency of API requests
  */
 
+import { RATE_LIMIT_DEFAULT_DELAY } from "../constants/index.js";
+
 export class RateLimiter {
   private lastRequestTime = 0;
-  private minDelay: number;
+  private readonly minDelay: number;
 
-  constructor(minDelay = 100) {
+  constructor(minDelay = RATE_LIMIT_DEFAULT_DELAY) {
+    if (minDelay < 0) {
+      throw new Error("minDelay must be non-negative");
+    }
     this.minDelay = minDelay;
   }
 
   async waitForSlot(): Promise<void> {
     const now = Date.now();
     const elapsedTime = now - this.lastRequestTime;
-    
+
     if (elapsedTime < this.minDelay) {
       const waitTime = this.minDelay - elapsedTime;
       await new Promise(resolve => setTimeout(resolve, waitTime));
+      // Set to the time when we can make the next request
+      this.lastRequestTime = Date.now();
+    } else {
+      // No wait needed, update to current time
+      this.lastRequestTime = now;
     }
-    
-    this.lastRequestTime = Date.now();
   }
 }

package/src/infrastructure/utils/text-validator.util.ts

@@ -2,6 +2,10 @@
  * Text Validation Utilities
  */
 
+// Default words/patterns to skip during translation
+const DEFAULT_SKIPLIST = ["@umituz"] as const;
+const skiplist = [...DEFAULT_SKIPLIST];
+
 /**
  * Validates if the text is suitable for translation
  */
@@ -16,14 +20,13 @@ export function isValidText(text: unknown): text is string {
  * Checks if a word should be skipped (e.g., proper nouns, symbols)
  */
 export function shouldSkipWord(text: string): boolean {
-  const skiplist = ["@umituz"];
   return skiplist.some(word => text.includes(word));
 }
 
 /**
  * Determines if a key needs translation
  */
-export function needsTranslation(targetValue: unknown, sourceValue: string): boolean {
+export function needsTranslation(targetValue: unknown, _sourceValue: string): boolean {
   if (typeof targetValue !== "string") return true;
   if (targetValue.length === 0) return true; // Empty string means untranslated
   // Do NOT return true if target === source anymore, to avoid infinite translations for words that are identical in both languages

package/src/integrations/i18n.setup.ts

@@ -0,0 +1,71 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import { initSEO } from '@umituz/web-seo';
+
+export interface DetectionOptions {
+  order?: string[];
+  caches?: string[];
+  lookupLocalStorage?: string;
+  lookupSessionstorage?: string;
+}
+
+export interface SetupI18nOptions {
+  resources: Record<string, { translation: Record<string, unknown> }>;
+  defaultLng?: string;
+  fallbackLng?: string;
+  onInit?: (instance: typeof i18n) => void;
+  detection?: DetectionOptions;
+  seo?: {
+    titleKey: string;
+    descriptionKey: string;
+    defaultImage?: string;
+    twitterHandle?: string;
+  };
+}
+
+/**
+ * Static i18n initialization to simplify main app code.
+ * @description All common configuration including SEO integration is hidden inside this package.
+ */
+export function setupI18n(options: SetupI18nOptions): typeof i18n {
+  const {
+    resources,
+    defaultLng = 'en-US',
+    fallbackLng = 'en-US',
+    onInit,
+    detection = {
+      order: ['localStorage', 'navigator'],
+      caches: ['localStorage'],
+    },
+    seo,
+  } = options;
+
+  i18n
+    .use(LanguageDetector)
+    .use(initReactI18next)
+    .init({
+      resources,
+      lng: defaultLng,
+      fallbackLng,
+      interpolation: {
+        escapeValue: false,
+      },
+      detection,
+    })
+    .then(() => {
+      if (seo) {
+        initSEO({
+          i18n,
+          ...seo,
+        });
+      }
+      if (onInit) onInit(i18n);
+    })
+    .catch((error) => {
+      console.error('Failed to initialize i18n:', error);
+      throw error;
+    });
+
+  return i18n;
+}

package/src/scripts/cli.ts

@@ -6,21 +6,28 @@
 
 import { Command } from "commander";
 import { cliService } from "../infrastructure/services/cli.service.js";
+import type { SyncOptions } from "../infrastructure/services/cli.service.js";
 import chalk from "chalk";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
 
 const program = new Command();
 
 program
   .name("web-loc")
   .description("Localization CLI tool for web applications")
-  .version("1.0.0");
+  .version(packageJson.version);
 
 program
   .command("sync")
   .description("Synchronize missing keys from base language to other languages")
   .option("-d, --locales-dir <dir>", "Directory containing locale files", "src/locales")
   .option("-b, --base-lang <lang>", "Base language code", "en-US")
-  .action(async (options) => {
+  .action(async (options: SyncOptions) => {
     try {
       await cliService.sync(options);
     } catch (error) {
@@ -34,7 +41,8 @@ program
   .description("Automatically translate missing strings using Google Translate")
   .option("-d, --locales-dir <dir>", "Directory containing locale files", "src/locales")
   .option("-b, --base-lang <lang>", "Base language code", "en-US")
-  .action(async (options) => {
+  .option("-f, --force", "Force re-translation of all strings", false)
+  .action(async (options: SyncOptions & { force?: boolean }) => {
     try {
       await cliService.translate(options);
     } catch (error) {

package/dist/domain/entities/translation.entity.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"translation.entity.d.ts","sourceRoot":"","sources":["../../../src/domain/entities/translation.entity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,eAAe,EAAE,CAAC;CACnC"}

package/dist/domain/interfaces/translation-service.interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"translation-service.interface.d.ts","sourceRoot":"","sources":["../../../src/domain/interfaces/translation-service.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,gCAAgC,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACnD,aAAa,IAAI,OAAO,CAAC;IACzB,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrE,cAAc,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1E,eAAe,CACb,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,gBAAgB,EACxB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAC5D,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,sCAAsC,CAAC;AACrD,cAAc,mDAAmD,CAAC;AAClE,cAAc,oDAAoD,CAAC;AACnE,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC"}

package/dist/infrastructure/constants/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/constants/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,wBAAwB,wDAAwD,CAAC;AAE9F,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,eAAe,QAAQ,CAAC;AAErC,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AACjD,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,qBAAqB,UAAU,CAAC"}

package/dist/infrastructure/services/cli.service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/services/cli.service.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,UAAU;IACf,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0D9C,SAAS,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAsD1D;AAED,eAAO,MAAM,UAAU,YAAmB,CAAC"}

package/dist/infrastructure/services/google-translate.service.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"google-translate.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/services/google-translate.service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EACV,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,0DAA0D,CAAC;AAalE,cAAM,sBAAuB,YAAW,mBAAmB;IACzD,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,WAAW,CAA4B;IAE/C,UAAU,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI;IASlD,aAAa,IAAI,OAAO;IAIxB,OAAO,CAAC,iBAAiB;IAQnB,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsDpE,cAAc,CAAC,QAAQ,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyDzE,eAAe,CACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,cAAc,EAAE,MAAM,EACtB,IAAI,SAAK,EACT,KAAK,GAAE,gBAMN,EACD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAC5D,OAAO,CAAC,IAAI,CAAC;YA6DF,gBAAgB;CAkF/B;AAED,eAAO,MAAM,sBAAsB,wBAA+B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/infrastructure/utils/file.util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file.util.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/utils/file.util.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoB7E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAajG"}

package/dist/infrastructure/utils/rate-limit.util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rate-limit.util.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/utils/rate-limit.util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,WAAW;IACtB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,SAAM;IAIpB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAWnC"}

package/dist/infrastructure/utils/text-validator.util.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"text-validator.util.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/utils/text-validator.util.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAKzD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAKnF"}

package/dist/scripts/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/scripts/cli.ts"],"names":[],"mappings":";AAEA;;GAEG"}