scribe-cms 0.0.12 → 0.0.13

package/dist/cli/index.cjs

@@ -76,6 +76,8 @@ function addColumnIfMissing(db, table, column, ddlType) {
   }
 }
 function readSchemaVersion(db) {
+  const metaTable = db.prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'`).get();
+  if (!metaTable) return 0;
   const row = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
   return row ? Number.parseInt(row.value, 10) || 0 : 0;
 }
@@ -100,7 +102,7 @@ var SCHEMA_VERSION, MIGRATIONS;
 var init_sqlite = __esm({
   "src/storage/sqlite.ts"() {
     init_cjs_shims();
-    SCHEMA_VERSION = 4;
+    SCHEMA_VERSION = 5;
     MIGRATIONS = [
       `CREATE TABLE IF NOT EXISTS meta (
     key TEXT PRIMARY KEY,
@@ -148,7 +150,30 @@ var init_sqlite = __esm({
     UNIQUE (content_type, en_slug, en_hash)
   )`,
       `CREATE INDEX IF NOT EXISTS idx_en_snapshots_lookup
-    ON en_snapshots(content_type, en_slug, created_at DESC)`
+    ON en_snapshots(content_type, en_slug, created_at DESC)`,
+      `CREATE TABLE IF NOT EXISTS translation_batch_jobs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_name TEXT NOT NULL UNIQUE,
+    model TEXT NOT NULL,
+    display_model TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    state TEXT NOT NULL,
+    completed_at TEXT
+  )`,
+      `CREATE TABLE IF NOT EXISTS translation_batch_items (
+    job_id INTEGER NOT NULL,
+    request_index INTEGER NOT NULL,
+    content_type TEXT NOT NULL,
+    en_slug TEXT NOT NULL,
+    locale TEXT NOT NULL,
+    en_hash TEXT NOT NULL,
+    snapshot_id INTEGER NOT NULL,
+    status TEXT NOT NULL,
+    error TEXT,
+    PRIMARY KEY (job_id, request_index)
+  )`,
+      `CREATE INDEX IF NOT EXISTS idx_batch_items_status
+    ON translation_batch_items(status)`
     ];
   }
 });
@@ -190,26 +215,6 @@ function getRelationTarget(schema) {
   }
   return null;
 }
-function unwrapSchema(schema) {
-  let current = schema;
-  for (let i = 0; i < 8; i++) {
-    const anySchema = current;
-    if (typeof anySchema.unwrap === "function") {
-      current = anySchema.unwrap();
-      continue;
-    }
-    if (typeof anySchema.removeDefault === "function") {
-      current = anySchema.removeDefault();
-      continue;
-    }
-    if (anySchema._def?.innerType) {
-      current = anySchema._def.innerType;
-      continue;
-    }
-    break;
-  }
-  return current;
-}
 function peelOptionalWrappers(schema) {
   let current = schema;
   for (let i = 0; i < 8; i++) {
@@ -355,6 +360,39 @@ function resolveConfig(input, baseDir) {
   if (localeRouting.strategy === "search-param" && !localeRouting.param) {
     throw new Error('scribe config: localeRouting search-param requires a "param" name');
   }
+  const localeFallbacks = {};
+  for (const [locale, chain] of Object.entries(raw.localeFallbacks ?? {})) {
+    if (!raw.locales.includes(locale)) {
+      throw new Error(
+        `scribe config: localeFallbacks key "${locale}" is not in locales [${raw.locales.join(", ")}]`
+      );
+    }
+    const seen = /* @__PURE__ */ new Set();
+    for (const fallback of chain) {
+      if (!raw.locales.includes(fallback)) {
+        throw new Error(
+          `scribe config: localeFallbacks["${locale}"] entry "${fallback}" is not in locales [${raw.locales.join(", ")}]`
+        );
+      }
+      if (fallback === locale) {
+        throw new Error(
+          `scribe config: localeFallbacks["${locale}"] must not contain its own key "${locale}"`
+        );
+      }
+      if (fallback === defaultLocale) {
+        throw new Error(
+          `scribe config: localeFallbacks["${locale}"] must not contain the defaultLocale "${defaultLocale}" \u2014 it is always the final fallback; remove it`
+        );
+      }
+      if (seen.has(fallback)) {
+        throw new Error(
+          `scribe config: localeFallbacks["${locale}"] contains duplicate entry "${fallback}"`
+        );
+      }
+      seen.add(fallback);
+    }
+    localeFallbacks[locale] = [...chain];
+  }
   const projectRoot = path3__default.default.resolve(baseDir ?? process.cwd(), raw.rootDir);
   const contentRoot = path3__default.default.resolve(projectRoot, raw.contentDir ?? "content");
   const storePath = path3__default.default.resolve(projectRoot, raw.store ?? ".scribe/store.sqlite");
@@ -384,6 +422,7 @@ function resolveConfig(input, baseDir) {
     defaultLocale,
     localeRouting,
     localePresets: raw.localePresets,
+    localeFallbacks,
     translate: raw.translate,
     types
   };
@@ -399,6 +438,12 @@ init_cjs_shims();
 
 // src/core/introspect-schema.ts
 init_cjs_shims();
+function getArrayElement(schema) {
+  if (schema instanceof Object && "element" in schema && schema._def?.type === "array") {
+    return schema.element;
+  }
+  return null;
+}
 function introspectSchema(schema, prefix = []) {
   const relation = getRelationTarget(schema);
   if (relation && prefix.length > 0) {
@@ -412,7 +457,10 @@ function introspectSchema(schema, prefix = []) {
       }
     ];
   }
-  const base = unwrapSchema(schema);
+  if (prefix.length > 0 && getFieldKind(schema) === "translatable") {
+    return [{ path: prefix, kind: "translatable" }];
+  }
+  const base = peelOptionalWrappers(schema);
   if (base instanceof Object && "shape" in base) {
     const shape = base.shape;
     const fields = [];
@@ -421,9 +469,9 @@ function introspectSchema(schema, prefix = []) {
     }
     return fields;
   }
-  if (base instanceof Object && "element" in base) {
-    const element = base.element;
-    const elementBase = unwrapSchema(element);
+  const element = getArrayElement(base);
+  if (element) {
+    const elementBase = peelOptionalWrappers(element);
     if (elementBase instanceof Object && "shape" in elementBase) {
       const shape = elementBase.shape;
       const fields = [];
@@ -435,15 +483,48 @@ function introspectSchema(schema, prefix = []) {
   }
   return [{ path: prefix, kind: getFieldKind(schema) }];
 }
-function extractByPaths(data, paths) {
-  const out = {};
+function buildPathTrie(paths) {
+  const root = { leaf: false, children: /* @__PURE__ */ new Map() };
   for (const path15 of paths) {
-    const value = getAtPath(data, path15);
+    let node = root;
+    for (const segment of path15) {
+      let child = node.children.get(segment);
+      if (!child) {
+        child = { leaf: false, children: /* @__PURE__ */ new Map() };
+        node.children.set(segment, child);
+      }
+      node = child;
+    }
+    node.leaf = true;
+  }
+  return root;
+}
+function extractNode(data, trie) {
+  if (trie.leaf) return data;
+  const star = trie.children.get("*");
+  if (star) {
+    if (!Array.isArray(data)) return void 0;
+    return data.map(
+      (item) => typeof item === "object" && item !== null ? extractNode(item, star) ?? {} : {}
+    );
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return void 0;
+  const record = data;
+  const out = {};
+  let any = false;
+  for (const [key, child] of trie.children) {
+    const value = extractNode(record[key], child);
     if (value !== void 0) {
-      setAtPath(out, path15.filter((p) => p !== "*"), value);
+      out[key] = value;
+      any = true;
     }
   }
-  return out;
+  return any ? out : void 0;
+}
+function extractByPaths(data, paths) {
+  if (paths.length === 0) return {};
+  const extracted = extractNode(data, buildPathTrie(paths));
+  return extracted && typeof extracted === "object" && !Array.isArray(extracted) ? extracted : {};
 }
 function pickTranslatable(data, schema) {
   const translatablePaths = introspectSchema(schema).filter((f) => f.kind === "translatable").map((f) => f.path);
@@ -458,32 +539,6 @@ function mergeStructuralOntoLocale(localeData, enData, schema) {
   const translatable = pickTranslatable(localeData, schema);
   return deepMerge(structural, translatable);
 }
-function getAtPath(obj, path15) {
-  let current = obj;
-  for (const segment of path15) {
-    if (segment === "*") {
-      if (!Array.isArray(current)) return void 0;
-      return current.map(
-        (item) => typeof item === "object" && item !== null ? getAtPath(item, path15.slice(path15.indexOf("*") + 1)) : void 0
-      );
-    }
-    if (typeof current !== "object" || current === null || Array.isArray(current)) return void 0;
-    current = current[segment];
-  }
-  return current;
-}
-function setAtPath(obj, path15, value) {
-  if (path15.length === 0) return;
-  if (path15.length === 1) {
-    obj[path15[0]] = value;
-    return;
-  }
-  const [head, ...rest] = path15;
-  if (!(head in obj) || typeof obj[head] !== "object" || obj[head] === null) {
-    obj[head] = {};
-  }
-  setAtPath(obj[head], rest, value);
-}
 function deepMerge(base, overlay) {
   const out = { ...base };
   for (const [key, value] of Object.entries(overlay)) {
@@ -774,7 +829,8 @@ function sanitizeMdxJsxAttributeQuotes(body) {
       if (i >= body.length || body[i] === ">" || body[i] === "/") break;
       const attrStart = i;
       while (i < body.length && /[\w:.-]/.test(body[i] ?? "")) i += 1;
-      body.slice(attrStart, i);
+      const attrName = body.slice(attrStart, i);
+      if (!attrName) break;
       while (i < body.length && /\s/.test(body[i] ?? "")) i += 1;
       if (body[i] !== "=") {
         tagOut += body.slice(attrStart, i);
@@ -783,10 +839,12 @@ function sanitizeMdxJsxAttributeQuotes(body) {
       tagOut += body.slice(attrStart, i);
       tagOut += "=";
       i += 1;
+      const wsStart = i;
       while (i < body.length && /\s/.test(body[i] ?? "")) i += 1;
+      tagOut += body.slice(wsStart, i);
       const quote = body[i];
       if (quote !== '"' && quote !== "'") {
-        continue;
+        break;
       }
       if (quote === "'") {
         const valStart2 = i + 1;
@@ -1108,7 +1166,7 @@ function getTranslatablePayload(doc, type) {
 
 // src/i18n/resolve-document.ts
 init_cjs_shims();
-function resolveLocalizedDocument(slug, locale, defaultLocale, allDocs, type, localeRouting) {
+function resolveLocalizedDocument(slug, locale, defaultLocale, allDocs, type, localeRouting, fallbackLocales = []) {
   const urlBuilder = createUrlBuilder({
     locales: [defaultLocale, locale],
     defaultLocale,
@@ -1122,15 +1180,28 @@ function resolveLocalizedDocument(slug, locale, defaultLocale, allDocs, type, lo
   for (const [docLocale, docIdx] of allDocs) {
     const found = docIdx.bySlug.get(slug);
     if (!found) continue;
-    const correctSlug = getSlugForLocale(found, docLocale, locale, allDocs, defaultLocale);
-    if (correctSlug && correctSlug !== slug) {
+    const enSlug = docLocale === defaultLocale ? found.slug : found.enSlug;
+    let target;
+    let targetLocale = locale;
+    for (const candidateLocale of [locale, ...fallbackLocales]) {
+      const cand = candidateLocale === defaultLocale ? allDocs.get(candidateLocale)?.bySlug.get(enSlug) : allDocs.get(candidateLocale)?.byEnSlug.get(enSlug);
+      if (cand) {
+        target = cand;
+        targetLocale = candidateLocale;
+        break;
+      }
+    }
+    if (target) {
+      if (target.slug === slug) {
+        return { document: target, actualLocale: targetLocale };
+      }
       if (!type.path) {
         return { document: null, actualLocale: locale };
       }
       return {
         document: null,
         actualLocale: locale,
-        shouldRedirectTo: urlBuilder.resolvePath(type.path, correctSlug, locale)
+        shouldRedirectTo: urlBuilder.resolvePath(type.path, target.slug, locale)
       };
     }
     if (docLocale === defaultLocale) {
@@ -1161,13 +1232,6 @@ function resolveLocalizedDocument(slug, locale, defaultLocale, allDocs, type, lo
   }
   return { document: null, actualLocale: locale };
 }
-function getSlugForLocale(document2, sourceLocale, targetLocale, allDocs, defaultLocale) {
-  if (sourceLocale === targetLocale) return document2.slug;
-  const englishSlug = sourceLocale === defaultLocale ? document2.slug : document2.enSlug;
-  if (!englishSlug) return null;
-  if (targetLocale === defaultLocale) return englishSlug;
-  return allDocs.get(targetLocale)?.byEnSlug.get(englishSlug)?.slug ?? null;
-}
 
 // src/create-project.ts
 function comparatorFor(orderBy) {
@@ -1220,7 +1284,8 @@ function buildRuntime(config, type, getRuntime) {
         config.defaultLocale,
         load(),
         type,
-        config.localeRouting
+        config.localeRouting,
+        config.localeFallbacks[locale] ?? []
       );
       if (result.document && type.path) {
         return {
@@ -1242,8 +1307,14 @@ function buildRuntime(config, type, getRuntime) {
       const params = [];
       for (const locale of options.locales ?? config.locales) {
         const localeIdx = all.get(locale);
+        const fallbacks = config.localeFallbacks[locale] ?? [];
         for (const doc of enIdx.bySlug.values()) {
-          const slug = locale === config.defaultLocale ? doc.slug : localeIdx?.byEnSlug.get(doc.slug)?.slug ?? doc.slug;
+          let slug;
+          if (locale === config.defaultLocale) {
+            slug = doc.slug;
+          } else {
+            slug = localeIdx?.byEnSlug.get(doc.slug)?.slug ?? fallbacks.map((fb) => all.get(fb)?.byEnSlug.get(doc.slug)?.slug).find((s) => s !== void 0) ?? doc.slug;
+          }
           params.push({ locale, slug });
         }
       }
@@ -1705,7 +1776,7 @@ init_sqlite();
 
 // src/validate/validate-relations.ts
 init_cjs_shims();
-function getAtPath2(obj, fieldPath) {
+function getAtPath(obj, fieldPath) {
   let current = obj;
   for (const segment of fieldPath) {
     if (typeof current !== "object" || current === null || Array.isArray(current)) return void 0;
@@ -1750,7 +1821,7 @@ function validateRelations(project) {
           });
           continue;
         }
-        const value = getAtPath2(doc.frontmatter, fieldMeta.path);
+        const value = getAtPath(doc.frontmatter, fieldMeta.path);
         if (value === void 0 || value === null || value === "") continue;
         const targetSlugs = slugIndex.get(targetTypeId) ?? /* @__PURE__ */ new Set();
         const fieldLabel = fieldMeta.path.join(".");
@@ -2134,6 +2205,66 @@ function resolveLocalesFromPreset(config, preset, explicitLocales) {
 // src/translate/page-translator.ts
 init_cjs_shims();
 
+// src/storage/batch-jobs.ts
+init_cjs_shims();
+function insertBatchJob(db, input) {
+  const info = db.prepare(
+    `INSERT INTO translation_batch_jobs (job_name, model, display_model, created_at, state)
+       VALUES (?, ?, ?, ?, ?)`
+  ).run(input.jobName, input.model, input.displayModel, input.createdAt, input.state);
+  return Number(info.lastInsertRowid);
+}
+function insertBatchItems(db, jobId, items) {
+  const stmt = db.prepare(
+    `INSERT INTO translation_batch_items (
+      job_id, request_index, content_type, en_slug, locale, en_hash, snapshot_id, status
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending')`
+  );
+  for (const item of items) {
+    stmt.run(
+      jobId,
+      item.requestIndex,
+      item.contentType,
+      item.enSlug,
+      item.locale,
+      item.enHash,
+      item.snapshotId
+    );
+  }
+}
+function listPendingBatchJobs(db) {
+  return db.prepare(`SELECT * FROM translation_batch_jobs WHERE completed_at IS NULL ORDER BY id`).all();
+}
+function listBatchItems(db, jobId) {
+  return db.prepare(`SELECT * FROM translation_batch_items WHERE job_id = ? ORDER BY request_index`).all(jobId);
+}
+function listPendingBatchItems(db) {
+  return db.prepare(
+    `SELECT i.* FROM translation_batch_items i
+       JOIN translation_batch_jobs j ON j.id = i.job_id
+       WHERE j.completed_at IS NULL AND i.status = 'pending'
+       ORDER BY i.job_id, i.request_index`
+  ).all();
+}
+function claimBatchJobCompletion(db, jobId, state, completedAt) {
+  const info = db.prepare(
+    `UPDATE translation_batch_jobs SET state = ?, completed_at = ?
+       WHERE id = ? AND completed_at IS NULL`
+  ).run(state, completedAt, jobId);
+  return info.changes > 0;
+}
+function updateBatchItemStatus(db, jobId, requestIndex, status, error) {
+  db.prepare(
+    `UPDATE translation_batch_items SET status = ?, error = ? WHERE job_id = ? AND request_index = ?`
+  ).run(status, error ?? null, jobId, requestIndex);
+}
+
+// src/translate/page-translator.ts
+init_sqlite();
+
+// src/translate/batch-worklist.ts
+init_cjs_shims();
+
 // src/history/record-snapshot.ts
 init_cjs_shims();
 init_sqlite();
@@ -2151,9 +2282,111 @@ function recordEnSnapshot(config, input, db) {
   return id;
 }
 
-// src/translate/page-translator.ts
+// src/translate/batch-worklist.ts
 init_sqlite();
 
+// src/translate/gemini-batch.ts
+init_cjs_shims();
+
+// src/translate/retry.ts
+init_cjs_shims();
+var TRANSIENT_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function statusFromError(error) {
+  if (error instanceof genai.ApiError && typeof error.status === "number") {
+    return error.status;
+  }
+  if (error && typeof error === "object" && "status" in error) {
+    const status = error.status;
+    if (typeof status === "number") return status;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const match = message.match(/\b(429|500|502|503|504)\b/);
+  if (match) return Number(match[1]);
+  return void 0;
+}
+function isNetworkError(error) {
+  const err = error;
+  const code = typeof err?.code === "string" ? err.code : "";
+  if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "EPIPE" || code === "UND_ERR_SOCKET") {
+    return true;
+  }
+  const message = error instanceof Error ? error.message.toLowerCase() : "";
+  return message.includes("network") || message.includes("fetch failed") || message.includes("socket hang up") || message.includes("terminated");
+}
+function isTransientError(error) {
+  const status = statusFromError(error);
+  if (status !== void 0) return TRANSIENT_STATUS.has(status);
+  return isNetworkError(error);
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function withRetry(fn, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? 3);
+  const baseDelayMs = options.baseDelayMs ?? 1e3;
+  const sleep2 = options.sleep ?? defaultSleep;
+  const random = options.random ?? Math.random;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt >= attempts || !isTransientError(error)) throw error;
+      const backoff = baseDelayMs * 2 ** (attempt - 1);
+      const delay = backoff + random() * backoff;
+      await sleep2(delay);
+    }
+  }
+  throw lastError;
+}
+
+// src/translate/gemini-batch.ts
+var STATE_FAMILY_PREFIX = /^(JOB_STATE_|BATCH_STATE_)/;
+var TERMINAL_STATES = /* @__PURE__ */ new Set([
+  "SUCCEEDED",
+  "FAILED",
+  "CANCELLED",
+  "EXPIRED",
+  "PARTIALLY_SUCCEEDED"
+]);
+var SUCCESSFUL_STATES = /* @__PURE__ */ new Set(["SUCCEEDED", "PARTIALLY_SUCCEEDED"]);
+function normalizeBatchState(state) {
+  return String(state ?? "UNKNOWN").replace(STATE_FAMILY_PREFIX, "");
+}
+function isTerminalBatchState(state) {
+  return TERMINAL_STATES.has(normalizeBatchState(state));
+}
+function isSuccessfulBatchState(state) {
+  return SUCCESSFUL_STATES.has(normalizeBatchState(state));
+}
+function makeClient(apiKey) {
+  const key = apiKey ?? process.env.GEMINI_API_KEY;
+  if (!key) {
+    throw new Error("GEMINI_API_KEY is required for scribe translate");
+  }
+  return new genai.GoogleGenAI({ apiKey: key });
+}
+function textFromBatchResponse(response) {
+  if (typeof response.text === "string") return response.text;
+  const parts = response.candidates?.[0]?.content?.parts ?? [];
+  return parts.filter((part) => !part.thought && typeof part.text === "string").map((part) => part.text).join("");
+}
+async function createGeminiBatchJob(input) {
+  const ai = makeClient(input.apiKey);
+  const job = await withRetry(
+    () => ai.batches.create({
+      model: input.model,
+      src: input.requests,
+      config: { displayName: input.displayName ?? `scribe-translate-${Date.now()}` }
+    })
+  );
+  if (!job.name) throw new Error("Gemini batch job was created without a name");
+  return job;
+}
+async function getGeminiBatchJob(input) {
+  const ai = makeClient(input.apiKey);
+  return withRetry(() => ai.batches.get({ name: input.name }));
+}
+
 // src/translate/gemini-client.ts
 init_cjs_shims();
 
