@umituz/web-localization 1.0.6 → 1.1.2

package/dist/index.d.ts

@@ -8,4 +8,5 @@ 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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;AACvD,cAAc,2BAA2B,CAAC"}

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/services/cli.service.d.ts

@@ -2,6 +2,7 @@ export interface SyncOptions {
     localesDir?: string;
     sourceDir?: string;
     baseLang?: string;
+    force?: boolean;
 }
 export declare class CLIService {
     sync(options?: SyncOptions): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"cli.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/services/cli.service.ts"],"names":[],"mappings":"AAWA,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;IAsD9C,SAAS,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAsD1D;AAED,eAAO,MAAM,UAAU,YAAmB,CAAC"}
+{"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;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;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;CAuD1D;AAED,eAAO,MAAM,UAAU,YAAmB,CAAC"}

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

@@ -34,7 +34,8 @@ export class CLIService {
                         result[key] = syncObject(source[key], target[key] || {});
                     }
                     else if (target[key] === undefined) {
-                        result[key] = source[key];
+                        // Let empty string indicate untranslated state
+                        result[key] = typeof source[key] === "string" ? "" : source[key];
                     }
                 }
                 // Remove extra keys
@@ -80,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,7 +12,7 @@ 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;

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

@@ -1 +1 @@
-{"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;CAuC/B;AAED,eAAO,MAAM,sBAAsB,wBAA+B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"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,EAC7D,KAAK,UAAQ,GACZ,OAAO,CAAC,IAAI,CAAC;YAiEF,gBAAgB;CAkF/B;AAED,eAAO,MAAM,sBAAsB,wBAA+B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

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,41 +161,83 @@ 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++;
+                    }
                 }
             }
         }
     }
-    async callTranslateAPI(text, targetLanguage, sourceLanguage) {
+    async callTranslateAPI(text, targetLanguage, sourceLanguage, retries = 3, backoffMs = 2000) {
+        // 1. Variable Protection (Extract {{variables}})
+        const varMap = new Map();
+        let counter = 0;
+        // Find all {{something}} patterns
+        let safeText = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
+            const placeholder = `_VAR${counter}_`; // Using a simple token less likely to be split
+            varMap.set(placeholder, match);
+            counter++;
+            return placeholder;
+        });
         const timeout = this.config?.timeout || DEFAULT_TIMEOUT;
