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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nitta-a
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @form-engine-ts/translator-google-v3
+
+Google Cloud Translation Advanced v3 adapter for form-engine-ts. It supports regional endpoints, glossaries, labels,
+UTF-8-aware batch chunking, and transient network/HTTP retry with `Retry-After`-aware full jitter.
+
+## Install
+
+```bash
+pnpm add @form-engine-ts/core @form-engine-ts/translator-google-v3
+```
+
+## Quick start
+
+```ts
+import { createGoogleV3Translator } from "@form-engine-ts/translator-google-v3";
+
+const translator = createGoogleV3Translator({
+  projectId: "my-project",
+  location: "us-central1",
+  getAccessToken: () => getGoogleAccessToken(),
+  glossaryConfig: {
+    glossary: "projects/my-project/locations/us-central1/glossaries/product-terms"
+  },
+  labels: { application: "survey" }
+});
+
+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`.

package/dist/index.cjs

@@ -0,0 +1,224 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createGoogleV3Translator: () => createGoogleV3Translator,
+  splitTranslationBatch: () => splitTranslationBatch
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_ENDPOINT = "https://translation.googleapis.com/v3";
+var DEFAULT_MAX_ITEMS = 250;
+var DEFAULT_MAX_CHARACTERS = 25e3;
+var HARD_MAX_ITEMS = 1024;
+var HARD_MAX_CHARACTERS = 3e4;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireNonEmpty(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0)
+    throw new TypeError(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+function nonNegativeInteger(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) throw new TypeError(`${name} must be a non-negative integer.`);
+  return resolved;
+}
+function positiveInteger(value, fallback, name) {
+  const resolved = nonNegativeInteger(value, fallback, name);
+  if (resolved < 1) throw new TypeError(`${name} must be greater than zero.`);
+  return resolved;
+}
+function splitTranslationBatch(texts, limits = {}) {
+  if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
+    throw new TypeError("texts must be an array of strings.");
+  }
+  const maxItems = positiveInteger(limits.maxItems, DEFAULT_MAX_ITEMS, "maxItems");
+  const maxCharacters = positiveInteger(limits.maxCharacters, DEFAULT_MAX_CHARACTERS, "maxCharacters");
+  if (maxItems > HARD_MAX_ITEMS) throw new TypeError(`maxItems cannot exceed ${HARD_MAX_ITEMS}.`);
+  if (maxCharacters > HARD_MAX_CHARACTERS) {
+    throw new TypeError(`maxCharacters cannot exceed ${HARD_MAX_CHARACTERS}.`);
+  }
+  const encoder = new TextEncoder();
+  const chunks = [];
+  let chunk = [];
+  let chunkBytes = 0;
+  for (const text of texts) {
+    const textBytes = encoder.encode(text).length;
+    if (textBytes > maxCharacters) {
+      throw new TypeError(`A text item uses ${textBytes} UTF-8 bytes; maxCharacters is ${maxCharacters}.`);
+    }
+    if (chunk.length > 0 && (chunk.length >= maxItems || chunkBytes + textBytes > maxCharacters)) {
+      chunks.push(chunk);
+      chunk = [];
+      chunkBytes = 0;
+    }
+    chunk.push(text);
+    chunkBytes += textBytes;
+  }
+  if (chunk.length > 0) chunks.push(chunk);
+  return chunks;
+}
+function endpoint(value) {
+  try {
+    return new URL(value ?? DEFAULT_ENDPOINT).toString().replace(/\/$/, "");
+  } catch (cause) {
+    throw new TypeError("apiEndpoint must be a valid absolute URL.", { cause });
+  }
+}
+function parseTranslations(body, expected, useGlossary) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (cause) {
+    throw new Error("Google Translation Advanced returned invalid JSON.", { cause });
+  }
+  const preferredKey = useGlossary ? "glossaryTranslations" : "translations";
+  const fallbackKey = useGlossary ? "translations" : "glossaryTranslations";
+  const values = isRecord(parsed) ? Array.isArray(parsed[preferredKey]) ? parsed[preferredKey] : parsed[fallbackKey] : void 0;
+  if (!Array.isArray(values)) throw new Error("Google Translation Advanced response is missing translations.");
+  if (values.length !== expected) {
+    throw new Error(`Google Translation Advanced returned ${values.length} translations for ${expected} texts.`);
+  }
+  return values.map((value, index) => {
+    if (!isRecord(value) || typeof value.translatedText !== "string") {
+      throw new Error(`Google Translation Advanced result at index ${index} is invalid.`);
+    }
+    return value.translatedText;
+  });
+}
+function validateLabels(labels) {
+  if (labels === void 0) return void 0;
+  for (const [key, value] of Object.entries(labels)) {
+    requireNonEmpty(key, "label key");
+    requireNonEmpty(value, `label ${key}`);
+  }
+  return { ...labels };
+}
+function retryAfterMilliseconds(value, now) {
+  if (value === null) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? Math.max(0, timestamp - now()) : void 0;
+}
+function createGoogleV3Translator(options) {
+  const projectId = requireNonEmpty(options?.projectId, "projectId");
+  const location = requireNonEmpty(options.location ?? "global", "location");
+  if (typeof options.getAccessToken !== "function") throw new TypeError("getAccessToken must be a function.");
+  const apiEndpoint = endpoint(options.apiEndpoint);
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function")
+    throw new Error("Fetch is unavailable. Pass fetchFn when creating the translator.");
+  const batchLimits = {
+    maxItems: options.batchLimits?.maxItems ?? options.maxBatchSize ?? DEFAULT_MAX_ITEMS,
+    maxCharacters: options.batchLimits?.maxCharacters ?? DEFAULT_MAX_CHARACTERS
+  };
+  const maxRetries = nonNegativeInteger(options.retry?.maxRetries ?? options.maxRetries, 4, "maxRetries");
+  const retryBaseDelayMs = nonNegativeInteger(
+    options.retry?.baseDelayMs ?? options.retryBaseDelayMs,
+    500,
+    "baseDelayMs"
+  );
+  const maxRetryDelayMs = nonNegativeInteger(
+    options.retry?.maxDelayMs ?? options.maxRetryDelayMs,
+    1e4,
+    "maxDelayMs"
+  );
+  const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const labels = validateLabels(options.labels);
+  const glossaryConfig = options.glossaryConfig === void 0 ? void 0 : {
+    glossary: requireNonEmpty(options.glossaryConfig.glossary, "glossaryConfig.glossary"),
+    ...options.glossaryConfig.ignoreCase === void 0 ? {} : { ignoreCase: options.glossaryConfig.ignoreCase }
+  };
+  const requestUrl = `${apiEndpoint}/projects/${encodeURIComponent(projectId)}/locations/${encodeURIComponent(location)}:translateText`;
+  const translateChunk = async (texts, targetLocale, sourceLocale) => {
+    const token = requireNonEmpty(await options.getAccessToken(), "accessToken");
+    const body = JSON.stringify({
+      contents: texts,
+      mimeType: "text/plain",
+      targetLanguageCode: targetLocale,
+      ...sourceLocale === void 0 ? {} : { sourceLanguageCode: sourceLocale },
+      ...glossaryConfig === void 0 ? {} : { glossaryConfig },
+      ...labels === void 0 ? {} : { labels }
+    });
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      try {
+        response = await fetchImpl(requestUrl, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+          body
+        });
+      } catch (cause) {
+        if (attempt >= maxRetries) {
+          throw new Error("Google Translation Advanced request failed before receiving an HTTP response.", { cause });
+        }
+      }
+      if (response?.ok === true) {
+        return parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0);
+      }
+      const retryable = response === void 0 || response.status === 429 || response.status >= 500 && response.status <= 599;
+      if (retryable && attempt < maxRetries) {
+        const retryAfter = response === void 0 ? void 0 : retryAfterMilliseconds(response.headers.get("retry-after"), now);
+        if (response !== void 0) await response.text();
+        const exponentialCap = Math.min(maxRetryDelayMs, retryBaseDelayMs * 2 ** attempt);
+        const jitter = Math.floor(random() * exponentialCap);
+        await sleep(Math.max(retryAfter ?? 0, jitter));
+        continue;
+      }
+      if (response === void 0) throw new Error("Google Translation Advanced request failed.");
+      const detail = (await response.text()).replaceAll(token, "[redacted]");
+      throw new Error(
+        `Google Translation Advanced request failed with HTTP ${response.status}${detail.length === 0 ? "." : `: ${detail}`}`
+      );
+    }
+  };
+  const translateBatch = async (texts, targetLocale, sourceLocale) => {
+    if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
+      throw new TypeError("texts must be an array of strings.");
+    }
+    const target = requireNonEmpty(targetLocale, "targetLocale");
+    const source = sourceLocale === void 0 ? void 0 : requireNonEmpty(sourceLocale, "sourceLocale");
+    const translated = [];
+    for (const chunk of splitTranslationBatch(texts, batchLimits)) {
+      translated.push(...await translateChunk(chunk, target, source));
+    }
+    return translated;
+  };
+  return {
+    async translateText(text, targetLocale, sourceLocale) {
+      if (typeof text !== "string") throw new TypeError("text must be a string.");
+      const translated = await translateBatch([text], targetLocale, sourceLocale);
+      const value = translated[0];
+      if (value === void 0) throw new Error("Google Translation Advanced returned no translation.");
+      return value;
+    },
+    translateBatch
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGoogleV3Translator,
+  splitTranslationBatch
+});