@@ -2178,6 +2411,12 @@ function normalizeGeminiDisplayName(model) {
   if (alias) return alias[0];
   return name;
 }
+function resolveThinkingConfig(apiModelId) {
+  const id = stripModelsPrefix(apiModelId).toLowerCase();
+  if (id.startsWith("gemini-3")) return { thinkingLevel: genai.ThinkingLevel.LOW };
+  if (id.includes("2.5")) return { thinkingBudget: 128 };
+  return void 0;
+}
 
 // src/translate/gemini-client.ts
 var DEFAULT_MODEL = DEFAULT_GEMINI_MODEL;
@@ -2191,11 +2430,36 @@ function extractJson(text) {
   return trimmed;
 }
 function parseGeminiResponse(text) {
+  let parsed;
   try {
-    return JSON.parse(text.trim());
+    parsed = JSON.parse(text.trim());
   } catch {
-    return JSON.parse(extractJson(text));
+    parsed = JSON.parse(extractJson(text));
   }
+  if (parsed !== null && typeof parsed === "object" && parsed.frontmatter === void 0) {
+    parsed.frontmatter = {};
+  }
+  return parsed;
+}
+function buildGeminiRequestConfig(input) {
+  const thinkingConfig = resolveThinkingConfig(input.apiModelId);
+  return {
+    responseMimeType: "application/json",
+    ...input.responseSchema ? { responseSchema: input.responseSchema } : {},
+    ...thinkingConfig ? { thinkingConfig } : {}
+  };
+}
+function usageFromResponse(response) {
+  const meta = response.usageMetadata ?? response.usage_metadata ?? {};
+  const thoughtsTokens = meta.thoughtsTokenCount ?? meta.thoughts_token_count ?? 0;
+  return {
+    inputTokens: meta.promptTokenCount ?? meta.prompt_token_count ?? 0,
+    // candidatesTokenCount does not include thoughts, but thoughts are billed as
+    // output tokens, so fold them in here for accurate cost accounting.
+    outputTokens: (meta.candidatesTokenCount ?? meta.candidates_token_count ?? 0) + thoughtsTokens,
+    thoughtsTokens,
+    totalTokens: meta.totalTokenCount ?? meta.total_token_count ?? 0
+  };
 }
 async function translatePageWithGemini(input) {
   const apiKey = input.apiKey ?? process.env.GEMINI_API_KEY;
@@ -2207,28 +2471,28 @@ async function translatePageWithGemini(input) {
   );
   const apiModel = resolveGeminiModelId(displayModel);
   const ai = new genai.GoogleGenAI({ apiKey });
-  const response = await ai.models.generateContent({
-    model: apiModel,
-    contents: input.prompt,
-    config: {
-      responseMimeType: "application/json",
-      ...input.responseSchema ? { responseSchema: input.responseSchema } : {}
-    }
-  });
+  const response = await withRetry(
+    () => ai.models.generateContent({
+      model: apiModel,
+      contents: input.prompt,
+      config: buildGeminiRequestConfig({
+        apiModelId: apiModel,
+        responseSchema: input.responseSchema
+      })
+    })
+  );
   const raw = response.text ?? "";
   const parsed = parseGeminiResponse(raw);
   if (!parsed.frontmatter || typeof parsed.body !== "string") {
     throw new Error("Gemini response missing frontmatter/body");
   }
-  const usageMetadata = response.usageMetadata;
-  const usage = {
-    inputTokens: usageMetadata?.promptTokenCount ?? 0,
-    outputTokens: usageMetadata?.candidatesTokenCount ?? 0,
-    totalTokens: usageMetadata?.totalTokenCount ?? 0
-  };
-  return { model: displayModel, raw, parsed, usage };
+  return { model: displayModel, raw, parsed, usage: usageFromResponse(response) };
 }
 