-        const encodedText = encodeURIComponent(text);
+        const encodedText = encodeURIComponent(safeText);
         const url = `${GOOGLE_TRANSLATE_API_URL}?client=gtx&sl=${sourceLanguage}&tl=${targetLanguage}&dt=t&q=${encodedText}`;
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeout);
-        try {
-            const response = await fetch(url, {
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                throw new Error(`API request failed: ${response.status}`);
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            try {
+                const response = await fetch(url, {
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    if (response.status === 429 || response.status >= 500) {
+                        if (attempt < retries) {
+                            clearTimeout(timeoutId);
+                            // Exponential backoff
+                            const delay = backoffMs * Math.pow(2, attempt);
+                            await new Promise(resolve => setTimeout(resolve, delay));
+                            continue;
+                        }
+                    }
+                    throw new Error(`API request failed: ${response.status}`);
+                }
+                const data = await response.json();
+                let translatedStr = safeText;
+                if (Array.isArray(data) &&
+                    data.length > 0 &&
+                    Array.isArray(data[0]) &&
+                    data[0].length > 0 &&
+                    typeof data[0][0][0] === "string") {
+                    translatedStr = data[0].map((item) => item[0]).join('');
+                }
+                // 2. Re-inject Variables
+                if (varMap.size > 0) {
+                    // Sometimes Google adds spaces, like _VAR0_ -> _ VAR0 _
+                    for (const [placeholder, originalVar] of varMap.entries()) {
+                        const regex = new RegExp(placeholder.split('').join('\\s*'), 'g');
+                        translatedStr = translatedStr.replace(regex, originalVar);
+                    }
+                }
+                return translatedStr;
             }
-            const data = await response.json();
-            if (Array.isArray(data) &&
-                data.length > 0 &&
-                Array.isArray(data[0]) &&
-                data[0].length > 0 &&
-                Array.isArray(data[0][0]) &&
-                typeof data[0][0][0] === "string") {
-                return data[0][0][0];
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (attempt === retries) {
+                    throw error;
+                }
+                const delay = backoffMs * Math.pow(2, attempt);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+            finally {
+                clearTimeout(timeoutId);
             }
-            return text;
-        }
-        finally {
-            clearTimeout(timeoutId);
         }
+        return text;
     }
 }
 export const googleTranslateService = new GoogleTranslateService();

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

@@ -1 +1 @@
-{"version":3,"file":"file.util.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/utils/file.util.ts"],"names":[],"mappings":"AAGA;;;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"}
+{"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/text-validator.util.js

@@ -26,9 +26,8 @@ export function shouldSkipWord(text) {
 export function needsTranslation(targetValue, sourceValue) {
     if (typeof targetValue !== "string")
         return true;
-    if (targetValue.trim().length === 0)
-        return true;
-    if (targetValue === sourceValue && !/^\d+$/.test(sourceValue))
-        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
     return false;
 }

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

@@ -0,0 +1,23 @@
+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;
+//# sourceMappingURL=i18n.setup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.setup.d.ts","sourceRoot":"","sources":["../../src/integrations/i18n.setup.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,SAAS,CAAC;AAK3B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,IAAI,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAE,GAAG,CAAC;IAChB,GAAG,CAAC,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,0BAoClD;AAED,eAAe,IAAI,CAAC"}

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.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.0.6",
+  "version": "1.1.2",
   "description": "Google Translate integrated localization package for web applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -13,6 +13,7 @@
     ".": "./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": {
@@ -35,16 +36,21 @@
     "access": "public"
   },
   "dependencies": {
-    "commander": "^12.0.0",
     "chalk": "^5.3.0",
-    "dotenv": "^16.4.5"
+    "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",
-    "typescript": "^5.4.5",
-    "eslint": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^7.7.0",
     "@typescript-eslint/parser": "^7.7.0",
-    "@typescript-eslint/eslint-plugin": "^7.7.0"
+    "eslint": "^8.57.0",
+    "typescript": "^5.4.5"
   },
   "files": [
     "src",

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/services/cli.service.ts

@@ -12,6 +12,7 @@ export interface SyncOptions {
   localesDir?: string;
   sourceDir?: string;
   baseLang?: string;
+  force?: boolean;
 }
 
 export class CLIService {
@@ -52,7 +53,8 @@ export class CLIService {
               (target[key] as Record<string, unknown>) || {}
             );
           } else if (target[key] === undefined) {
-            result[key] = source[key];
+             // Let empty string indicate untranslated state
+            result[key] = typeof source[key] === "string" ? "" : source[key];
           }
         }
         // Remove extra keys
@@ -113,7 +115,8 @@ export class CLIService {
         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

@@ -172,7 +172,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 +197,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++;
@@ -226,8 +228,11 @@ class GoogleTranslateService implements ITranslationService {
 
           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++;
           }
         }
       }
@@ -237,41 +242,84 @@ class GoogleTranslateService implements ITranslationService {
   private async callTranslateAPI(
     text: string,
     targetLanguage: string,
-    sourceLanguage: string
+    sourceLanguage: string,
+    retries = 3,
+    backoffMs = 2000
   ): Promise<string> {
+    // 1. Variable Protection (Extract {{variables}})
+    const varMap = new Map<string, string>();
+    let counter = 0;
+    
+    // Find all {{something}} patterns
+    let safeText = text.replace(/\{\{([^}]+)\}\}/g, (match) => {
+      const placeholder = `_VAR${counter}_`; // Using a simple token less likely to be split
+      varMap.set(placeholder, match);
+      counter++;
+      return placeholder;
+    });
+
     const timeout = this.config?.timeout || DEFAULT_TIMEOUT;
-    const encodedText = encodeURIComponent(text);
+    const encodedText = encodeURIComponent(safeText);
     const url = `${GOOGLE_TRANSLATE_API_URL}?client=gtx&sl=${sourceLanguage}&tl=${targetLanguage}&dt=t&q=${encodedText}`;
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      try {
+        const response = await fetch(url, {
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          if (response.status === 429 || response.status >= 500) {
+            if (attempt < retries) {
+              clearTimeout(timeoutId);
+              // Exponential backoff
+              const delay = backoffMs * Math.pow(2, attempt);
+              await new Promise(resolve => setTimeout(resolve, delay));
+              continue;
+            }
+          }
+          throw new Error(`API request failed: ${response.status}`);
+        }
 
-    try {
-      const response = await fetch(url, {
-        signal: controller.signal,
-      });
+        const data = await response.json();
 
-      if (!response.ok) {
-        throw new Error(`API request failed: ${response.status}`);
-      }
+        let translatedStr = safeText;
+        if (
+          Array.isArray(data) &&
+          data.length > 0 &&
+          Array.isArray(data[0]) &&
+          data[0].length > 0 &&
+        typeof data[0][0][0] === "string"
+        ) {
+          translatedStr = data[0].map((item: any) => item[0]).join('');
+        }
 
-      const data = await response.json();
+        // 2. Re-inject Variables
+        if (varMap.size > 0) {
+          // Sometimes Google adds spaces, like _VAR0_ -> _ VAR0 _
+          for (const [placeholder, originalVar] of varMap.entries()) {
+            const regex = new RegExp(placeholder.split('').join('\\s*'), 'g');
+            translatedStr = translatedStr.replace(regex, originalVar);
+          }
+        }
 
-      if (
-        Array.isArray(data) &&
-        data.length > 0 &&
-        Array.isArray(data[0]) &&
-        data[0].length > 0 &&
-        Array.isArray(data[0][0]) &&
-        typeof data[0][0][0] === "string"
-      ) {
-        return data[0][0][0];
+        return translatedStr;
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (attempt === retries) {
+          throw error;
+        }
+        const delay = backoffMs * Math.pow(2, attempt);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      } finally {
+        clearTimeout(timeoutId);
       }
-
-      return text;
-    } finally {
-      clearTimeout(timeoutId);
     }
+    
+    return text;
   }
 }
 

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

@@ -25,7 +25,7 @@ export function shouldSkipWord(text: string): boolean {
  */
 export function needsTranslation(targetValue: unknown, sourceValue: string): boolean {
   if (typeof targetValue !== "string") return true;
-  if (targetValue.trim().length === 0) return true;
-  if (targetValue === sourceValue && !/^\d+$/.test(sourceValue)) 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
   return false;
 }

package/src/integrations/i18n.setup.ts

@@ -0,0 +1,62 @@
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import { initSEO } from '@umituz/web-seo';
+
+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 function setupI18n(options: SetupI18nOptions) {
+  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/src/scripts/cli.ts

@@ -34,6 +34,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);