package/dist/index.d.cts

@@ -0,0 +1,38 @@
+import { AsyncTranslationAdapter } from '@form-engine-ts/core';
+
+interface GoogleV3GlossaryConfig {
+    readonly glossary: string;
+    readonly ignoreCase?: boolean;
+}
+interface GoogleV3TranslatorOptions {
+    readonly projectId: string;
+    readonly location?: string;
+    readonly getAccessToken: () => Promise<string> | string;
+    readonly glossaryConfig?: GoogleV3GlossaryConfig;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly fetchFn?: typeof fetch;
+    readonly apiEndpoint?: string;
+    readonly batchLimits?: BatchSplitLimits;
+    readonly retry?: RetryConfig;
+    readonly maxBatchSize?: number;
+    readonly maxRetries?: number;
+    readonly retryBaseDelayMs?: number;
+    readonly maxRetryDelayMs?: number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+interface BatchSplitLimits {
+    readonly maxItems?: number;
+    /** UTF-8 bytes across all text items in a request. */
+    readonly maxCharacters?: number;
+}
+interface RetryConfig {
+    readonly maxRetries?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: 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 };

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { AsyncTranslationAdapter } from '@form-engine-ts/core';
+
+interface GoogleV3GlossaryConfig {
+    readonly glossary: string;
+    readonly ignoreCase?: boolean;
+}
+interface GoogleV3TranslatorOptions {
+    readonly projectId: string;
+    readonly location?: string;
+    readonly getAccessToken: () => Promise<string> | string;
+    readonly glossaryConfig?: GoogleV3GlossaryConfig;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly fetchFn?: typeof fetch;
+    readonly apiEndpoint?: string;
+    readonly batchLimits?: BatchSplitLimits;
+    readonly retry?: RetryConfig;
+    readonly maxBatchSize?: number;
+    readonly maxRetries?: number;
+    readonly retryBaseDelayMs?: number;
+    readonly maxRetryDelayMs?: number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly random?: () => number;
+    readonly now?: () => number;
+}
+interface BatchSplitLimits {
+    readonly maxItems?: number;
+    /** UTF-8 bytes across all text items in a request. */
+    readonly maxCharacters?: number;
+}
+interface RetryConfig {
+    readonly maxRetries?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: 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 };

package/dist/index.js

@@ -0,0 +1,198 @@
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://translation.googleapis.com/v3";
+var DEFAULT_MAX_ITEMS = 250;
+var DEFAULT_MAX_CHARACTERS = 25e3;
+var HARD_MAX_ITEMS = 1024;
+var HARD_MAX_CHARACTERS = 3e4;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireNonEmpty(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0)
+    throw new TypeError(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+function nonNegativeInteger(value, fallback, name) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 0) throw new TypeError(`${name} must be a non-negative integer.`);
+  return resolved;
+}
+function positiveInteger(value, fallback, name) {
+  const resolved = nonNegativeInteger(value, fallback, name);
+  if (resolved < 1) throw new TypeError(`${name} must be greater than zero.`);
+  return resolved;
+}
+function splitTranslationBatch(texts, limits = {}) {
+  if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
+    throw new TypeError("texts must be an array of strings.");
+  }
+  const maxItems = positiveInteger(limits.maxItems, DEFAULT_MAX_ITEMS, "maxItems");
+  const maxCharacters = positiveInteger(limits.maxCharacters, DEFAULT_MAX_CHARACTERS, "maxCharacters");
+  if (maxItems > HARD_MAX_ITEMS) throw new TypeError(`maxItems cannot exceed ${HARD_MAX_ITEMS}.`);
+  if (maxCharacters > HARD_MAX_CHARACTERS) {
+    throw new TypeError(`maxCharacters cannot exceed ${HARD_MAX_CHARACTERS}.`);
+  }
+  const encoder = new TextEncoder();
+  const chunks = [];
+  let chunk = [];
+  let chunkBytes = 0;
+  for (const text of texts) {
+    const textBytes = encoder.encode(text).length;
+    if (textBytes > maxCharacters) {
+      throw new TypeError(`A text item uses ${textBytes} UTF-8 bytes; maxCharacters is ${maxCharacters}.`);
+    }
+    if (chunk.length > 0 && (chunk.length >= maxItems || chunkBytes + textBytes > maxCharacters)) {
+      chunks.push(chunk);
+      chunk = [];
+      chunkBytes = 0;
+    }
+    chunk.push(text);
+    chunkBytes += textBytes;
+  }
+  if (chunk.length > 0) chunks.push(chunk);
+  return chunks;
+}
+function endpoint(value) {
+  try {
+    return new URL(value ?? DEFAULT_ENDPOINT).toString().replace(/\/$/, "");
+  } catch (cause) {
+    throw new TypeError("apiEndpoint must be a valid absolute URL.", { cause });
+  }
+}
+function parseTranslations(body, expected, useGlossary) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (cause) {
+    throw new Error("Google Translation Advanced returned invalid JSON.", { cause });
+  }
+  const preferredKey = useGlossary ? "glossaryTranslations" : "translations";
+  const fallbackKey = useGlossary ? "translations" : "glossaryTranslations";
+  const values = isRecord(parsed) ? Array.isArray(parsed[preferredKey]) ? parsed[preferredKey] : parsed[fallbackKey] : void 0;
+  if (!Array.isArray(values)) throw new Error("Google Translation Advanced response is missing translations.");
+  if (values.length !== expected) {
+    throw new Error(`Google Translation Advanced returned ${values.length} translations for ${expected} texts.`);
+  }
+  return values.map((value, index) => {
+    if (!isRecord(value) || typeof value.translatedText !== "string") {
+      throw new Error(`Google Translation Advanced result at index ${index} is invalid.`);
+    }
+    return value.translatedText;
+  });
+}
+function validateLabels(labels) {
+  if (labels === void 0) return void 0;
+  for (const [key, value] of Object.entries(labels)) {
+    requireNonEmpty(key, "label key");
+    requireNonEmpty(value, `label ${key}`);
+  }
+  return { ...labels };
+}
+function retryAfterMilliseconds(value, now) {
+  if (value === null) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1e3;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? Math.max(0, timestamp - now()) : void 0;
+}
+function createGoogleV3Translator(options) {
+  const projectId = requireNonEmpty(options?.projectId, "projectId");
+  const location = requireNonEmpty(options.location ?? "global", "location");
+  if (typeof options.getAccessToken !== "function") throw new TypeError("getAccessToken must be a function.");
+  const apiEndpoint = endpoint(options.apiEndpoint);
+  const fetchImpl = options.fetchFn ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function")
+    throw new Error("Fetch is unavailable. Pass fetchFn when creating the translator.");
+  const batchLimits = {
+    maxItems: options.batchLimits?.maxItems ?? options.maxBatchSize ?? DEFAULT_MAX_ITEMS,
+    maxCharacters: options.batchLimits?.maxCharacters ?? DEFAULT_MAX_CHARACTERS
+  };
+  const maxRetries = nonNegativeInteger(options.retry?.maxRetries ?? options.maxRetries, 4, "maxRetries");
+  const retryBaseDelayMs = nonNegativeInteger(
+    options.retry?.baseDelayMs ?? options.retryBaseDelayMs,
+    500,
+    "baseDelayMs"
+  );
+  const maxRetryDelayMs = nonNegativeInteger(
+    options.retry?.maxDelayMs ?? options.maxRetryDelayMs,
+    1e4,
+    "maxDelayMs"
+  );
+  const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const labels = validateLabels(options.labels);
+  const glossaryConfig = options.glossaryConfig === void 0 ? void 0 : {
+    glossary: requireNonEmpty(options.glossaryConfig.glossary, "glossaryConfig.glossary"),
+    ...options.glossaryConfig.ignoreCase === void 0 ? {} : { ignoreCase: options.glossaryConfig.ignoreCase }
+  };
+  const requestUrl = `${apiEndpoint}/projects/${encodeURIComponent(projectId)}/locations/${encodeURIComponent(location)}:translateText`;
+  const translateChunk = async (texts, targetLocale, sourceLocale) => {
+    const token = requireNonEmpty(await options.getAccessToken(), "accessToken");
+    const body = JSON.stringify({
+      contents: texts,
+      mimeType: "text/plain",
+      targetLanguageCode: targetLocale,
+      ...sourceLocale === void 0 ? {} : { sourceLanguageCode: sourceLocale },
+      ...glossaryConfig === void 0 ? {} : { glossaryConfig },
+      ...labels === void 0 ? {} : { labels }
+    });
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      try {
+        response = await fetchImpl(requestUrl, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+          body
+        });
+      } catch (cause) {
+        if (attempt >= maxRetries) {
+          throw new Error("Google Translation Advanced request failed before receiving an HTTP response.", { cause });
+        }
+      }
+      if (response?.ok === true) {
+        return parseTranslations(await response.text(), texts.length, glossaryConfig !== void 0);
+      }
+      const retryable = response === void 0 || response.status === 429 || response.status >= 500 && response.status <= 599;
+      if (retryable && attempt < maxRetries) {
+        const retryAfter = response === void 0 ? void 0 : retryAfterMilliseconds(response.headers.get("retry-after"), now);
+        if (response !== void 0) await response.text();
+        const exponentialCap = Math.min(maxRetryDelayMs, retryBaseDelayMs * 2 ** attempt);
+        const jitter = Math.floor(random() * exponentialCap);
+        await sleep(Math.max(retryAfter ?? 0, jitter));
+        continue;
+      }
+      if (response === void 0) throw new Error("Google Translation Advanced request failed.");
+      const detail = (await response.text()).replaceAll(token, "[redacted]");
+      throw new Error(
+        `Google Translation Advanced request failed with HTTP ${response.status}${detail.length === 0 ? "." : `: ${detail}`}`
+      );
+    }
+  };
+  const translateBatch = async (texts, targetLocale, sourceLocale) => {
+    if (!Array.isArray(texts) || texts.some((text) => typeof text !== "string")) {
+      throw new TypeError("texts must be an array of strings.");
+    }
+    const target = requireNonEmpty(targetLocale, "targetLocale");
+    const source = sourceLocale === void 0 ? void 0 : requireNonEmpty(sourceLocale, "sourceLocale");
+    const translated = [];
+    for (const chunk of splitTranslationBatch(texts, batchLimits)) {
+      translated.push(...await translateChunk(chunk, target, source));
+    }
+    return translated;
+  };
+  return {
+    async translateText(text, targetLocale, sourceLocale) {
+      if (typeof text !== "string") throw new TypeError("text must be a string.");
+      const translated = await translateBatch([text], targetLocale, sourceLocale);
+      const value = translated[0];
+      if (value === void 0) throw new Error("Google Translation Advanced returned no translation.");
+      return value;
+    },
+    translateBatch
+  };
+}
+export {
+  createGoogleV3Translator,
+  splitTranslationBatch
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@form-engine-ts/translator-google-v3",
+  "version": "2.5.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitta-a/form-engine-ts.git",
+    "directory": "packages/translator-google-v3"
+  },
+  "bugs": {
+    "url": "https://github.com/nitta-a/form-engine-ts/issues"
+  },
+  "homepage": "https://github.com/nitta-a/form-engine-ts#readme",
+  "keywords": [
+    "form",
+    "translation",
+    "google-cloud",
+    "translation-advanced",
+    "translator",
+    "typescript"
+  ],
+  "dependencies": {
+    "@form-engine-ts/core": "2.5.1"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",
+    "check": "biome check . && tsc --noEmit",
+    "test": "vitest run --globals",
+    "typecheck": "tsc --noEmit"
+  }
+}