@purposeinplay/payload-ai-translate 0.1.0

package/dist/api.js

@@ -0,0 +1,918 @@
+import { DEFAULT_CONCURRENCY, DEFAULT_RETRY, DEFAULT_TARGET_POLICY, REENTRY_FLAG } from './defaults.js';
+import { collectBlocksConfig, extractTranslationUnits } from './lib/content-extractor.js';
+import { checkPerDocLimit } from './lib/cost-guards.js';
+import { getEffectiveExcludePatternsForSurface, getExcludedFieldPaths, isPathExcluded } from './lib/effective-locales.js';
+import { emitAlert, emitEvent } from './lib/events.js';
+import { diffFields } from './lib/field-diff.js';
+import { isFieldEmpty } from './lib/field-empty.js';
+import { resolveTranslatableFields } from './lib/field-resolver.js';
+import { mergeTranslationsIntoTargetDoc } from './lib/locale-merge.js';
+import { applyHashSkip, recordHashesAfterWrite } from './lib/manual-edit-guard.js';
+import { findByIdNoFallback, findGlobalNoFallback } from './lib/payload-read.js';
+import { bucketLocaleOutcomes, persistTranslationUsage } from './lib/persist-usage.js';
+import { completeJobNow, createJob, updateJob } from './lib/progress-store.js';
+import { truncateSourceValue } from './lib/truncate-source-value.js';
+import { DEFAULT_MANUAL_EDIT_COLLECTION_SLUG } from './manual-edit-collection.js';
+import { DEFAULT_SETTINGS_GLOBAL_SLUG } from './settings-global.js';
+import { batchUnits, translateBatch, translateForLocale } from './translate.js';
+/**
+ * Pick the provider this translation run should use.
+ *
+ * Resolution order:
+ *   1. If `config.providers` is configured AND the `translation-settings`
+ *      global has `activeProvider` set to one of those keys → that provider.
+ *   2. Otherwise → `config.provider` (the static fallback).
+ *
+ * The settings read is wrapped in try/catch because the global may not
+ * exist yet (first request after install before migrations land) or the
+ * read may fail for unrelated reasons. In those cases we fall back to
+ * the static provider rather than failing the translation.
+ */ async function resolveProvider(payload, config) {
+    if (!config.providers || Object.keys(config.providers).length === 0) {
+        return config.provider;
+    }
+    const slug = config.settings?.globalSlug ?? DEFAULT_SETTINGS_GLOBAL_SLUG;
+    try {
+        const settings = await payload.findGlobal({
+            slug: slug,
+            depth: 0,
+            overrideAccess: true
+        });
+        const activeName = settings?.activeProvider;
+        if (activeName && config.providers[activeName]) {
+            return config.providers[activeName];
+        }
+    } catch  {
+    // Global not yet created or read failed — fall back to default.
+    }
+    return config.provider;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function translateDocument(payload, options) {
+    const baseConfig = payload.config?.custom?.aiTranslate;
+    if (!baseConfig) {
+        throw new Error('[ai-translate] Plugin not configured. Add aiTranslatePlugin() to your Payload config.');
+    }
+    // Resolve the runtime provider ONCE per document. All locales of this
+    // run use the same provider — a switch shouldn't happen mid-job. The
+    // resolved provider is spliced into a shallow config copy that flows
+    // through the rest of the pipeline; no other call site needs to
+    // change.
+    const runtimeProvider = await resolveProvider(payload, baseConfig);
+    const config = runtimeProvider === baseConfig.provider ? baseConfig : {
+        ...baseConfig,
+        provider: runtimeProvider
+    };
+    const { collection, id, signal } = options;
+    const targetLocales = options.targetLocales ?? config.targetLocales;
+    const targetPolicy = options.targetPolicy ?? config.automation?.targetPolicy ?? DEFAULT_TARGET_POLICY;
+    const startedAt = Date.now();
+    // Read source document. Default to reading the draft so admin-UI flows
+    // ("draft → translate → review → publish") work on versioned collections.
+    // Hooks that fire on the published transition can pass `draft: false`
+    // explicitly if they need the published shape.
+    const sourceDoc = await findByIdNoFallback(payload, collection, id, config.sourceLocale, {
+        draft: options.draft ?? true
+    });
+    if (!sourceDoc) {
+        throw new Error(`[ai-translate] Document not found: ${collection}/${String(id)}`);
+    }
+    // Resolve collection field config
+    const collectionFields = getCollectionFields(payload, collection);
+    if (!collectionFields) {
+        throw new Error(`[ai-translate] Collection "${collection}" not found in Payload config.`);
+    }
+    // Find translatable fields
+    let translatableFields = resolveTranslatableFields(collectionFields);
+    // Surface-aware patterns: respects D7 `translateSlug` opt-in on the
+    // matching `perCollection` row, so slugs only flow through when
+    // explicitly enabled per surface.
+    const excludePatterns = await getEffectiveExcludePatternsForSurface(payload, config, collection);
+    // Block schemas for the schema-aware extractor path. Walks every
+    // `type: 'blocks'` field in the collection config and gathers its
+    // registered `Block` configs so the extractor can gate which keys
+    // inside a block are translatable based on the schema (fixes BUG-04
+    // family — non-text strings being treated as translatable). When the
+    // map has no entry for a given blockType, the extractor falls back to
+    // the previous heuristic walk.
+    const blocksConfig = collectBlocksConfig(collectionFields);
+    // Capture the full set of localized top-level fields BEFORE narrowing to
+    // `options.fields`. The locale-write merge needs this even when a per-
+    // field translate restricts work to a single field — Payload validates
+    // required-localized siblings on partial writes, so we must include them
+    // in writeData with their existing-target or source values.
+    const allLocalizedTopFields = new Set(translatableFields.filter((f)=>f.localized).map((f)=>f.path.split('.')[0]));
+    // Admin-configured per-surface exclusions (D6 feature). Applies to
+    // BOTH manual and automation paths — distinct from `excludePatterns`
+    // (static plugin config) and from the locale gates in
+    // `effective-locales` (automation-only). Applied BEFORE the
+    // `options.fields` narrowing below so that a manual per-field
+    // request for an excluded path returns an empty job rather than
+    // silently translating a field the admin opted out.
+    const adminExcludedPaths = await getExcludedFieldPaths(payload, config, collection);
+    if (adminExcludedPaths.size > 0) {
+        translatableFields = translatableFields.filter((f)=>!isPathExcluded(f.path, adminExcludedPaths));
+    }
+    // If caller specified specific fields, filter down
+    if (options.fields?.length) {
+        const requested = new Set(options.fields);
+        translatableFields = translatableFields.filter((f)=>requested.has(f.path));
+    }
+    if (translatableFields.length === 0) {
+        // Caller may have seeded a progress-store job (e.g. on-change hook) and
+        // threaded its id through `options.jobId`. Without this nudge the job
+        // stays `running` until the 2-minute TTL — the SSE stream keeps emitting
+        // it and the editor sees a phantom "Translating: 0/N" widget.
+        if (options.jobId) completeJobNow(options.jobId);
+        return {
+            documentId: id,
+            collection,
+            sourceLocale: config.sourceLocale,
+            succeeded: [],
+            preserved: [],
+            failed: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                estimatedCostUsd: 0
+            }
+        };
+    }
+    // Extract translation units
+    let units = extractTranslationUnits(sourceDoc, translatableFields, excludePatterns, blocksConfig);
+    // If previousDoc is available, filter to changed fields only.
+    // A unit whose fieldPath either (a) equals a changed field path or (b) is
+    // nested under one (e.g. unit "general.hello" under changed field "general")
+    // is kept. Plain string equality breaks for JSON / nested group units.
+    if (options.previousDoc) {
+        const fieldPaths = translatableFields.map((f)=>f.path);
+        const changedPaths = diffFields(options.previousDoc, sourceDoc, fieldPaths);
+        units = units.filter((u)=>changedPaths.some((cp)=>u.fieldPath === cp || u.fieldPath.startsWith(`${cp}.`)));
+    }
+    if (units.length === 0) {
+        if (options.jobId) completeJobNow(options.jobId);
+        return {
+            documentId: id,
+            collection,
+            sourceLocale: config.sourceLocale,
+            succeeded: [],
+            preserved: [],
+            failed: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                estimatedCostUsd: 0
+            }
+        };
+    }
+    // Check per-document character ceiling
+    const totalChars = units.reduce((sum, u)=>sum + u.text.length, 0);
+    try {
+        checkPerDocLimit(totalChars, config.costLimits.perDocCharCeiling);
+    } catch (error) {
+        const costError = error;
+        emitAlert(config, {
+            type: 'translation.cost-guard-abort',
+            code: costError.code === 'PER_CALL_LIMIT' ? 'cost-guard.per-call' : 'cost-guard.per-doc',
+            context: {
+                chars: costError.characterCount,
+                limit: costError.limit,
+                collection,
+                documentId: id
+            },
+            message: costError.message,
+            documentId: id,
+            collection,
+            timestamp: new Date(),
+            metadata: {
+                characterCount: costError.characterCount,
+                limit: costError.limit
+            }
+        });
+        throw error;
+    }
+    // Create progress tracking job — or reuse one passed in by the caller
+    // (the after-change hook seeds a job for instant UI feedback and threads
+    // its id through here so we don't end up with a phantom + real job pair)
+    const jobId = options.jobId ?? createJob(collection, id, targetLocales);
+    // Emit started event
+    emitEvent(config, {
+        type: 'translation.started',
+        documentId: id,
+        collection,
+        sourceLocale: config.sourceLocale,
+        targetLocales,
+        timestamp: new Date()
+    });
+    // Translate for each target locale with concurrency control
+    const concurrency = config.concurrency?.perDocument ?? DEFAULT_CONCURRENCY.perDocument;
+    const allSucceeded = [];
+    const allPreserved = [];
+    const allFailed = [];
+    const totalUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        estimatedCostUsd: 0
+    };
+    let providerLatencyMs = 0;
+    const localeQueue = [
+        ...targetLocales
+    ];
+    const running = new Set();
+    while(localeQueue.length > 0 || running.size > 0){
+        // Fill up to concurrency limit
+        while(localeQueue.length > 0 && running.size < concurrency){
+            if (signal?.aborted) break;
+            const locale = localeQueue.shift();
+            const promise = (async ()=>{
+                try {
+                    const result = await translateForLocale({
+                        payload,
+                        config,
+                        sourceDoc,
+                        documentId: id,
+                        collection,
+                        targetLocale: locale,
+                        units,
+                        fields: translatableFields,
+                        allLocalizedTopFields,
+                        writeMode: options.writeMode,
+                        targetPolicy,
+                        signal,
+                        req: options.req,
+                        force: options.force
+                    });
+                    allSucceeded.push(...result.succeeded);
+                    allPreserved.push(...result.preserved ?? []);
+                    allFailed.push(...result.failed);
+                    totalUsage.inputTokens += result.usage.inputTokens;
+                    totalUsage.outputTokens += result.usage.outputTokens;
+                    totalUsage.estimatedCostUsd = (totalUsage.estimatedCostUsd ?? 0) + (result.usage.estimatedCostUsd ?? 0);
+                    totalUsage.model = totalUsage.model ?? result.usage.model;
+                    providerLatencyMs += result.providerLatencyMs;
+                    // Per-locale tick: only real failures gate the locale's bar from
+                    // green. Skipped fields (verbatim echoes, etc.) are info-level
+                    // and shouldn't false-alarm the editor.
+                    const realFailedLocale = result.failed.filter((f)=>f.status === 'failed');
+                    updateJob(jobId, locale, realFailedLocale.length === 0, realFailedLocale.length > 0 ? `${realFailedLocale.length} field(s) failed` : undefined);
+                } catch (error) {
+                    const errMsg = error instanceof Error ? error.message : 'Unknown locale error';
+                    allFailed.push({
+                        fieldPath: '*',
+                        locale,
+                        status: 'failed',
+                        error: errMsg
+                    });
+                    updateJob(jobId, locale, false, errMsg);
+                    payload.logger.error(`[ai-translate] Locale "${locale}" failed for ${collection}/${String(id)}: ${errMsg}`);
+                }
+            })();
+            const tracked = promise.then(()=>{
+                running.delete(tracked);
+            }, ()=>{
+                running.delete(tracked);
+            });
+            running.add(tracked);
+        }
+        if (running.size > 0) {
+            await Promise.race(running);
+        }
+    }
+    // Fallback: when every locale fails before its provider call returns
+    // (e.g. 429 quota, network error), `totalUsage.model` is never stamped
+    // from a response. Surface the configured model so usage rows show what
+    // *would have* run instead of `<No Model>`.
+    if (!totalUsage.model && config.provider.model) {
+        totalUsage.model = config.provider.model;
+    }
+    // Real failures only — `skipped` results (verbatim echo, etc.) carry
+    // `status: 'skipped'` and shouldn't drive doc-level status to "failed".
+    const realFailed = allFailed.filter((f)=>f.status === 'failed');
+    // Soft skips (verbatim echo, etc.) — surface separately so the event
+    // consumer can flag "doc succeeded but N fields stayed in source".
+    const skippedReports = allFailed.filter((f)=>f.status === 'skipped').map((f)=>({
+            fieldPath: f.fieldPath,
+            locale: f.locale,
+            reason: f.error,
+            reasonCode: f.errorCode,
+            sourceValue: f.sourceValue
+        }));
+    // Emit final event
+    const eventType = realFailed.length === 0 ? 'translation.succeeded' : 'translation.failed';
+    emitEvent(config, {
+        type: eventType,
+        documentId: id,
+        collection,
+        sourceLocale: config.sourceLocale,
+        targetLocales,
+        timestamp: new Date(),
+        fields: [
+            ...allSucceeded,
+            ...allFailed
+        ],
+        usage: totalUsage,
+        error: realFailed.length > 0 ? `${realFailed.length} field(s) failed` : undefined,
+        ...skippedReports.length > 0 ? {
+            skippedFields: skippedReports
+        } : {}
+    });
+    // Persist a usage row when the consumer opted in. The helper short-circuits
+    // when usageTracking is disabled and swallows its own errors — translation
+    // results are returned to the caller regardless of whether the row landed.
+    await persistTranslationUsage({
+        payload,
+        config,
+        kind: 'collection',
+        slug: collection,
+        documentId: id,
+        jobId,
+        status: realFailed.length === 0 ? 'succeeded' : 'failed',
+        sourceLocale: config.sourceLocale,
+        localeOutcomes: bucketLocaleOutcomes(targetLocales, allSucceeded, realFailed),
+        succeededCount: allSucceeded.length,
+        failedCount: realFailed.length,
+        succeeded: allSucceeded,
+        preserved: allPreserved,
+        softSkippedFields: skippedReports,
+        usage: totalUsage,
+        durationMs: Date.now() - startedAt,
+        error: realFailed.length > 0 ? `${realFailed.length} field(s) failed` : undefined
+    });
+    return {
+        jobId,
+        documentId: id,
+        collection,
+        sourceLocale: config.sourceLocale,
+        succeeded: allSucceeded,
+        preserved: allPreserved,
+        failed: allFailed,
+        usage: totalUsage,
+        providerLatencyMs
+    };
+}
+// ---------------------------------------------------------------------------
+// Globals API
+// ---------------------------------------------------------------------------
+const NO_FALLBACK = null;
+export async function translateGlobal(payload, options) {
+    const baseConfig = payload.config?.custom?.aiTranslate;
+    if (!baseConfig) {
+        throw new Error('[ai-translate] Plugin not configured. Add aiTranslatePlugin() to your Payload config.');
+    }
+    // Same runtime-provider resolution as translateDocument — see comment there.
+    const runtimeProvider = await resolveProvider(payload, baseConfig);
+    const config = runtimeProvider === baseConfig.provider ? baseConfig : {
+        ...baseConfig,
+        provider: runtimeProvider
+    };
+    const { signal } = options;
+    const targetLocales = options.targetLocales ?? config.targetLocales;
+    const startedAt = Date.now();
+    const targetPolicy = options.targetPolicy ?? config.automation?.targetPolicy ?? DEFAULT_TARGET_POLICY;
+    // Read source global
+    const sourceDoc = await payload.findGlobal({
+        slug: options.global,
+        locale: config.sourceLocale,
+        fallbackLocale: NO_FALLBACK
+    });
+    if (!sourceDoc) {
+        throw new Error(`[ai-translate] Global not found: ${options.global}`);
+    }
+    // Resolve global field config
+    const globalFields = getGlobalFields(payload, options.global);
+    if (!globalFields) {
+        throw new Error(`[ai-translate] Global "${options.global}" not found in Payload config.`);
+    }
+    // Find translatable fields
+    let translatableFields = resolveTranslatableFields(globalFields);
+    const excludePatterns = await getEffectiveExcludePatternsForSurface(payload, config, options.global);
+    // See comment in `translateDocument` — globals can also embed
+    // `type: 'blocks'` fields (header zones, layout blocks).
+    const blocksConfig = collectBlocksConfig(globalFields);
+    // Capture the full localized-top-field set BEFORE narrowing — see comment
+    // on the matching block in `translateDocument`.
+    const allLocalizedTopFields = new Set(translatableFields.filter((f)=>f.localized).map((f)=>f.path.split('.')[0]));
+    // Admin-configured exclusions — see comment in `translateDocument`.
+    // Applies to manual + automation. For globals, `surfaceSlug` is the
+    // global slug itself (globals only have one row in `perCollection`).
+    const adminExcludedPaths = await getExcludedFieldPaths(payload, config, options.global);
+    if (adminExcludedPaths.size > 0) {
+        translatableFields = translatableFields.filter((f)=>!isPathExcluded(f.path, adminExcludedPaths));
+    }
+    // If caller specified specific fields, filter down
+    if (options.fields?.length) {
+        const requested = new Set(options.fields);
+        translatableFields = translatableFields.filter((f)=>requested.has(f.path));
+    }
+    if (translatableFields.length === 0) {
+        // See comment in `translateDocument` for the same early-return —
+        // without this nudge the seeded job stays `running` until TTL.
+        if (options.jobId) completeJobNow(options.jobId);
+        return {
+            documentId: options.global,
+            collection: options.global,
+            sourceLocale: config.sourceLocale,
+            succeeded: [],
+            preserved: [],
+            failed: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                estimatedCostUsd: 0
+            }
+        };
+    }
+    // Extract translation units
+    let units = extractTranslationUnits(sourceDoc, translatableFields, excludePatterns, blocksConfig);
+    // diffOnly: if previousDoc is provided, narrow units to only changed fields.
+    // Match by exact path or nested-under prefix (e.g. unit "general.title"
+    // under changed field "general") so JSON / nested group units are kept.
+    if (options.previousDoc) {
+        const fieldPaths = translatableFields.map((f)=>f.path);
+        const changedPaths = diffFields(options.previousDoc, sourceDoc, fieldPaths);
+        units = units.filter((u)=>changedPaths.some((cp)=>u.fieldPath === cp || u.fieldPath.startsWith(`${cp}.`)));
+    }
+    if (units.length === 0) {
+        if (options.jobId) completeJobNow(options.jobId);
+        return {
+            documentId: options.global,
+            collection: options.global,
+            sourceLocale: config.sourceLocale,
+            succeeded: [],
+            preserved: [],
+            failed: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                estimatedCostUsd: 0
+            }
+        };
+    }
+    // Check per-document character ceiling
+    const totalChars = units.reduce((sum, u)=>sum + u.text.length, 0);
+    try {
+        checkPerDocLimit(totalChars, config.costLimits.perDocCharCeiling);
+    } catch (error) {
+        const costError = error;
+        emitAlert(config, {
+            type: 'translation.cost-guard-abort',
+            code: costError.code === 'PER_CALL_LIMIT' ? 'cost-guard.per-call' : 'cost-guard.per-doc',
+            context: {
+                chars: costError.characterCount,
+                limit: costError.limit,
+                globalSlug: options.global
+            },
+            message: costError.message,
+            documentId: options.global,
+            collection: options.global,
+            timestamp: new Date(),
+            metadata: {
+                characterCount: costError.characterCount,
+                limit: costError.limit
+            }
+        });
+        throw error;
+    }
+    // Progress tracking job — reuse caller's jobId when provided (e.g. the
+    // on-change hook seeds one for instant UI feedback).
+    const jobId = options.jobId ?? createJob(options.global, options.global, targetLocales);
+    // Emit started event
+    emitEvent(config, {
+        type: 'translation.started',
+        documentId: options.global,
+        collection: options.global,
+        sourceLocale: config.sourceLocale,
+        targetLocales,
+        timestamp: new Date()
+    });
+    // Translate for each target locale with concurrency control
+    const concurrency = config.concurrency?.perDocument ?? DEFAULT_CONCURRENCY.perDocument;
+    const allSucceeded = [];
+    const allPreserved = [];
+    const allFailed = [];
+    const totalUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        estimatedCostUsd: 0
+    };
+    let providerLatencyMs = 0;
+    const localeQueue = [
+        ...targetLocales
+    ];
+    const running = new Set();
+    while(localeQueue.length > 0 || running.size > 0){
+        while(localeQueue.length > 0 && running.size < concurrency){
+            if (signal?.aborted) break;
+            const locale = localeQueue.shift();
+            const promise = (async ()=>{
+                try {
+                    const result = await translateGlobalForLocale({
+                        payload,
+                        config,
+                        sourceDoc,
+                        globalSlug: options.global,
+                        targetLocale: locale,
+                        units,
+                        fields: translatableFields,
+                        allLocalizedTopFields,
+                        writeMode: options.writeMode,
+                        targetPolicy,
+                        signal,
+                        req: options.req,
+                        force: options.force
+                    });
+                    allSucceeded.push(...result.succeeded);
+                    allPreserved.push(...result.preserved ?? []);
+                    allFailed.push(...result.failed);
+                    totalUsage.inputTokens += result.usage.inputTokens;
+                    totalUsage.outputTokens += result.usage.outputTokens;
+                    totalUsage.estimatedCostUsd = (totalUsage.estimatedCostUsd ?? 0) + (result.usage.estimatedCostUsd ?? 0);
+                    totalUsage.model = totalUsage.model ?? result.usage.model;
+                    providerLatencyMs += result.providerLatencyMs;
+                    // See collection branch above — skipped fields are info-level,
+                    // not real failures, and must not flip the locale's bar to red.
+                    const realFailedLocale = result.failed.filter((f)=>f.status === 'failed');
+                    updateJob(jobId, locale, realFailedLocale.length === 0, realFailedLocale.length > 0 ? `${realFailedLocale.length} field(s) failed` : undefined);
+                } catch (error) {
+                    const errMsg = error instanceof Error ? error.message : 'Unknown locale error';
+                    allFailed.push({
+                        fieldPath: '*',
+                        locale,
+                        status: 'failed',
+                        error: errMsg
+                    });
+                    updateJob(jobId, locale, false, errMsg);
+                    payload.logger.error(`[ai-translate] Locale "${locale}" failed for global "${options.global}": ${errMsg}`);
+                }
+            })();
+            const tracked = promise.then(()=>{
+                running.delete(tracked);
+            }, ()=>{
+                running.delete(tracked);
+            });
+            running.add(tracked);
+        }
+        if (running.size > 0) {
+            await Promise.race(running);
+        }
+    }
+    // Same model fallback as the collection path — see comment above.
+    if (!totalUsage.model && config.provider.model) {
+        totalUsage.model = config.provider.model;
+    }
+    // Real failures only — see comment in collection branch above.
+    const realFailed = allFailed.filter((f)=>f.status === 'failed');
+    const skippedReports = allFailed.filter((f)=>f.status === 'skipped').map((f)=>({
+            fieldPath: f.fieldPath,
+            locale: f.locale,
+            reason: f.error,
+            reasonCode: f.errorCode,
+            sourceValue: f.sourceValue
+        }));
+    // Emit final event
+    const eventType = realFailed.length === 0 ? 'translation.succeeded' : 'translation.failed';
+    emitEvent(config, {
+        type: eventType,
+        documentId: options.global,
+        collection: options.global,
+        sourceLocale: config.sourceLocale,
+        targetLocales,
+        timestamp: new Date(),
+        fields: [
+            ...allSucceeded,
+            ...allFailed
+        ],
+        usage: totalUsage,
+        error: realFailed.length > 0 ? `${realFailed.length} field(s) failed` : undefined,
+        ...skippedReports.length > 0 ? {
+            skippedFields: skippedReports
+        } : {}
+    });
+    // Persist usage row when feature is enabled. Same contract as the
+    // collection branch — helper short-circuits + swallows errors.
+    await persistTranslationUsage({
+        payload,
+        config,
+        kind: 'global',
+        slug: options.global,
+        documentId: options.global,
+        jobId,
+        status: realFailed.length === 0 ? 'succeeded' : 'failed',
+        sourceLocale: config.sourceLocale,
+        localeOutcomes: bucketLocaleOutcomes(targetLocales, allSucceeded, realFailed),
+        succeededCount: allSucceeded.length,
+        failedCount: realFailed.length,
+        succeeded: allSucceeded,
+        preserved: allPreserved,
+        softSkippedFields: skippedReports,
+        usage: totalUsage,
+        durationMs: Date.now() - startedAt,
+        error: realFailed.length > 0 ? `${realFailed.length} field(s) failed` : undefined
+    });
+    return {
+        jobId,
+        documentId: options.global,
+        collection: options.global,
+        sourceLocale: config.sourceLocale,
+        succeeded: allSucceeded,
+        preserved: allPreserved,
+        failed: allFailed,
+        usage: totalUsage,
+        providerLatencyMs
+    };
+}
+async function translateGlobalForLocale(params) {
+    const { payload, config, sourceDoc, globalSlug, targetLocale, fields, allLocalizedTopFields, writeMode, targetPolicy, signal, req, force } = params;
+    let { units } = params;
+    const succeeded = [];
+    const preserved = [];
+    const failed = [];
+    const totalUsage = {
+        inputTokens: 0,
+        outputTokens: 0,
+        estimatedCostUsd: 0
+    };
+    let providerLatencyMs = 0;
+    if (targetLocale === config.sourceLocale) {
+        return {
+            succeeded,
+            preserved,
+            failed,
+            usage: totalUsage,
+            providerLatencyMs
+        };
+    }
+    // Preserve policy: skip fields that already have content in the target locale
+    if (targetPolicy === 'preserve') {
+        units = await filterPreservedGlobalFields(payload, globalSlug, targetLocale, units, fields);
+    }
+    if (units.length === 0) {
+        return {
+            succeeded,
+            preserved,
+            failed,
+            usage: totalUsage,
+            providerLatencyMs
+        };
+    }
+    // BUG-21 hash-skip preflight for globals (1.2.8). Previously globals
+    // bypassed this path entirely — every re-translate re-hit the LLM for
+    // every field even when the source content was unchanged. Now mirrors
+    // the collection path in `translate.ts`: load stored source+target
+    // hashes, drop units whose top-level field hashes match on both sides,
+    // surface those as hash-skipped successes (characterCount = 0,
+    // durationMs = 0). `force: true` callers bypass — see
+    // `TranslateGlobalOptions.force`.
+    if (config.preserveManualEdits && !force) {
+        const metaSlug = config.manualEditCollectionSlug ?? DEFAULT_MANUAL_EDIT_COLLECTION_SLUG;
+        const skip = await applyHashSkip({
+            payload,
+            metaCollection: metaSlug,
+            surfaceSlug: globalSlug,
+            documentId: globalSlug,
+            targetLocale,
+            units,
+            sourceDoc,
+            loadTargetDoc: ()=>findGlobalNoFallback(payload, globalSlug, targetLocale)
+        });
+        units = skip.remainingUnits;
+        succeeded.push(...skip.hashSkipped);
+        if (units.length === 0) {
+            return {
+                succeeded,
+                preserved,
+                failed,
+                usage: totalUsage,
+                providerLatencyMs
+            };
+        }
+    }
+    const batches = batchUnits(units, config.costLimits.perCallCharLimit, config.costLimits.perCallItemLimit);
+    const retryConfig = {
+        ...DEFAULT_RETRY,
+        ...config.retry ?? {}
+    };
+    const translatedMap = new Map();
+    for (const batch of batches){
+        if (signal?.aborted) {
+            for (const unit of batch){
+                failed.push({
+                    fieldPath: unit.fieldPath,
+                    locale: targetLocale,
+                    status: 'failed',
+                    error: 'Aborted'
+                });
+            }
+            continue;
+        }
+        const batchResult = await translateBatch({
+            batch,
+            config,
+            collection: globalSlug,
+            targetLocale,
+            signal,
+            retryConfig
+        });
+        totalUsage.inputTokens += batchResult.usage.inputTokens;
+        totalUsage.outputTokens += batchResult.usage.outputTokens;
+        totalUsage.estimatedCostUsd = (totalUsage.estimatedCostUsd ?? 0) + (batchResult.usage.estimatedCostUsd ?? 0);
+        totalUsage.model = totalUsage.model ?? batchResult.usage.model;
+        providerLatencyMs += batchResult.latencyMs;
+        for (const unit of batch){
+            const translated = batchResult.translations.get(unit.id);
+            if (translated !== undefined) {
+                translatedMap.set(unit.id, translated);
+                succeeded.push({
+                    fieldPath: unit.fieldPath,
+                    locale: targetLocale,
+                    status: 'success',
+                    characterCount: translated.length,
+                    durationMs: batchResult.latencyMs,
+                    ...unit.kind === 'plain' ? {
+                        translatedText: translated
+                    } : {}
+                });
+            } else if (batchResult.skipped.has(unit.id)) {
+                failed.push({
+                    fieldPath: unit.fieldPath,
+                    locale: targetLocale,
+                    status: 'skipped',
+                    error: batchResult.skipped.get(unit.id),
+                    sourceValue: truncateSourceValue(unit.text)
+                });
+            } else {
+                const err = batchResult.errors.get(unit.id);
+                failed.push({
+                    fieldPath: unit.fieldPath,
+                    locale: targetLocale,
+                    status: 'failed',
+                    error: err ?? 'No translation returned'
+                });
+            }
+        }
+    }
+    // Read the existing target-locale doc and merge translations onto it,
+    // then write only the translated top-level fields. Reading from the
+    // target locale (rather than cloning the source) is what keeps Payload
+    // internal columns from leaking into the update body and lets
+    // required-localized siblings stay populated when we only change a
+    // subset of fields.
+    if (translatedMap.size > 0) {
+        const translatedTopFields = new Set();
+        for (const unit of units){
+            if (translatedMap.has(unit.id)) {
+                translatedTopFields.add(unit.fieldPath.split('.')[0]);
+            }
+        }
+        let targetDoc = null;
+        try {
+            targetDoc = await findGlobalNoFallback(payload, globalSlug, targetLocale);
+        } catch  {
+            targetDoc = null;
+        }
+        const writeData = mergeTranslationsIntoTargetDoc({
+            sourceDoc,
+            targetDoc,
+            translatedMap,
+            fields,
+            translatedTopFields,
+            allLocalizedTopFields,
+            writeMode
+        });
+        // BUG-25 fix: skip the DB write when writeData is empty (everything
+        // got preserved by manual-edit guard or merge produced no diff).
+        // Mirrors the collection-level fix in translate.ts.
+        if (Object.keys(writeData).length === 0) {
+            payload.logger?.info?.(`[ai-translate] No fields to write for global "${globalSlug}" locale=${targetLocale} — skipping payload.updateGlobal.`);
+        } else {
+            try {
+                // See comment in translate.ts — fresh transactionID per locale
+                // write so concurrent updates don't collide on shared junction
+                // tables. `req.user` and friends are preserved for audit-log.
+                const writeReq = req ? {
+                    ...req,
+                    transactionID: undefined
+                } : undefined;
+                // Same allowlist pattern as translateForLocale (translate.ts:478).
+                // Only `disableRevalidate` flows through — naive `...writeReq.context`
+                // would propagate audit-log's AUDIT_CONTEXT_KEY into the global
+                // write's afterChange and mis-attribute the audit row.
+                const forwardedContext = {};
+                if (writeReq?.context && 'disableRevalidate' in writeReq.context) {
+                    forwardedContext.disableRevalidate = writeReq.context.disableRevalidate;
+                }
+                await payload.updateGlobal({
+                    slug: globalSlug,
+                    locale: targetLocale,
+                    data: writeData,
+                    context: {
+                        ...forwardedContext,
+                        [REENTRY_FLAG]: true
+                    },
+                    ...writeReq ? {
+                        req: writeReq
+                    } : {}
+                });
+                // Persist source+target hashes for next-translation hash-skip
+                // (1.2.8). Mirrors `translate.ts` for collections. Best-effort —
+                // failure here doesn't roll back the successful translation write
+                // above.
+                if (config.preserveManualEdits) {
+                    const metaSlug = config.manualEditCollectionSlug ?? DEFAULT_MANUAL_EDIT_COLLECTION_SLUG;
+                    await recordHashesAfterWrite({
+                        payload,
+                        metaCollection: metaSlug,
+                        surfaceSlug: globalSlug,
+                        documentId: globalSlug,
+                        targetLocale,
+                        writeData,
+                        sourceDoc
+                    });
+                }
+            } catch (error) {
+                const errMsg = error instanceof Error ? error.message : 'Unknown write error';
+                payload.logger.error(`[ai-translate] Failed to write translations for global "${globalSlug}" locale=${targetLocale}: ${errMsg}`);
+                for (const result of succeeded){
+                    failed.push({
+                        ...result,
+                        status: 'failed',
+                        error: `Write failed: ${errMsg}`
+                    });
+                }
+                succeeded.length = 0;
+            }
+        } // end else (non-empty)
+    }
+    // Emit per-field events
+    const isCanary = targetLocale === config.quality?.canaryLocale;
+    for (const result of [
+        ...succeeded,
+        ...failed
+    ]){
+        emitEvent(config, {
+            type: 'translation.field',
+            documentId: globalSlug,
+            collection: globalSlug,
+            sourceLocale: config.sourceLocale,
+            targetLocales: [
+                targetLocale
+            ],
+            timestamp: new Date(),
+            fields: [
+                result
+            ],
+            canary: isCanary || undefined
+        });
+    }
+    return {
+        succeeded,
+        preserved,
+        failed,
+        usage: totalUsage,
+        providerLatencyMs
+    };
+}
+// ---------------------------------------------------------------------------
+// Global preserve-policy filter
+// ---------------------------------------------------------------------------
+async function filterPreservedGlobalFields(payload, globalSlug, targetLocale, units, fields) {
+    try {
+        const targetDoc = await payload.findGlobal({
+            slug: globalSlug,
+            locale: targetLocale,
+            fallbackLocale: NO_FALLBACK
+        });
+        return units.filter((unit)=>{
+            const field = fields.find((f)=>unit.fieldPath === f.path || unit.fieldPath.startsWith(`${f.path}.`));
+            if (!field) return true;
+            const targetValue = resolvePathValue(targetDoc, field.path);
+            return isFieldEmpty(targetValue, field.type);
+        });
+    } catch  {
+        return units;
+    }
+}
+function resolvePathValue(obj, path) {
+    const segments = path.split('.');
+    let current = obj;
+    for (const segment of segments){
+        if (current == null || typeof current !== 'object') return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function getCollectionFields(payload, collectionSlug) {
+    const collections = payload.config?.collections ?? [];
+    const collection = collections.find((c)=>c.slug === collectionSlug);
+    return collection?.fields;
+}
+function getGlobalFields(payload, globalSlug) {
+    const globals = payload.config?.globals ?? [];
+    const global = globals.find((g)=>g.slug === globalSlug);
+    return global?.fields;
+}