@form-engine-ts/translator-google-v3 2.5.1 → 2.7.0

package/README.md

@@ -21,7 +21,8 @@ const translator = createGoogleV3Translator({
   glossaryConfig: {
     glossary: "projects/my-project/locations/us-central1/glossaries/product-terms"
   },
-  labels: { application: "survey" }
+  labels: { application: "survey" },
+  onBatchReport: (report) => console.info(report)
 });
 
 const japanese = await translator.translateText("Thank you", "ja", "en");
@@ -30,3 +31,7 @@ const japanese = await translator.translateText("Thank you", "ja", "en");
 Keep OAuth access tokens on a trusted server. `translateBatch` defaults to at most 250 items and 25,000 UTF-8 bytes per
 request (hard limits: 1,024 items and 30,000 bytes). Network errors, HTTP 429, and HTTP 5xx responses are retried; customize
 batch and retry behavior with `batchLimits` and `retry`.
+
+Blank and whitespace-only inputs are omitted from API requests and restored as empty output strings in their original
+positions. `onBatchReport` receives `totalChunks`, Unicode-code-point `totalCharacters`, aggregate retry attempts, total
+duration, `cacheHitCount`, `cacheMissCount`, and `evictionCount` after each `translateBatch` call.

package/dist/index.cjs

@@ -176,7 +176,10 @@ function createGoogleV3Translator(options) {
         }
       }
       if (response?.ok === true) {
-        return parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0);
+        return {
+          translations: parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0),
+          retryAttempts: attempt
+        };
       }
       const retryable = response === void 0 || response.status === 429 || response.status >= 500 && response.status <= 599;
       if (retryable && attempt < maxRetries) {
@@ -200,11 +203,33 @@ function createGoogleV3Translator(options) {
     }
     const target = requireNonEmpty(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? void 0 : requireNonEmpty(sourceLocale, "sourceLocale");
+    const nonEmptyEntries = texts.flatMap((text, index) => text.trim().length === 0 ? [] : [{ text, index }]);
+    const nonEmptyTexts = nonEmptyEntries.map((entry) => entry.text);
+    const chunks = splitTranslationBatch(nonEmptyTexts, batchLimits);
+    const startedAt = now();
     const translated = [];
-    for (const chunk of splitTranslationBatch(texts, batchLimits)) {
-      translated.push(...await translateChunk(chunk, target, source));
+    let retryAttempts = 0;
+    for (const chunk of chunks) {
+      const result = await translateChunk(chunk, target, source);
+      translated.push(...result.translations);
+      retryAttempts += result.retryAttempts;
     }
-    return translated;
+    const restored = Array.from({ length: texts.length }, () => "");
+    for (const [translatedIndex, entry] of nonEmptyEntries.entries()) {
+      const value = translated[translatedIndex];
+      if (value === void 0) throw new Error("Google Translation Advanced returned an incomplete translation batch.");
+      restored[entry.index] = value;
+    }
+    options.onBatchReport?.({
+      totalChunks: chunks.length,
+      totalCharacters: nonEmptyTexts.reduce((total, text) => total + [...text].length, 0),
+      retryAttempts,
+      durationMs: Math.max(0, now() - startedAt),
+      cacheHitCount: 0,
+      cacheMissCount: nonEmptyTexts.length,
+      evictionCount: 0
+    });
+    return restored;
   };
   return {
     async translateText(text, targetLocale, sourceLocale) {

package/dist/index.d.cts

@@ -21,6 +21,7 @@ interface GoogleV3TranslatorOptions {
     readonly sleep?: (milliseconds: number) => Promise<void>;
     readonly random?: () => number;
     readonly now?: () => number;
+    readonly onBatchReport?: (report: TranslationBatchReport) => void;
 }
 interface BatchSplitLimits {
     readonly maxItems?: number;
@@ -32,7 +33,16 @@ interface RetryConfig {
     readonly baseDelayMs?: number;
     readonly maxDelayMs?: number;
 }
+interface TranslationBatchReport {
+    readonly totalChunks: number;
+    readonly totalCharacters: number;
+    readonly retryAttempts: number;
+    readonly durationMs: number;
+    readonly cacheHitCount: number;
+    readonly cacheMissCount: number;
+    readonly evictionCount: number;
+}
 declare function splitTranslationBatch(texts: readonly string[], limits?: BatchSplitLimits): string[][];
 declare function createGoogleV3Translator(options: GoogleV3TranslatorOptions): AsyncTranslationAdapter;
 
-export { type BatchSplitLimits, type GoogleV3GlossaryConfig, type GoogleV3TranslatorOptions, type RetryConfig, createGoogleV3Translator, splitTranslationBatch };
+export { type BatchSplitLimits, type GoogleV3GlossaryConfig, type GoogleV3TranslatorOptions, type RetryConfig, type TranslationBatchReport, createGoogleV3Translator, splitTranslationBatch };

package/dist/index.d.ts

@@ -21,6 +21,7 @@ interface GoogleV3TranslatorOptions {
     readonly sleep?: (milliseconds: number) => Promise<void>;
     readonly random?: () => number;
     readonly now?: () => number;
+    readonly onBatchReport?: (report: TranslationBatchReport) => void;
 }
 interface BatchSplitLimits {
     readonly maxItems?: number;
@@ -32,7 +33,16 @@ interface RetryConfig {
     readonly baseDelayMs?: number;
     readonly maxDelayMs?: number;
 }
+interface TranslationBatchReport {
+    readonly totalChunks: number;
+    readonly totalCharacters: number;
+    readonly retryAttempts: number;
+    readonly durationMs: number;
+    readonly cacheHitCount: number;
+    readonly cacheMissCount: number;
+    readonly evictionCount: number;
+}
 declare function splitTranslationBatch(texts: readonly string[], limits?: BatchSplitLimits): string[][];
 declare function createGoogleV3Translator(options: GoogleV3TranslatorOptions): AsyncTranslationAdapter;
 
-export { type BatchSplitLimits, type GoogleV3GlossaryConfig, type GoogleV3TranslatorOptions, type RetryConfig, createGoogleV3Translator, splitTranslationBatch };
+export { type BatchSplitLimits, type GoogleV3GlossaryConfig, type GoogleV3TranslatorOptions, type RetryConfig, type TranslationBatchReport, createGoogleV3Translator, splitTranslationBatch };

package/dist/index.js

@@ -151,7 +151,10 @@ function createGoogleV3Translator(options) {
         }
       }
       if (response?.ok === true) {
-        return parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0);
+        return {
+          translations: parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0),
+          retryAttempts: attempt
+        };
       }
       const retryable = response === void 0 || response.status === 429 || response.status >= 500 && response.status <= 599;
       if (retryable && attempt < maxRetries) {
@@ -175,11 +178,33 @@ function createGoogleV3Translator(options) {
     }
     const target = requireNonEmpty(targetLocale, "targetLocale");
     const source = sourceLocale === void 0 ? void 0 : requireNonEmpty(sourceLocale, "sourceLocale");
+    const nonEmptyEntries = texts.flatMap((text, index) => text.trim().length === 0 ? [] : [{ text, index }]);
+    const nonEmptyTexts = nonEmptyEntries.map((entry) => entry.text);
+    const chunks = splitTranslationBatch(nonEmptyTexts, batchLimits);
+    const startedAt = now();
     const translated = [];
-    for (const chunk of splitTranslationBatch(texts, batchLimits)) {
-      translated.push(...await translateChunk(chunk, target, source));
+    let retryAttempts = 0;
+    for (const chunk of chunks) {
+      const result = await translateChunk(chunk, target, source);
+      translated.push(...result.translations);
+      retryAttempts += result.retryAttempts;
     }
-    return translated;
+    const restored = Array.from({ length: texts.length }, () => "");
+    for (const [translatedIndex, entry] of nonEmptyEntries.entries()) {
+      const value = translated[translatedIndex];
+      if (value === void 0) throw new Error("Google Translation Advanced returned an incomplete translation batch.");
+      restored[entry.index] = value;
+    }
+    options.onBatchReport?.({
+      totalChunks: chunks.length,
+      totalCharacters: nonEmptyTexts.reduce((total, text) => total + [...text].length, 0),
+      retryAttempts,
+      durationMs: Math.max(0, now() - startedAt),
+      cacheHitCount: 0,
+      cacheMissCount: nonEmptyTexts.length,
+      evictionCount: 0
+    });
+    return restored;
   };
   return {
     async translateText(text, targetLocale, sourceLocale) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/translator-google-v3",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -40,7 +40,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.5.1"
+    "@form-engine-ts/core": "2.7.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",