+// src/translate/translate-core.ts
+init_cjs_shims();
+init_sqlite();
+
 // src/translate/gemini-pricing.ts
 init_cjs_shims();
 var CONTEXT_TIER_TOKENS = 2e5;
@@ -2247,12 +2511,14 @@ function resolveModelPricing(model) {
   const match = Object.entries(GEMINI_PRICING_USD).find(([key]) => id.includes(key));
   return match?.[1];
 }
-function estimateTranslationCostUsd(model, inputTokens, outputTokens) {
+var BATCH_DISCOUNT = 0.5;
+function estimateTranslationCostUsd(model, inputTokens, outputTokens, mode = "interactive") {
   const pricing = resolveModelPricing(model);
   if (!pricing) return void 0;
   const inputRate = tierRate(inputTokens, pricing.input);
   const outputRate = tierRate(outputTokens, pricing.output);
-  return inputTokens / 1e6 * inputRate + outputTokens / 1e6 * outputRate;
+  const multiplier = mode === "batch" ? BATCH_DISCOUNT : 1;
+  return (inputTokens / 1e6 * inputRate + outputTokens / 1e6 * outputRate) * multiplier;
 }
 function formatTokenCount(tokens) {
   if (tokens >= 1e6) return `${(tokens / 1e6).toFixed(2)}M`;
@@ -2280,6 +2546,7 @@ var LOCALE_NAMES = {
   "zh-CN": "Simplified Chinese",
   "zh-TW": "Traditional Chinese",
   pt: "Portuguese",
+  "pt-BR": "Brazilian Portuguese",
   ja: "Japanese",
   ru: "Russian",
   it: "Italian",
@@ -2287,29 +2554,29 @@ var LOCALE_NAMES = {
 };
 function defaultLocalizationPrompt(localeName, locale) {
   return [
-    `Localize the content below into natural ${localeName} (${locale}).`,
+    `Localize the content above into natural ${localeName} (${locale}).`,
     "Do not translate word-for-word.",
     "Preserve the source tone and brand voice.",
     "Write as if a native speaker authored it for the target market."
   ].join(" ");
 }
+var TASK_FRAMING = "You are localizing the content below into a target language specified at the end of this prompt.";
+function buildOutputFormatLine(hasFrontmatter, slugStrategy) {
+  if (!hasFrontmatter) {
+    return slugStrategy === "localized" ? "`body` (string, full MDX body), `slug` (string)." : "`body` (string, full MDX body).";
+  }
+  return slugStrategy === "localized" ? "`frontmatter` (object with translated frontmatter fields), `body` (string, full MDX body), `slug` (string)." : "`frontmatter` (object), `body` (string).";
+}
 function buildPageTranslationPrompt(input) {
   const localeName = LOCALE_NAMES[input.targetLocale] ?? input.targetLocale;
-  const prompt = input.resolved.promptOverride ?? defaultLocalizationPrompt(localeName, input.targetLocale);
-  const lines = [
-    prompt,
+  const localizationPrompt = input.resolved.promptOverride ?? defaultLocalizationPrompt(localeName, input.targetLocale);
+  const prefix = [
+    TASK_FRAMING,
     "",
     ...input.resolved.context ? ["## Context", input.resolved.context, ""] : [],
     ...input.contextLabel ? [`Document: ${input.contextLabel}`, ""] : [],
     "## Rules",
     ...input.resolved.rules.map((rule) => `- ${rule}`),
-    ...input.slugStrategy === "localized" ? [
-      `- The slug MUST be written in ${localeName}, derived from the ${localeName} title and its meaning \u2014 never the English slug. Transliterate non-Latin ${localeName} into ASCII Latin.`
-    ] : [],
-    "",
-    "## Output format",
-    "Return ONLY valid JSON with keys:",
-    input.slugStrategy === "localized" ? "`frontmatter` (object with translated frontmatter fields), `body` (string, full MDX body), `slug` (string)." : "`frontmatter` (object), `body` (string).",
     "",
     "## EN translatable frontmatter (JSON)",
     JSON.stringify(input.translatableFrontmatter, null, 2),
@@ -2317,7 +2584,22 @@ function buildPageTranslationPrompt(input) {
     "## EN body (MDX)",
     input.enBody
   ];
-  return lines.join("\n");
+  const suffix = [
+    "",
+    "## Target language",
+    localizationPrompt,
+    ...input.slugStrategy === "localized" ? [
+      `The slug MUST be written in ${localeName}, derived from the ${localeName} title and its meaning \u2014 never the English slug.`
+    ] : [],
+    "",
+    "## Output format",
+    "Return ONLY valid JSON with keys:",
+    buildOutputFormatLine(
+      Object.keys(input.translatableFrontmatter).length > 0,
+      input.slugStrategy
+    )
+  ];
+  return [...prefix, ...suffix].join("\n");
 }
 
 // src/translate/response-schema.ts
@@ -2368,9 +2650,8 @@ function buildTranslatableSubschema(schema) {
 function buildGeminiResponseSchema(schema, slugStrategy) {
   try {
     const translatable = buildTranslatableSubschema(schema);
-    if (!translatable) return null;
     const responseShape = {
-      frontmatter: translatable,
+      ...translatable ? { frontmatter: translatable } : {},
       body: zod.z.string()
     };
     if (slugStrategy === "localized") {
@@ -2451,7 +2732,12 @@ function validateTranslatedFrontmatter(enDoc, localeFrontmatter, typeSchema) {
   return { ok: true, frontmatter };
 }
 
-// src/translate/page-translator.ts
+// src/translate/translate-core.ts
+function translationItemKey(item) {
+  const contentType = item.contentType ?? item.content_type ?? "";
+  const enSlug = item.enSlug ?? item.en_slug ?? "";
+  return `${contentType}\0${enSlug}\0${item.locale}`;
+}
 function summarizeResults(results, durationMs) {
   return results.reduce(
     (totals, result) => {
@@ -2487,17 +2773,6 @@ function formatTranslateError(error) {
   }
   return message.length > 160 ? `${message.slice(0, 157)}\u2026` : message;
 }
-async function runPool(items, concurrency, worker) {
-  if (items.length === 0) return;
-  let nextIndex = 0;
-  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-    while (nextIndex < items.length) {
-      const index = nextIndex++;
-      await worker(items[index], index);
-    }
-  });
-  await Promise.all(runners);
-}
 function resolveContextLabel(enDoc, enSlug) {
   const fm = enDoc.frontmatter;
   for (const key of ["title", "name", "h1"]) {
@@ -2506,73 +2781,82 @@ function resolveContextLabel(enDoc, enSlug) {
   }
   return enSlug;
 }
-async function translatePage(config, item, options = {}) {
-  const startedAt = Date.now();
-  const base = {
+function baseForItem(item) {
+  return {
     contentType: item.contentType,
     enSlug: item.enSlug,
     locale: item.locale
   };
-  try {
-    const type = config.types.find((t) => t.id === item.contentType);
-    if (!type) throw new Error(`Unknown content type ${item.contentType}`);
-    const enDoc = readEnDocument(config, type, item.enSlug);
-    if (!enDoc) throw new Error(`EN document not found: ${item.enSlug}`);
-    const payload = getTranslatablePayload(enDoc, type);
-    const currentEnHash = computePageEnHash(payload.frontmatter, payload.body);
-    const db = openStore(config, "readonly");
-    const existing = getTranslation(db, type.id, item.enSlug, item.locale);
-    db.close();
-    if (!options.force && existing && existing.en_hash === currentEnHash) {
-      return {
-        ...base,
+}
+function prepareTranslation(config, item, options, startedAt) {
+  const type = config.types.find((t) => t.id === item.contentType);
+  if (!type) throw new Error(`Unknown content type ${item.contentType}`);
+  const enDoc = readEnDocument(config, type, item.enSlug);
+  if (!enDoc) throw new Error(`EN document not found: ${item.enSlug}`);
+  const payload = getTranslatablePayload(enDoc, type);
+  const currentEnHash = computePageEnHash(payload.frontmatter, payload.body);
+  const db = openStore(config, "readonly");
+  const existing = getTranslation(db, type.id, item.enSlug, item.locale);
+  db.close();
+  if (!options.force && existing && existing.en_hash === currentEnHash) {
+    return {
+      status: "done",
+      result: {
+        ...baseForItem(item),
         skipped: true,
         reason: "fresh",
         durationMs: Date.now() - startedAt
-      };
-    }
-    const resolvedTranslate = resolveTranslateConfig(config, type);
-    const model = options.model ?? resolvedTranslate.model;
-    const prompt = buildPageTranslationPrompt({
-      resolved: resolvedTranslate,
-      targetLocale: item.locale,
-      contextLabel: resolveContextLabel(enDoc, item.enSlug),
-      translatableFrontmatter: payload.frontmatter,
-      enBody: payload.body,
-      slugStrategy: type.slugStrategy
-    });
-    if (options.dryRun) {
-      return {
-        ...base,
-        skipped: false,
-        model,
-        durationMs: Date.now() - startedAt
-      };
-    }
-    const responseSchema = buildGeminiResponseSchema(type.schema, type.slugStrategy);
-    const result = await translatePageWithGemini({
-      prompt,
+      }
+    };
+  }
+  const resolvedTranslate = resolveTranslateConfig(config, type);
+  const model = options.model ?? resolvedTranslate.model;
+  const prompt = buildPageTranslationPrompt({
+    resolved: resolvedTranslate,
+    targetLocale: item.locale,
+    contextLabel: resolveContextLabel(enDoc, item.enSlug),
+    translatableFrontmatter: payload.frontmatter,
+    enBody: payload.body,
+    slugStrategy: type.slugStrategy
+  });
+  const responseSchema = buildGeminiResponseSchema(type.schema, type.slugStrategy);
+  return {
+    status: "ready",
+    prepared: {
+      item,
+      type,
+      enDoc,
+      payload,
+      currentEnHash,
+      existingSlug: existing?.slug,
       model,
+      prompt,
       responseSchema: responseSchema ?? void 0
-    });
-    const rawSlug = type.slugStrategy === "localized" ? result.parsed.slug ?? existing?.slug ?? item.enSlug : item.enSlug;
+    }
+  };
+}
+function finalizeTranslation(config, prepared, output, options) {
+  const { item, type, enDoc, payload } = prepared;
+  const base = baseForItem(item);
+  try {
+    const rawSlug = type.slugStrategy === "localized" ? output.parsed.slug ?? prepared.existingSlug ?? item.enSlug : item.enSlug;
     const localeCodes = config.locales.filter((l) => l !== config.defaultLocale);
     const { slug, stripped, matchedCode } = stripLocaleSuffixFromSlug(rawSlug, localeCodes);
     const slugAdjusted = stripped && matchedCode ? { from: rawSlug, to: slug, matchedCode } : void 0;
-    const validated = validateTranslatedFrontmatter(enDoc, result.parsed.frontmatter, type.schema);
+    const validated = validateTranslatedFrontmatter(enDoc, output.parsed.frontmatter, type.schema);
     if (!validated.ok) {
       throw new Error(`Translation validation failed: ${validated.error}`);
     }
     const { body: translatedBody, adjusted: mdxAdjusted } = assertValidTranslatedMdxBody(
-      result.parsed.body
+      output.parsed.body
     );
     const writeDb = openStore(config, "readwrite");
-    const snapshotId = recordEnSnapshot(
+    const snapshotId = options.snapshotId ?? recordEnSnapshot(
       config,
       {
         contentType: type.id,
         enSlug: item.enSlug,
-        enHash: currentEnHash,
+        enHash: prepared.currentEnHash,
         frontmatter: payload.frontmatter,
         body: payload.body
       },
@@ -2585,24 +2869,25 @@ async function translatePage(config, item, options = {}) {
       slug,
       frontmatter: validated.frontmatter,
       body: translatedBody,
-      enHash: currentEnHash,
+      enHash: prepared.currentEnHash,
       translatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      model: result.model,
+      model: output.model,
       snapshotId
     });
     writeDb.close();
     const estimatedCostUsd = estimateTranslationCostUsd(
-      normalizeGeminiDisplayName(result.model),
-      result.usage.inputTokens,
-      result.usage.outputTokens
+      normalizeGeminiDisplayName(output.model),
+      output.usage.inputTokens,
+      output.usage.outputTokens,
+      options.costMode
     );
     return {
       ...base,
       skipped: false,
-      model: result.model,
-      usage: result.usage,
+      model: output.model,
+      usage: output.usage,
       estimatedCostUsd,
-      durationMs: Date.now() - startedAt,
+      durationMs: Date.now() - options.startedAt,
       slugAdjusted,
       mdxAdjusted: mdxAdjusted || void 0
     };
@@ -2612,33 +2897,559 @@ async function translatePage(config, item, options = {}) {
       skipped: false,
       failed: true,
       error: formatTranslateError(error),
+      durationMs: Date.now() - options.startedAt
+    };
+  }
+}
+function displayModelFor(prepared) {
+  return normalizeGeminiDisplayName(
+    prepared.model ?? process.env.PROSE_GEMINI_MODEL ?? DEFAULT_GEMINI_MODEL
+  );
+}
+
+// src/translate/batch-worklist.ts
+var MAX_REQUESTS_PER_JOB = 100;
+var MAX_PROMPT_BYTES_PER_JOB = 15 * 1024 * 1024;
+var INITIAL_POLL_MS = 5e3;
+var MAX_POLL_MS = 3e4;
+var POLL_BACKOFF_FACTOR = 1.5;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function planBatchJobs(entries) {
+  const byModel = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const group = byModel.get(entry.apiModel);
+    if (group) group.push(entry);
+    else byModel.set(entry.apiModel, [entry]);
+  }
+  const plans = [];
+  for (const [apiModel, group] of byModel) {
+    let current = [];
+    let currentBytes = 0;
+    for (const entry of group) {
+      const size = Buffer.byteLength(entry.prompt, "utf8");
+      if (current.length > 0 && (current.length >= MAX_REQUESTS_PER_JOB || currentBytes + size > MAX_PROMPT_BYTES_PER_JOB)) {
+        plans.push({ apiModel, entries: current });
+        current = [];
+        currentBytes = 0;
+      }
+      current.push(entry);
+      currentBytes += size;
+    }
+    if (current.length > 0) plans.push({ apiModel, entries: current });
+  }
+  return plans;
+}
+function readPendingBatchWork(config) {
+  const db = openStore(config, "readwrite");
+  const jobs = listPendingBatchJobs(db);
+  const pendingItems = listPendingBatchItems(db);
+  db.close();
+  const inFlightKeys = new Set(pendingItems.map((item) => translationItemKey(item)));
+  return { jobs, inFlightKeys, pendingItems };
+}
+async function submitBatchJobPlan(config, input) {
+  const { plan, displayModel, jobIndex, jobCount } = input;
+  const job = await createGeminiBatchJob({
+    model: plan.apiModel,
+    requests: plan.entries.map(({ prepared }) => ({
+      contents: prepared.prompt,
+      config: buildGeminiRequestConfig({
+        apiModelId: plan.apiModel,
+        responseSchema: prepared.responseSchema
+      })
+    })),
+    displayName: `scribe-translate-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${jobIndex + 1}`
+  });
+  const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+  const db = openStore(config, "readwrite");
+  const jobId = insertBatchJob(db, {
+    jobName: job.name,
+    model: plan.apiModel,
+    displayModel,
+    state: String(job.state ?? "JOB_STATE_PENDING"),
+    createdAt
+  });
+  insertBatchItems(
+    db,
+    jobId,
+    plan.entries.map(({ prepared }, requestIndex) => ({
+      requestIndex,
+      contentType: prepared.item.contentType,
+      enSlug: prepared.item.enSlug,
+      locale: prepared.item.locale,
+      enHash: prepared.currentEnHash,
+      // Snapshot the EN source now so ingestion after a resume does not depend
+      // on the EN files still matching (or existing) on disk.
+      snapshotId: recordEnSnapshot(
+        config,
+        {
+          contentType: prepared.item.contentType,
+          enSlug: prepared.item.enSlug,
+          enHash: prepared.currentEnHash,
+          frontmatter: prepared.payload.frontmatter,
+          body: prepared.payload.body
+        },
+        db
+      )
+    }))
+  );
+  const row = {
+    id: jobId,
+    job_name: job.name,
+    model: plan.apiModel,
+    display_model: displayModel,
+    created_at: createdAt,
+    state: String(job.state ?? "JOB_STATE_PENDING"),
+    completed_at: null
+  };
+  db.close();
+  input.onProgress?.({
+    type: "batch-submitted",
+    name: job.name,
+    count: plan.entries.length,
+    model: displayModel,
+    jobIndex,
+    jobCount,
+    createdAt
+  });
+  return row;
+}
+function buildIngestContext(config, db, jobRow, itemRow) {
+  const type = config.types.find((t) => t.id === itemRow.content_type);
+  if (!type) throw new Error(`Unknown content type ${itemRow.content_type}`);
+  let enDoc = readEnDocument(config, type, itemRow.en_slug);
+  if (!enDoc) {
+    const snapshot = getEnSnapshot(db, itemRow.snapshot_id);
+    if (!snapshot) {
+      throw new Error(
+        `EN document and snapshot #${itemRow.snapshot_id} not found for ${itemRow.en_slug}`
+      );
+    }
+    enDoc = {
+      slug: itemRow.en_slug,
+      enSlug: itemRow.en_slug,
+      locale: config.defaultLocale,
+      noindex: false,
+      frontmatter: JSON.parse(snapshot.frontmatter_json),
+      content: snapshot.body
+    };
+  }
+  const item = {
+    contentType: itemRow.content_type,
+    enSlug: itemRow.en_slug,
+    locale: itemRow.locale,
+    reason: "missing",
+    currentEnHash: itemRow.en_hash
+  };
+  return {
+    item,
+    type,
+    enDoc,
+    // Unused on ingest: finalizeTranslation receives the pre-recorded snapshotId.
+    payload: { frontmatter: enDoc.frontmatter, body: enDoc.content },
+    currentEnHash: itemRow.en_hash,
+    existingSlug: getTranslation(db, type.id, itemRow.en_slug, itemRow.locale)?.slug,
+    model: jobRow.display_model,
+    prompt: "",
+    responseSchema: void 0
+  };
+}
+function ingestBatchJob(config, jobRow, batchJob, onResult) {
+  const state = String(batchJob.state ?? "UNKNOWN");
+  const db = openStore(config, "readwrite");
+  if (!claimBatchJobCompletion(db, jobRow.id, state, (/* @__PURE__ */ new Date()).toISOString())) {
+    db.close();
+    return null;
+  }
+  const pendingItems = listBatchItems(db, jobRow.id).filter((item) => item.status === "pending");
+  const results = [];
+  const failItem = (itemRow, message, startedAt) => {
+    const result = {
+      contentType: itemRow.content_type,
+      enSlug: itemRow.en_slug,
+      locale: itemRow.locale,
+      skipped: false,
+      failed: true,
+      error: formatTranslateError(new Error(message)),
       durationMs: Date.now() - startedAt
     };
+    updateBatchItemStatus(db, jobRow.id, itemRow.request_index, "failed", result.error);
+    results.push(result);
+    onResult?.(result);
+  };
+  if (isSuccessfulBatchState(state)) {
+    const responses = batchJob.dest?.inlinedResponses ?? [];
+    for (const itemRow of pendingItems) {
+      const startedAt = Date.now();
+      const inlined = responses[itemRow.request_index];
+      if (!inlined || inlined.error || !inlined.response) {
+        failItem(
+          itemRow,
+          inlined?.error?.message ?? (inlined ? "Batch response missing content" : "Batch response missing"),
+          startedAt
+        );
+        continue;
+      }
+      let result;
+      try {
+        const response = inlined.response;
+        const raw = textFromBatchResponse(response);
+        const parsed = parseGeminiResponse(raw);
+        if (!parsed.frontmatter || typeof parsed.body !== "string") {
+          throw new Error("Gemini response missing frontmatter/body");
+        }
+        const prepared = buildIngestContext(config, db, jobRow, itemRow);
+        result = finalizeTranslation(
+          config,
+          prepared,
+          { model: jobRow.display_model, parsed, usage: usageFromResponse(response) },
+          { costMode: "batch", startedAt, snapshotId: itemRow.snapshot_id }
+        );
+      } catch (error) {
+        failItem(itemRow, error instanceof Error ? error.message : String(error), startedAt);
+        continue;
+      }
+      updateBatchItemStatus(
+        db,
+        jobRow.id,
+        itemRow.request_index,
+        result.failed ? "failed" : "done",
+        result.error
+      );
+      results.push(result);
+      onResult?.(result);
+    }
+  } else {
+    const message = batchJob.error?.message ?? `Batch job ended in state ${normalizeBatchState(state)}`;
+    const startedAt = Date.now();
+    for (const itemRow of pendingItems) {
+      failItem(itemRow, message, startedAt);
+    }
+  }
+  db.close();
+  return results;
+}
+async function pollAndIngestBatchJobs(config, jobs, options = {}) {
+  const jobCount = options.jobCount ?? jobs.length;
+  const active = jobs.map((row, jobIndex) => ({ row, jobIndex }));
+  const loopStartedAt = Date.now();
+  let delay = INITIAL_POLL_MS;
+  let firstRound = true;
+  const elapsedFor = (row) => {
+    const createdAtMs = Date.parse(row.created_at);
+    return Number.isNaN(createdAtMs) ? Date.now() - loopStartedAt : Date.now() - createdAtMs;
+  };
+  while (active.length > 0) {
+    if (!firstRound) {
+      await sleep(delay);
+      delay = Math.min(delay * POLL_BACKOFF_FACTOR, MAX_POLL_MS);
+    }
+    firstRound = false;
+    for (const tracked of [...active]) {
+      const batchJob = await getGeminiBatchJob({ name: tracked.row.job_name });
+      const state = normalizeBatchState(batchJob.state);
+      options.onProgress?.({
+        type: "batch-polling",
+        name: tracked.row.job_name,
+        state,
+        elapsedMs: elapsedFor(tracked.row),
+        jobIndex: tracked.jobIndex,
+        jobCount
+      });
+      if (isTerminalBatchState(batchJob.state)) {
+        active.splice(active.indexOf(tracked), 1);
+        const results = ingestBatchJob(
+          config,
+          tracked.row,
+          batchJob,
+          options.onResult
+        );
+        if (results === null) {
+          options.onProgress?.({
+            type: "batch-done",
+            name: tracked.row.job_name,
+            state,
+            model: tracked.row.display_model,
+            count: 0,
+            jobIndex: tracked.jobIndex,
+            jobCount,
+            translated: 0,
+            failed: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            estimatedCostUsd: 0,
+            elapsedMs: elapsedFor(tracked.row),
+            alreadyIngested: true
+          });
+          continue;
+        }
+        options.onProgress?.({
+          type: "batch-done",
+          name: tracked.row.job_name,
+          state,
+          model: tracked.row.display_model,
+          count: results.length,
+          jobIndex: tracked.jobIndex,
+          jobCount,
+          translated: results.filter((r) => !r.failed && !r.skipped).length,
+          failed: results.filter((r) => r.failed).length,
+          inputTokens: results.reduce((sum, r) => sum + (r.usage?.inputTokens ?? 0), 0),
+          outputTokens: results.reduce((sum, r) => sum + (r.usage?.outputTokens ?? 0), 0),
+          estimatedCostUsd: results.reduce((sum, r) => sum + (r.estimatedCostUsd ?? 0), 0),
+          elapsedMs: elapsedFor(tracked.row)
+        });
+      }
+    }
   }
 }
+function failedResultForItem(item, error, startedAt) {
+  return {
+    ...baseForItem(item),
+    skipped: false,
+    failed: true,
+    error: formatTranslateError(error),
+    durationMs: Date.now() - startedAt
+  };
+}
+
+// src/translate/page-translator.ts
+async function runPool(items, concurrency, worker) {
+  if (items.length === 0) return;
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (nextIndex < items.length) {
+      const index = nextIndex++;
+      await worker(items[index], index);
+    }
+  });
+  await Promise.all(runners);
+}
 function labelForItem(item) {
   return `${item.contentType}/${item.enSlug}@${item.locale}`;
 }
+async function translatePage(config, item, options = {}) {
+  const startedAt = Date.now();
+  let outcome;
+  try {
+    outcome = prepareTranslation(config, item, options, startedAt);
+  } catch (error) {
+    return failedResultForItem(item, error, startedAt);
+  }
+  if (outcome.status === "done") return outcome.result;
+  const prepared = outcome.prepared;
+  if (options.dryRun) {
+    return {
+      ...baseForItem(item),
+      skipped: false,
+      model: prepared.model,
+      durationMs: Date.now() - startedAt
+    };
+  }
+  try {
+    const result = await translatePageWithGemini({
+      prompt: prepared.prompt,
+      model: prepared.model,
+      responseSchema: prepared.responseSchema
+    });
+    return finalizeTranslation(
+      config,
+      prepared,
+      { model: result.model, parsed: result.parsed, usage: result.usage },
+      { costMode: "interactive", startedAt }
+    );
+  } catch (error) {
+    return failedResultForItem(item, error, startedAt);
+  }
+}
+function createResultCollector(items, onProgress) {
+  const slotByKey = /* @__PURE__ */ new Map();
+  items.forEach((item, index) => slotByKey.set(translationItemKey(item), index));
+  const slots = new Array(items.length);
+  const extras = [];
+  return {
+    emit(result) {
+      const slot = slotByKey.get(translationItemKey(result));
+      if (slot !== void 0 && slots[slot] === void 0) slots[slot] = result;
+      else extras.push(result);
+      onProgress?.({ type: "item-done", result });
+    },
+    assemble() {
+      return [
+        ...slots.filter((result) => result !== void 0),
+        ...extras
+      ];
+    }
+  };
+}
 async function translateWorklist(config, items, options = {}) {
+  const mode = options.mode ?? "batch";
   const concurrency = Math.max(1, options.concurrency ?? 3);
   const startedAt = Date.now();
-  const results = new Array(items.length);
-  const active = /* @__PURE__ */ new Set();
+  if (options.dryRun) {
+    options.onProgress?.({
+      type: "start",
+      total: items.length,
+      concurrency,
+      dryRun: true,
+      model: options.model,
+      mode
+    });
+    const results2 = items.map((item) => {
+      const itemStartedAt = Date.now();
+      try {
+        const outcome = prepareTranslation(config, item, options, itemStartedAt);
+        return outcome.status === "done" ? outcome.result : {
+          ...baseForItem(item),
+          skipped: false,
+          model: outcome.prepared.model,
+          durationMs: Date.now() - itemStartedAt
+        };
+      } catch (error) {
+        return failedResultForItem(item, error, itemStartedAt);
+      }
+    });
+    for (const result of results2) options.onProgress?.({ type: "item-done", result });
+    const totals2 = summarizeResults(results2, Date.now() - startedAt);
+    options.onProgress?.({ type: "done", results: results2, totals: totals2 });
+    return results2;
+  }
+  const pending = readPendingBatchWork(config);
+  const inputKeys = new Set(items.map((item) => translationItemKey(item)));
+  const resumedExtraCount = pending.pendingItems.filter(
+    (item) => !inputKeys.has(translationItemKey(item))
+  ).length;
   options.onProgress?.({
     type: "start",
-    total: items.length,
+    total: items.length + resumedExtraCount,
     concurrency,
-    dryRun: Boolean(options.dryRun),
-    model: options.model
+    dryRun: false,
+    model: options.model,
+    mode
   });
-  await runPool(items, concurrency, async (item, index) => {
-    const label = labelForItem(item);
-    active.add(label);
-    options.onProgress?.({ type: "item-start", item, active: [...active] });
-    const result = await translatePage(config, item, options);
-    results[index] = result;
-    active.delete(label);
-    options.onProgress?.({ type: "item-done", result });
+  const collector = createResultCollector(items, options.onProgress);
+  const workItems = items.filter((item) => !pending.inFlightKeys.has(translationItemKey(item)));
+  if (mode === "direct") {
+    const pendingCounts = countPendingItems(config, pending.jobs);
+    emitResumedJobs(pending.jobs, pendingCounts, pending.jobs.length, options.onProgress);
+    const active = /* @__PURE__ */ new Set();
+    await Promise.all([
+      runPool(workItems, concurrency, async (item) => {
+        const label = labelForItem(item);
+        active.add(label);
+        options.onProgress?.({ type: "item-start", item, active: [...active] });
+        const result = await translatePage(config, item, options);
+        active.delete(label);
+        collector.emit(result);
+      }),
+      pending.jobs.length > 0 ? pollAndIngestBatchJobs(config, pending.jobs, {
+        onProgress: options.onProgress,
+        onResult: collector.emit
+      }) : Promise.resolve()
+    ]);
+  } else {
+    const entries = [];
+    for (const item of workItems) {
+      const itemStartedAt = Date.now();
+      try {
+        const outcome = prepareTranslation(config, item, options, itemStartedAt);
+        if (outcome.status === "done") {
+          collector.emit(outcome.result);
+        } else {
+          entries.push({
+            apiModel: resolveGeminiModelId(displayModelFor(outcome.prepared)),
+            prompt: outcome.prepared.prompt,
+            prepared: outcome.prepared
+          });
+        }
+      } catch (error) {
+        collector.emit(failedResultForItem(item, error, itemStartedAt));
+      }
+    }
+    const plans = planBatchJobs(entries);
+    const jobCount = pending.jobs.length + plans.length;
+    const pendingCounts = countPendingItems(config, pending.jobs);
+    emitResumedJobs(pending.jobs, pendingCounts, jobCount, options.onProgress);
+    const submitted = await Promise.all(
+      plans.map(async (plan, planIndex) => {
+        try {
+          return await submitBatchJobPlan(config, {
+            plan,
+            displayModel: normalizeGeminiDisplayName(plan.apiModel),
+            jobIndex: pending.jobs.length + planIndex,
+            jobCount,
+            onProgress: options.onProgress
+          });
+        } catch (error) {
+          for (const entry of plan.entries) {
+            collector.emit(failedResultForItem(entry.prepared.item, error, startedAt));
+          }
+          return void 0;
+        }
+      })
+    );
+    const jobsToPoll = [
+      ...pending.jobs,
+      ...submitted.filter((row) => row !== void 0)
+    ];
+    if (jobsToPoll.length > 0) {
+      await pollAndIngestBatchJobs(config, jobsToPoll, {
+        jobCount,
+        onProgress: options.onProgress,
+        onResult: collector.emit
+      });
+    }
+  }
+  const results = collector.assemble();
+  const totals = summarizeResults(results, Date.now() - startedAt);
+  options.onProgress?.({ type: "done", results, totals });
+  return results;
+}
+function countPendingItems(config, jobs) {
+  if (jobs.length === 0) return /* @__PURE__ */ new Map();
+  const db = openStore(config, "readonly");
+  const counts = /* @__PURE__ */ new Map();
+  for (const job of jobs) {
+    counts.set(job.id, listBatchItems(db, job.id).filter((i) => i.status === "pending").length);
+  }
+  db.close();
+  return counts;
+}
+function emitResumedJobs(jobs, counts, jobCount, onProgress) {
+  jobs.forEach((job, jobIndex) => {
+    onProgress?.({
+      type: "batch-submitted",
+      name: job.job_name,
+      count: counts.get(job.id) ?? 0,
+      model: job.display_model,
+      jobIndex,
+      jobCount,
+      resumed: true,
+      createdAt: job.created_at
+    });
+  });
+}
+async function resumeTranslationJobs(config, options = {}) {
+  const startedAt = Date.now();
+  const pending = readPendingBatchWork(config);
+  if (pending.jobs.length === 0) return null;
+  options.onProgress?.({
+    type: "start",
+    total: pending.pendingItems.length,
+    concurrency: 1,
+    dryRun: false,
+    mode: "batch"
+  });
+  const counts = countPendingItems(config, pending.jobs);
+  emitResumedJobs(pending.jobs, counts, pending.jobs.length, options.onProgress);
+  const results = [];
+  await pollAndIngestBatchJobs(config, pending.jobs, {
+    onProgress: options.onProgress,
+    onResult: (result) => {
+      results.push(result);
+      options.onProgress?.({ type: "item-done", result });
+    }
   });
   const totals = summarizeResults(results, Date.now() - startedAt);
   options.onProgress?.({ type: "done", results, totals });
@@ -3256,35 +4067,43 @@ async function promptContentType(config) {
     })
   );
 }
+var ALL_LOCALES = /* @__PURE__ */ Symbol("all-locales");
+var PICK_LOCALES = /* @__PURE__ */ Symbol("pick-locales");
+async function promptManualLocales(config) {
+  const locales = nonDefaultLocales(config);
+  if (locales.length <= 1) return {};
+  const picked = await runPrompt(
+    prompts.checkbox({
+      message: "Locales to translate",
+      choices: locales.map((locale) => ({ name: locale, value: locale, checked: true })),
+      validate: (values) => values.length > 0 || "Pick at least one locale"
+    })
+  );
+  return picked.length === locales.length ? {} : { locale: picked };
+}
 async function promptLocalePreset(config) {
   const presets = Object.entries(config.localePresets ?? {}).filter(
     (entry) => Array.isArray(entry[1])
   );
   if (presets.length === 0) {
-    const locales = nonDefaultLocales(config);
-    if (locales.length <= 1) return {};
-    const picked = await runPrompt(
-      prompts.checkbox({
-        message: "Locales to translate",
-        choices: locales.map((locale) => ({ name: locale, value: locale, checked: true })),
-        validate: (values) => values.length > 0 || "Pick at least one locale"
-      })
-    );
-    return picked.length === locales.length ? {} : { locale: picked };
+    return promptManualLocales(config);
   }
   const choice = await runPrompt(
     prompts.select({
       message: "Locale preset",
       choices: [
-        { name: "All locales", value: void 0 },
+        { name: "All locales", value: ALL_LOCALES },
         ...presets.map(([name, locales]) => ({
           name: `${name} (${locales.join(", ")})`,
           value: name
-        }))
+        })),
+        { name: "Choose locales manually\u2026", value: PICK_LOCALES }
       ]
     })
   );
-  return choice ? { preset: choice } : {};
+  if (choice === PICK_LOCALES) return promptManualLocales(config);
+  if (choice === ALL_LOCALES) return {};
+  return { preset: choice };
 }
 async function promptStrategy() {
   return runPrompt(
@@ -3298,12 +4117,25 @@ async function promptStrategy() {
     })
   );
 }
+async function promptMode() {
+  return runPrompt(
+    prompts.select({
+      message: "Translation mode",
+      choices: [
+        { name: "Batch \u2014 50% cheaper, async, resumable (recommended)", value: "batch" },
+        { name: "Direct \u2014 immediate results, full price", value: "direct" }
+      ],
+      default: "batch"
+    })
+  );
+}
 async function promptTranslateSelection(config, flags) {
   const selection = {
     contentType: flags.type,
     preset: flags.preset,
     locale: flags.locale,
-    strategy: flags.strategy
+    strategy: flags.strategy,
+    mode: flags.mode
   };
   if (!isInteractive()) return selection;
   if (!selection.contentType) {
@@ -3315,6 +4147,9 @@ async function promptTranslateSelection(config, flags) {
   if (!selection.strategy) {
     selection.strategy = await promptStrategy();
   }
+  if (!selection.mode) {
+    selection.mode = await promptMode();
+  }
   return selection;
 }
 
@@ -3336,6 +4171,34 @@ function progressBar(ratio, width = 28) {
 function labelForResult(result) {
   return `${result.contentType}/${result.enSlug}@${result.locale}`;
 }
+function shortJobId(name) {
+  const segments = name.split("/");
+  return segments[segments.length - 1] || name;
+}
+function formatElapsed(elapsedMs) {
+  return `${Math.round(elapsedMs / 1e3)}s`;
+}
+function batchDoneParts(event) {
+  if (event.alreadyIngested) {
+    return [
+      `job ${shortJobId(event.name)}`,
+      event.model ?? "?",
+      "already ingested by another scribe run (results saved there)",
+      formatElapsed(event.elapsedMs)
+    ].join(" \xB7 ");
+  }
+  const parts = [
+    `job ${shortJobId(event.name)}`,
+    event.model ?? "?",
+    `${event.count} request${event.count === 1 ? "" : "s"}`,
+    `${event.translated} translated`
+  ];
+  if (event.failed > 0) parts.push(`${event.failed} failed`);
+  parts.push(`${formatTokenCount(event.inputTokens)} in / ${formatTokenCount(event.outputTokens)} out`);
+  parts.push(`${formatUsd(event.estimatedCostUsd)} est.`);
+  parts.push(formatElapsed(event.elapsedMs));
+  return parts.join(" \xB7 ");
+}
 function statusForResult(result, dryRun) {
   if (result.failed) return red("failed");
   if (result.skipped) return dim("skipped");
@@ -3381,6 +4244,25 @@ function createTranslateProgressReporter(options = {}) {
   if (!enabled) {
     return {
       onEvent(event) {
+        if (event.type === "batch-submitted") {
+          const verb = event.resumed ? "Resuming" : "Submitted";
+          console.log(
+            `${verb} batch job ${event.jobIndex + 1}/${event.jobCount} with ${event.count} request${event.count === 1 ? "" : "s"}${event.model ? ` (${event.model})` : ""}: ${event.name}`
+          );
+          return;
+        }
+        if (event.type === "batch-polling") {
+          console.log(
+            `batch ${event.jobIndex + 1}/${event.jobCount} ${shortJobId(event.name)}: ${event.state.replace(/^JOB_STATE_/, "")} (${formatElapsed(event.elapsedMs)} elapsed)`
+          );
+          return;
+        }
+        if (event.type === "batch-done") {
+          const line = `batch ${event.jobIndex + 1}/${event.jobCount} ${event.state} \xB7 ${batchDoneParts(event)}`;
+          if (event.failed > 0 && event.translated === 0) console.error(line);
+          else console.log(line);
+          return;
+        }
         if (event.type === "item-done") {
           const label = labelForResult(event.result);
           const status = statusForResult(event.result, dryRun);
@@ -3411,6 +4293,9 @@ function createTranslateProgressReporter(options = {}) {
   let outputTokens = 0;
   let estimatedCostUsd = 0;
   let active = [];
+  let mode;
+  const batchJobs = /* @__PURE__ */ new Map();
+  let batchElapsedMs = 0;
   const recent = [];
   let renderedLines = 0;
   let cursorHidden = false;
@@ -3426,6 +4311,15 @@ function createTranslateProgressReporter(options = {}) {
       cursorHidden = false;
     }
   }
+  function printPersistent(lines) {
+    if (renderedLines > 0) {
+      process.stdout.write(`\x1B[${renderedLines}A`);
+    }
+    for (const line of lines) {
+      process.stdout.write("\x1B[2K" + line + "\n");
+    }
+    renderedLines = 0;
+  }
   function render() {
     hideCursor();
     if (renderedLines > 0) {
@@ -3433,12 +4327,34 @@ function createTranslateProgressReporter(options = {}) {
     }
     const lines = [];
     const title = dryRun ? "Dry run" : "Translating";
-    lines.push(cyan(`${title} ${done}/${total}`) + dim(` \xB7 ${concurrency} parallel`) + (model ? dim(` \xB7 ${model}`) : ""));
+    const isBatch = mode === "batch" || batchJobs.size > 0;
+    lines.push(
+      cyan(`${title} ${done}/${total}`) + dim(isBatch ? " \xB7 batch" : ` \xB7 ${concurrency} parallel`) + (model ? dim(` \xB7 ${model}`) : "")
+    );
     lines.push(progressBar(total === 0 ? 0 : done / total) + dim(`  ${Math.round(total === 0 ? 0 : done / total * 100)}%`));
     lines.push(
       dim("Tokens ") + `${formatTokenCount(inputTokens)} in \xB7 ${formatTokenCount(outputTokens)} out` + dim(" \xB7 Cost ") + formatUsd(estimatedCostUsd) + dim(" est.")
     );
-    if (active.length > 0) {
+    if (batchJobs.size > 0 && done < total) {
+      const terminal = /^(SUCCEEDED|FAILED|CANCELLED|EXPIRED|PARTIALLY_SUCCEEDED)$/;
+      let running = 0;
+      let finished = 0;
+      let requests = 0;
+      for (const job of batchJobs.values()) {
+        if (terminal.test(job.state)) finished += 1;
+        else running += 1;
+        requests += job.count;
+      }
+      lines.push(
+        dim("Batches ") + `${running} running \xB7 ${finished} done` + dim(` \xB7 ${requests} request${requests === 1 ? "" : "s"} \xB7 ${Math.round(batchElapsedMs / 1e3)}s elapsed`)
+      );
+      for (const [name, job] of batchJobs) {
+        if (terminal.test(job.state)) continue;
+        lines.push(
+          dim("  ") + shortJobId(name) + dim(` \xB7 ${job.model ?? "?"} \xB7 ${job.count} req \xB7 `) + job.state + dim(` \xB7 ${formatElapsed(job.elapsedMs)}`)
+        );
+      }
+    } else if (active.length > 0) {
       lines.push(dim("Active ") + active.slice(0, 3).join(", ") + (active.length > 3 ? dim(` +${active.length - 3}`) : ""));
     } else if (done < total) {
       lines.push(dim("Active ") + "starting\u2026");
@@ -3466,12 +4382,58 @@ function createTranslateProgressReporter(options = {}) {
           total = event.total;
           concurrency = event.concurrency;
           model = event.model;
+          mode = event.mode;
           render();
           break;
         case "item-start":
           active = event.active;
           render();
           break;
+        case "batch-submitted": {
+          const createdAtMs = event.createdAt ? Date.parse(event.createdAt) : void 0;
+          const elapsedMs = createdAtMs && !Number.isNaN(createdAtMs) ? Date.now() - createdAtMs : 0;
+          batchJobs.set(event.name, {
+            state: event.resumed ? "RESUMED" : "SUBMITTED",
+            count: event.count,
+            model: event.model,
+            createdAtMs: Number.isNaN(createdAtMs) ? void 0 : createdAtMs,
+            elapsedMs
+          });
+          const requests = `${event.count} ${event.resumed ? "pending " : ""}request${event.count === 1 ? "" : "s"}`;
+          const origin = event.resumed ? `resumed job (submitted ${formatElapsed(elapsedMs)} ago)` : "submitted job";
+          printPersistent([
+            dim(`${event.resumed ? "\u21BB" : "\u2192"} ${origin} ${shortJobId(event.name)} \xB7 ${event.model ?? "?"} \xB7 ${requests}`)
+          ]);
+          render();
+          break;
+        }
+        case "batch-polling": {
+          const job = batchJobs.get(event.name);
+          batchJobs.set(event.name, {
+            state: event.state.replace(/^JOB_STATE_/, ""),
+            count: job?.count ?? 0,
+            model: job?.model,
+            createdAtMs: job?.createdAtMs,
+            elapsedMs: event.elapsedMs
+          });
+          batchElapsedMs = Math.max(batchElapsedMs, event.elapsedMs);
+          render();
+          break;
+        }
+        case "batch-done": {
+          const job = batchJobs.get(event.name);
+          batchJobs.set(event.name, {
+            state: event.state.replace(/^JOB_STATE_/, ""),
+            count: job?.count ?? event.count,
+            model: job?.model ?? event.model,
+            createdAtMs: job?.createdAtMs,
+            elapsedMs: event.elapsedMs
+          });
+          const marker = event.failed > 0 && event.translated === 0 ? red("\u2717") : green("\u2713");
+          printPersistent([`${marker} ${dim(batchDoneParts(event))}`]);
+          render();
+          break;
+        }
         case "item-done": {
           done += 1;
           active = active.filter((label) => label !== labelForResult(event.result));
@@ -3594,6 +4556,21 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (arg === "--batch") {
+      options.batch = true;
+      i++;
+      continue;
+    }
+    if (arg === "--direct") {
+      options.direct = true;
+      i++;
+      continue;
+    }
+    if (arg === "--resume") {
+      options.resume = true;
+      i++;
+      continue;
+    }
     if (arg === "--strategy") {
       const value = argv[++i];
       if (value !== "all" && value !== "missing-only") {
@@ -3662,11 +4639,19 @@ Translate flags:
   --locale <code>...     Target locale(s); overrides --preset
   --slug <en-slug>       Single English document
   --model <id>           Gemini model override
-  --concurrency <n>      Parallel translations (default: 3)
+  --batch                Force Gemini Batch API mode (50% token cost; default)
+  --direct               Force direct interactive calls (immediate, full price)
+  --resume               Only poll/ingest pending batch jobs; submit nothing new
+  --concurrency <n>      Parallel translations in --direct mode (default: 3)
   --dry-run              List work without writing
   --force                Re-translate even when hashes match
   --strategy <mode>      all (default) or missing-only
   --no-progress          Plain line logging instead of live progress
+
+Batch mode submits jobs upfront and persists them in the store, so Ctrl+C
+during polling is safe: the next run (or --resume) picks the jobs back up and
+ingests their results. In a TTY without --batch/--direct, a prompt asks which
+mode to use.
 `);
     return;
   }
@@ -3712,11 +4697,29 @@ Translate flags:
       break;
     }
     case "translate": {
+      if (options.batch && options.direct) {
+        throw new Error("--batch and --direct are mutually exclusive");
+      }
+      if (options.resume) {
+        const reporter2 = createTranslateProgressReporter({
+          enabled: !options.noProgress,
+          dryRun: false
+        });
+        const results2 = await resumeTranslationJobs(config, { onProgress: reporter2.onEvent });
+        reporter2.finish();
+        if (results2 === null) {
+          console.log("No pending translation batch jobs.");
+          break;
+        }
+        if (results2.some((result) => result.failed)) process.exitCode = 1;
+        break;
+      }
       const selection = await promptTranslateSelection(config, {
         type: options.type,
         preset: options.preset,
         locale: options.locale,
-        strategy: options.strategy
+        strategy: options.strategy,
+        mode: options.batch ? "batch" : options.direct ? "direct" : void 0
       });
       const locales = resolveLocalesFromPreset(config, selection.preset, selection.locale);
       const worklist = buildWorklist(config, {
@@ -3726,6 +4729,18 @@ Translate flags:
         strategy: selection.strategy ?? "all"
       });
       if (worklist.length === 0) {
+        if (!options.dryRun) {
+          const reporter2 = createTranslateProgressReporter({
+            enabled: !options.noProgress,
+            dryRun: false
+          });
+          const resumed = await resumeTranslationJobs(config, { onProgress: reporter2.onEvent });
+          reporter2.finish();
+          if (resumed !== null) {
+            if (resumed.some((result) => result.failed)) process.exitCode = 1;
+            break;
+          }
+        }
         console.log("Nothing to translate.");
         break;
       }
@@ -3738,6 +4753,7 @@ Translate flags:
         dryRun: options.dryRun,
         force: options.force,
         concurrency: options.concurrency,
+        mode: selection.mode,
         onProgress: reporter.onEvent
       });
       reporter.finish();