@purposeinplay/payload-ai-translate 0.1.0

package/dist/plugin.js

@@ -0,0 +1,934 @@
+import { createAlertsCollection } from './alerts-collection.js';
+import { translateDocument, translateGlobal } from './api.js';
+// Bulk-translate engine (v1.2.0+). All gated on `options.bulk?.enabled`.
+import { createBulkTranslateBatchesCollection, DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG } from './bulk-translate-batches-collection.js';
+import { createBulkTranslateUnitsCollection, DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG } from './bulk-translate-units-collection.js';
+import { DEFAULT_ALERTS_COLLECTION_SLUG, DEFAULT_COALESCING_WINDOW_MS, DEFAULT_CONCURRENCY, DEFAULT_USAGE_COLLECTION_SLUG } from './defaults.js';
+import { getClientConfigHandler } from './endpoints/client-config.js';
+import { getEstimateHandler } from './endpoints/estimate.js';
+import { getProgressHandler } from './endpoints/progress.js';
+import { getTranslateHandler } from './endpoints/translate.js';
+import { getBulkTranslateActiveHandler } from './endpoints/translation-hub/active.js';
+import { getBulkTranslateCancelHandler } from './endpoints/translation-hub/cancel.js';
+import { getBulkTranslateEnqueueHandler } from './endpoints/translation-hub/enqueue.js';
+import { getBulkTranslateFailuresHandler } from './endpoints/translation-hub/failures.js';
+import { getBulkTranslateForceResetHandler } from './endpoints/translation-hub/force-reset.js';
+import { getBulkTranslateListHandler } from './endpoints/translation-hub/list.js';
+import { getBulkTranslatePreflightHandler } from './endpoints/translation-hub/preflight.js';
+import { getBulkTranslateRetryFailedHandler } from './endpoints/translation-hub/retry-failed.js';
+import { getBulkTranslateRevertHandler } from './endpoints/translation-hub/revert.js';
+import { getBulkTranslateStatusHandler } from './endpoints/translation-hub/status.js';
+import { getTranslationHubUsageSummaryHandler } from './endpoints/translation-hub/usage-summary.js';
+import { createTranslateAfterChangeHook } from './hooks/after-change.js';
+import { createTranslateGlobalAfterChangeHook } from './hooks/after-change-global.js';
+import { createAiTranslateAfterDeleteHook } from './hooks/after-delete.js';
+import { createJobsCollection, DEFAULT_JOBS_COLLECTION_SLUG } from './jobs-collection.js';
+import { ensureBulkTranslateSchema } from './lib/bulk-translate-migrations.js';
+import { createCoalescingQueue } from './lib/coalescing-queue.js';
+import { setAlertsContext } from './lib/events.js';
+import { getEffectiveExcludePatterns, isExcluded } from './lib/exclude-fields.js';
+import { setPersistenceContext } from './lib/progress-store.js';
+import { createRateLimiter } from './lib/rate-limiter.js';
+import { createManualEditMetaCollection, DEFAULT_MANUAL_EDIT_COLLECTION_SLUG } from './manual-edit-collection.js';
+import { createSettingsGlobal } from './settings-global.js';
+import { BULK_TRANSLATE_COORDINATOR_SLUG, BULK_TRANSLATE_DOC_TASK_SLUG, buildBulkTranslateCoordinator } from './tasks/bulk-translate-coordinator.js';
+import { buildBulkTranslateDocTask } from './tasks/bulk-translate-doc-task.js';
+import { BULK_TRANSLATE_JANITOR_SLUG, buildBulkTranslateJanitor, runJanitorSweep } from './tasks/bulk-translate-janitor.js';
+import { buildTranslateDocumentTask, buildTranslateGlobalTask, TRANSLATE_DOCUMENT_TASK_SLUG, TRANSLATE_GLOBAL_TASK_SLUG } from './tasks/translate-job-task.js';
+import { createTranslationDailySpendCollection } from './translation-daily-spend-collection.js';
+import { createTranslationRateLimitsCollection } from './translation-rate-limits-collection.js';
+import { createUsageCollection } from './usage-collection.js';
+export function aiTranslatePlugin(options) {
+    return (incomingConfig)=>{
+        const config = {
+            ...incomingConfig
+        };
+        config.custom = {
+            ...config.custom ?? {},
+            aiTranslate: options
+        };
+        // Expose a serializable subset of plugin config to the admin client
+        // bundle. The full `options` object contains provider function
+        // references (`translate`, `estimate`) that Payload's admin builder
+        // strips during client serialization — the client-side modal can
+        // only read JSON-safe fields. Writing this subset to a stable path
+        // (`config.custom.aiTranslateClient`) lets the Translate drawer
+        // restrict its locale picker to `targetLocales` without an extra
+        // round-trip.
+        config.custom.aiTranslateClient = {
+            sourceLocale: options.sourceLocale,
+            targetLocales: [
+                ...options.targetLocales
+            ],
+            perFieldButton: !!options.perFieldButton
+        };
+        if (options.enabled === false) {
+            return config;
+        }
+        // Validate required config
+        if (!options.sourceLocale) {
+            throw new Error('[ai-translate] sourceLocale is required');
+        }
+        if (!options.targetLocales?.length) {
+            throw new Error('[ai-translate] targetLocales must contain at least one locale');
+        }
+        if (!options.provider) {
+            throw new Error('[ai-translate] provider is required');
+        }
+        if (!options.costLimits) {
+            throw new Error('[ai-translate] costLimits is required');
+        }
+        if (!options.costLimits.perCallCharLimit) {
+            throw new Error('[ai-translate] costLimits.perCallCharLimit is required');
+        }
+        if (!options.costLimits.perDocCharCeiling) {
+            throw new Error('[ai-translate] costLimits.perDocCharCeiling is required');
+        }
+        if (!options.costLimits.bulkConfirmUsdThreshold) {
+            throw new Error('[ai-translate] costLimits.bulkConfirmUsdThreshold is required');
+        }
+        // Validate locale overlap
+        if (options.targetLocales.includes(options.sourceLocale)) {
+            console.warn(`[ai-translate] targetLocales includes sourceLocale "${options.sourceLocale}". It will be skipped during translation.`);
+        }
+        // Create rate limiter for provider calls
+        const rpm = options.concurrency?.perProvider ?? DEFAULT_CONCURRENCY.perProvider;
+        options._rateLimiter = createRateLimiter(rpm);
+        // Top-level client-config endpoint. Payload's admin bundle strips
+        // function refs from `config.custom`, so the Translate drawer can't
+        // read `targetLocales` directly via `useConfig()`. This endpoint
+        // exposes the JSON-safe subset (`sourceLocale`, `targetLocales`,
+        // `perFieldButton`) over `/api/ai-translate/client-config`, which
+        // the drawer fetches on open. Without it, the drawer falls back to
+        // listing every non-source locale Payload has registered — fine,
+        // just shows more choices than the plugin can translate to.
+        config.endpoints = [
+            ...Array.isArray(config.endpoints) ? config.endpoints : [],
+            {
+                handler: getClientConfigHandler(),
+                method: 'get',
+                path: '/ai-translate/client-config'
+            }
+        ];
+        // Auto-register the usage-tracking collection. Mirrors auditLogPlugin's
+        // collection-registration call site. No-op when feature is disabled or
+        // not configured, preserving today's behavior for projects that opt out.
+        if (options.usageTracking?.enabled) {
+            const usageSlug = options.usageTracking.collectionSlug ?? DEFAULT_USAGE_COLLECTION_SLUG;
+            const usageCollection = createUsageCollection(options.usageTracking.access?.read, usageSlug);
+            config.collections = [
+                ...config.collections ?? [],
+                usageCollection
+            ];
+        }
+        // Auto-register the alerts collection. Gated on usageTracking — if a
+        // consumer hasn't opted into usage tracking they likely don't want
+        // alerts persistence either (both feed the Hub). The collection is
+        // additive (creates a new table), so opt-in is the safe default.
+        // Alert persistence is best-effort in `emitAlert`; the consumer's
+        // `onAlert` callback still fires regardless for back-compat.
+        if (options.usageTracking?.enabled) {
+            const alertsSlug = options.alertsCollectionSlug ?? DEFAULT_ALERTS_COLLECTION_SLUG;
+            const alertsCollection = createAlertsCollection(options.usageTracking.access?.read, alertsSlug);
+            config.collections = [
+                ...config.collections ?? [],
+                alertsCollection
+            ];
+        }
+        // Auto-register the manual-edit-meta sidecar collection. Holds per-
+        // (collection, doc, locale, field) hashes of the last value the
+        // plugin wrote, so the writer can detect manual edits and skip
+        // overwriting them. See `preserveManualEdits` in types.ts.
+        if (options.preserveManualEdits) {
+            const metaSlug = options.manualEditCollectionSlug ?? DEFAULT_MANUAL_EDIT_COLLECTION_SLUG;
+            const metaCollection = createManualEditMetaCollection(undefined, metaSlug);
+            config.collections = [
+                ...config.collections ?? [],
+                metaCollection
+            ];
+        }
+        // Auto-register the jobs sidecar collection. Mirrors in-memory
+        // job state so a server restart doesn't lose admin visibility
+        // into in-flight translations. See `persistJobs` in types.ts.
+        if (options.persistJobs) {
+            const jobsSlug = options.jobsCollectionSlug ?? DEFAULT_JOBS_COLLECTION_SLUG;
+            const jobsCollection = createJobsCollection(undefined, jobsSlug);
+            config.collections = [
+                ...config.collections ?? [],
+                jobsCollection
+            ];
+            // Register the two Payload tasks the coalescing queue enqueues
+            // into. Without these, the queue worker's `payload.jobs.queue`
+            // call below would fail with "unknown task". Additive — never
+            // overwrites consumer-defined tasks.
+            config.jobs = config.jobs ?? {
+                tasks: []
+            };
+            const existingTasks = Array.isArray(config.jobs.tasks) ? config.jobs.tasks : [];
+            const hasDocTask = existingTasks.some((t)=>t.slug === TRANSLATE_DOCUMENT_TASK_SLUG);
+            const hasGlobalTask = existingTasks.some((t)=>t.slug === TRANSLATE_GLOBAL_TASK_SLUG);
+            config.jobs.tasks = [
+                ...existingTasks,
+                ...hasDocTask ? [] : [
+                    buildTranslateDocumentTask(options.collections ?? [])
+                ],
+                ...hasGlobalTask ? [] : [
+                    buildTranslateGlobalTask(options.globals ?? [])
+                ]
+            ];
+        }
+        // ---------------------------------------------------------------
+        // Bulk-translate engine (v1.2.0+). Auto-registers when the
+        // `options.bulk` block is present. Pass `enabled: false`
+        // explicitly to opt out — the real cost guards are
+        // `dailyUsdCap` + `requireTotp` + admin-role auth, not this
+        // flag. (Prior versions defaulted off, requiring `enabled:
+        // true` opt-in; the inversion landed in v1.2.3.)
+        // ---------------------------------------------------------------
+        if (options.bulk && options.bulk.enabled !== false) {
+            const bulkConfig = options.bulk;
+            const allowedCollectionsForBulk = (options.collections ?? []).filter((slug)=>!(bulkConfig.excludeCollections ?? []).includes(slug));
+            const allowedGlobalsForBulk = options.globals ?? [];
+            // (1) Collections — batches, units, daily-spend, rate-limits.
+            const bulkCollections = [
+                createBulkTranslateBatchesCollection(),
+                createBulkTranslateUnitsCollection(),
+                createTranslationDailySpendCollection(),
+                createTranslationRateLimitsCollection()
+            ];
+            config.collections = [
+                ...config.collections ?? [],
+                ...bulkCollections
+            ];
+            // (2) Tasks — coordinator, worker, janitor.
+            config.jobs = config.jobs ?? {
+                tasks: []
+            };
+            const tasks = Array.isArray(config.jobs.tasks) ? config.jobs.tasks : [];
+            const hasCoordinator = tasks.some((t)=>t.slug === BULK_TRANSLATE_COORDINATOR_SLUG);
+            const hasBulkWorker = tasks.some((t)=>t.slug === BULK_TRANSLATE_DOC_TASK_SLUG);
+            const hasJanitor = tasks.some((t)=>t.slug === BULK_TRANSLATE_JANITOR_SLUG);
+            config.jobs.tasks = [
+                ...tasks,
+                ...hasCoordinator ? [] : [
+                    buildBulkTranslateCoordinator()
+                ],
+                ...hasBulkWorker ? [] : [
+                    buildBulkTranslateDocTask({
+                        allowedCollections: allowedCollectionsForBulk,
+                        allowedGlobals: allowedGlobalsForBulk,
+                        callbacks: {
+                            onBatchComplete: bulkConfig.onBatchComplete,
+                            onBatchFailed: bulkConfig.onBatchFailed
+                        }
+                    })
+                ],
+                ...hasJanitor ? [] : [
+                    buildBulkTranslateJanitor({
+                        callbacks: {
+                            onBatchComplete: bulkConfig.onBatchComplete,
+                            onBatchFailed: bulkConfig.onBatchFailed
+                        }
+                    })
+                ]
+            ];
+            // (3) Endpoints — POST/GET handlers under /api/translation-hub.
+            // Handlers resolve admin roles, providers, locales, etc. at
+            // request time from `req.payload.config.custom.aiTranslate`
+            // (set at line 50). Plugin config flows through that channel.
+            // Factory options here are only slug overrides.
+            const bulkEndpointBase = '/translation-hub/bulk-translate';
+            const retryFailedHandler = getBulkTranslateRetryFailedHandler();
+            config.endpoints = [
+                ...Array.isArray(config.endpoints) ? config.endpoints : [],
+                {
+                    handler: getBulkTranslateEnqueueHandler(),
+                    method: 'post',
+                    path: bulkEndpointBase
+                },
+                {
+                    handler: getBulkTranslateListHandler(),
+                    method: 'get',
+                    path: bulkEndpointBase
+                },
+                {
+                    handler: getBulkTranslateActiveHandler(),
+                    method: 'get',
+                    path: `${bulkEndpointBase}/active`
+                },
+                {
+                    handler: getBulkTranslatePreflightHandler(),
+                    method: 'get',
+                    path: `${bulkEndpointBase}/preflight`
+                },
+                {
+                    handler: getBulkTranslateStatusHandler(),
+                    method: 'get',
+                    path: `${bulkEndpointBase}/:id/status`
+                },
+                {
+                    handler: getBulkTranslateFailuresHandler(),
+                    method: 'get',
+                    path: `${bulkEndpointBase}/:id/failures`
+                },
+                {
+                    handler: retryFailedHandler,
+                    method: 'post',
+                    path: `${bulkEndpointBase}/:id/retry-failed`
+                },
+                // UI hits `/retry` (shorter); register the same handler under
+                // both paths so consumers that call either keep working.
+                {
+                    handler: retryFailedHandler,
+                    method: 'post',
+                    path: `${bulkEndpointBase}/:id/retry`
+                },
+                {
+                    handler: getBulkTranslateCancelHandler(),
+                    method: 'post',
+                    path: `${bulkEndpointBase}/:id/cancel`
+                },
+                {
+                    handler: getBulkTranslateRevertHandler(),
+                    method: 'post',
+                    path: `${bulkEndpointBase}/:id/revert`
+                },
+                {
+                    handler: getBulkTranslateForceResetHandler(),
+                    method: 'post',
+                    path: `${bulkEndpointBase}/:id/force-reset`
+                },
+                // Hub-level (not bulk-translate-specific) — server-side
+                // aggregation for Overview + Audit KPIs. NEW-15 (v1.2.6):
+                // replaces the prior `/translation-usage?limit=1000` pattern
+                // that silently truncated past 1000 rows.
+                {
+                    handler: getTranslationHubUsageSummaryHandler(),
+                    method: 'get',
+                    path: '/translation-hub/usage-summary'
+                }
+            ];
+            // (4) Schema migration: idempotent CREATE UNIQUE INDEX IF NOT
+            // EXISTS for the partial unique index that backs F-DA-TOCTOU.
+            // Wraps the consumer's existing onInit so we don't clobber it.
+            const consumerOnInit = config.onInit;
+            config.onInit = async (payload)=>{
+                if (consumerOnInit) {
+                    await consumerOnInit(payload);
+                }
+                try {
+                    await ensureBulkTranslateSchema(payload);
+                } catch (err) {
+                    payload.logger?.warn?.(`[ai-translate] bulk-translate schema bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            };
+        }
+        // Track which collections / globals are configured for translation
+        const trackedCollections = options.collections ?? [];
+        const trackedGlobals = options.globals ?? [];
+        // Auto-register the translation-settings global. The global carries
+        // three sets of fields: an `activeProvider` selector (only meaningful
+        // when `providers` map has multiple entries), an `enabledTargetLocales`
+        // toggle (always meaningful as long as `targetLocales` are configured),
+        // and a `perCollection` array letting admins override the site-wide
+        // settings per surface.
+        const providerKeys = Object.keys(options.providers ?? {});
+        const settingsEnabled = options.targetLocales.length > 0 && options.settings?.enabled !== false;
+        if (settingsEnabled) {
+            const settingsGlobal = createSettingsGlobal(providerKeys, options.targetLocales, options.settings, [
+                ...trackedCollections,
+                ...trackedGlobals
+            ]);
+            config.globals = [
+                ...config.globals ?? [],
+                settingsGlobal
+            ];
+        }
+        // Pre-resolve the admin-role gate so both injection sites share the
+        // same check function. Defaults to ['admin'] for back-compat. Pass
+        // `adminRoles: ['super-admin']` etc. to support different role naming.
+        const adminRoles = Array.isArray(options.adminRoles) ? options.adminRoles : [
+            'admin'
+        ];
+        // Loose `args: any` because Payload's `FieldAccess` typing has
+        // `req.user: UntypedUser | null` (no roles property until consumers
+        // generate types). At runtime the user shape always has `roles`
+        // when the consumer uses Payload's auth — we read defensively.
+        const isAdminFromReq = (args)=>{
+            if (adminRoles.length === 0) return true; // explicit "everyone" opt-in
+            const roles = args?.req?.user?.roles;
+            if (!Array.isArray(roles)) return false;
+            return roles.some((r)=>typeof r === 'string' && adminRoles.includes(r));
+        };
+        // Automation: create coalescing queue if async mode. The queue is shared
+        // by both collection and global hooks — they dispatch to the right
+        // translate function via `entry.kind`.
+        let queue = null;
+        if (options.automation && options.automation.mode !== 'inline') {
+            const windowMs = options.automation.coalescingWindowMs ?? DEFAULT_COALESCING_WINDOW_MS;
+            queue = createCoalescingQueue(windowMs, async (entry)=>{
+                // When `persistJobs: true`, hand the work off to Payload's
+                // native jobs queue. The translation closure (`req`, doc id,
+                // `previousDoc`, target locales) is serialized into the
+                // job's input — Payload's cron worker re-runs the task if
+                // the process restarts before it completes. Without this
+                // flag we fall back to the original in-memory fire-and-
+                // forget path, which is faster but loses pending work on
+                // restart.
+                if (options.persistJobs) {
+                    try {
+                        if (entry.kind === 'global') {
+                            await entry.payload.jobs.queue({
+                                task: TRANSLATE_GLOBAL_TASK_SLUG,
+                                input: {
+                                    global: entry.collection,
+                                    jobId: entry.jobId,
+                                    targetLocales: entry.targetLocales ?? null,
+                                    previousDoc: entry.previousDoc ?? null
+                                }
+                            });
+                        } else {
+                            await entry.payload.jobs.queue({
+                                task: TRANSLATE_DOCUMENT_TASK_SLUG,
+                                input: {
+                                    collection: entry.collection,
+                                    documentId: String(entry.id),
+                                    jobId: entry.jobId,
+                                    targetLocales: entry.targetLocales ?? null,
+                                    previousDoc: entry.previousDoc ?? null,
+                                    draft: true
+                                }
+                            });
+                        }
+                        // Best-effort immediate run so the user-visible latency
+                        // matches the previous in-memory behavior. If `runByID`
+                        // isn't available on this Payload version (older
+                        // versions only exposed `run`), the cron will still pick
+                        // it up.
+                        void entry.payload.jobs.run?.({
+                            queue: 'default',
+                            limit: 1
+                        }).catch(()=>{});
+                        return;
+                    } catch (err) {
+                        entry.payload.logger?.error?.(`[ai-translate] Failed to enqueue persisted job for ${entry.collection}/${entry.kind === 'global' ? '<global>' : String(entry.id)}: ${err instanceof Error ? err.message : 'Unknown error'}. Falling back to in-process translation.`);
+                    // Fall through to the original in-process path so a
+                    // jobs-queue outage doesn't drop the work entirely.
+                    }
+                }
+                if (entry.kind === 'global') {
+                    await translateGlobal(entry.payload, {
+                        global: entry.collection,
+                        previousDoc: entry.previousDoc,
+                        jobId: entry.jobId,
+                        req: entry.req,
+                        targetLocales: entry.targetLocales
+                    });
+                    return;
+                }
+                await translateDocument(entry.payload, {
+                    collection: entry.collection,
+                    id: entry.id,
+                    previousDoc: entry.previousDoc,
+                    // Reuse the job seeded by the after-change hook so the polling UI
+                    // doesn't see two jobs for the same doc (one phantom, one real).
+                    jobId: entry.jobId,
+                    req: entry.req,
+                    targetLocales: entry.targetLocales
+                });
+            });
+        }
+        // Inject endpoints, hooks, and UI field on configured collections
+        // IMPORTANT: mutate and return the ORIGINAL collection object.
+        // Payload captures object references during buildConfig — shallow copies
+        // via spread create new references whose hooks Payload never sees.
+        config.collections = (config.collections ?? []).map((collection)=>{
+            if (!trackedCollections.includes(collection.slug)) {
+                return collection;
+            }
+            // Use the original — do NOT spread into a copy
+            const matchedCollection = collection;
+            // --- Endpoints ---
+            const existingEndpoints = matchedCollection.endpoints ?? [];
+            matchedCollection.endpoints = [
+                ...Array.isArray(existingEndpoints) ? existingEndpoints : [],
+                {
+                    handler: getTranslateHandler({
+                        kind: 'collection',
+                        slug: collection.slug
+                    }),
+                    method: 'post',
+                    path: '/ai-translate'
+                },
+                {
+                    handler: getEstimateHandler({
+                        kind: 'collection',
+                        slug: collection.slug
+                    }),
+                    method: 'post',
+                    path: '/ai-translate/estimate'
+                },
+                {
+                    handler: getProgressHandler(collection.slug),
+                    method: 'get',
+                    path: '/ai-translate/progress'
+                }
+            ];
+            // --- Per-doc auto-translate widgets ---
+            //
+            // Two sibling fields control per-doc auto-translate behavior:
+            //
+            // 1. `_aiTranslateAutoLocales` (select hasMany) — NARROW which
+            //    locales fan out on this doc. Empty / unset = inherit
+            //    collection-level decision (no narrowing). Non-empty =
+            //    restrict to these locales.
+            //
+            // 2. `_aiTranslateOptOut` (checkbox) — SKIP auto-translate
+            //    entirely for this doc. Unchecked = participate normally;
+            //    checked = bail before any locale work.
+            //
+            // Why two fields instead of overloading the array's empty state:
+            // Payload's hasMany select can't distinguish "admin cleared
+            // every checkbox" from "admin never touched the widget" — both
+            // serialize to 0 rows. Pre-fix versions treated empty as
+            // opt-out, which made auto-translate dead-by-default for every
+            // new doc (the inherit state was unreachable). Splitting the
+            // intents into distinct fields fixes that: empty array ALWAYS
+            // means inherit; opt-out is a separate, explicit boolean.
+            //
+            // `localized: false` on both: a per-locale value would let one
+            // locale clobber another. `access.update` is admin-only because
+            // they gate billable LLM spend; editors see the fields but they
+            // render read-only.
+            matchedCollection.fields = [
+                ...matchedCollection.fields,
+                {
+                    name: '_aiTranslateOptOut',
+                    label: 'Skip auto-translate',
+                    type: 'checkbox',
+                    defaultValue: false,
+                    required: false,
+                    localized: false,
+                    access: {
+                        update: isAdminFromReq
+                    },
+                    admin: {
+                        position: 'sidebar',
+                        description: 'Admin only. Check to skip auto-translate entirely for this document on publish. Manual Translate from the dialog still works. Leave unchecked to participate in normal auto-translate.'
+                    }
+                },
+                {
+                    name: '_aiTranslateAutoLocales',
+                    label: 'Auto-translate locales',
+                    type: 'select',
+                    hasMany: true,
+                    required: false,
+                    localized: false,
+                    options: options.targetLocales.map((code)=>({
+                            label: code,
+                            value: code
+                        })),
+                    // Reject locale codes not in the plugin's configured
+                    // `targetLocales`. The select's option list constrains the
+                    // admin form, but the REST/GraphQL API path accepts arbitrary
+                    // values — without this guard, an API write with
+                    // `_aiTranslateAutoLocales: ['xx', 'yy']` would persist and
+                    // silently narrow the intersection to empty downstream.
+                    validate: (value)=>{
+                        if (value === null || value === undefined) return true;
+                        if (!Array.isArray(value)) {
+                            return 'Must be an array of locale codes.';
+                        }
+                        const universe = new Set(options.targetLocales);
+                        const bad = value.filter((v)=>typeof v !== 'string' || !universe.has(v));
+                        if (bad.length > 0) {
+                            return `Unknown locale(s): ${bad.join(', ')}. Must be one of: ${options.targetLocales.join(', ')}.`;
+                        }
+                        return true;
+                    },
+                    access: {
+                        update: isAdminFromReq
+                    },
+                    admin: {
+                        position: 'sidebar',
+                        description: 'Admin only. Narrow which target locales auto-translate on publish for this document. Leave empty to inherit the collection default (translate to every enabled locale). Pick specific locales to translate to ONLY those. To skip auto-translate entirely for this doc, use the "Skip auto-translate" checkbox above — clearing this list does NOT opt out.'
+                    }
+                },
+                {
+                    name: '_aiTranslate',
+                    type: 'ui',
+                    admin: {
+                        position: 'sidebar',
+                        condition: (data)=>Boolean(data?.id),
+                        components: {
+                            Field: '@purposeinplay/payload-ai-translate/client#TranslateButton'
+                        }
+                    }
+                }
+            ];
+            // --- Per-field translate button (opt-in) ---
+            if (options.perFieldButton) {
+                matchedCollection.fields = injectFieldButtons(matchedCollection.fields, getEffectiveExcludePatterns(options));
+            }
+            // --- Automation hooks (only if automation config present) ---
+            if (options.automation) {
+                const automation = options.automation;
+                // Drafts detection: warn if on-change trigger + drafts enabled
+                const hasDrafts = !!(collection.versions && typeof collection.versions === 'object' && collection.versions.drafts);
+                if (hasDrafts && automation.trigger !== 'on-publish') {
+                    console.warn(`[ai-translate] Collection "${collection.slug}" has drafts enabled but automation trigger is "${automation.trigger ?? 'on-change'}". ` + `This will translate on every autosave. Consider using trigger: 'on-publish'.`);
+                }
+                const hook = createTranslateAfterChangeHook({
+                    collectionSlug: collection.slug,
+                    pluginOptions: options,
+                    queue,
+                    hasDrafts
+                });
+                // Mutate the ORIGINAL collection's hooks array in-place.
+                // Payload captures hook references during buildConfig before plugins
+                // return. Replacing the hooks object via spread creates a new reference
+                // that Payload never sees. We must push onto the original array.
+                if (!collection.hooks) {
+                    collection.hooks = {};
+                }
+                if (!collection.hooks.afterChange) {
+                    collection.hooks.afterChange = [];
+                }
+                collection.hooks.afterChange.unshift(hook);
+            }
+            // BUG-20 + BUG-26 — after-delete cleanup: cancel in-memory jobs +
+            // purge `ai_translate_jobs` and `ai_translate_meta` rows for the
+            // deleted doc. Registered unconditionally (no `automation` gate)
+            // because the storage tables can hold rows from earlier translate
+            // calls regardless of whether automation is on now.
+            const deleteHook = createAiTranslateAfterDeleteHook(collection.slug, options);
+            if (!collection.hooks.afterDelete) {
+                collection.hooks.afterDelete = [];
+            }
+            collection.hooks.afterDelete.unshift(deleteHook);
+            return matchedCollection;
+        });
+        // Globals: register endpoints + UI + after-change hook on configured globals.
+        // Mirrors the collection branch so manual translate, per-field buttons,
+        // estimate/progress endpoints, and auto-translate all work for globals too.
+        if (trackedGlobals.length > 0 && config.globals) {
+            config.globals = config.globals.map((global)=>{
+                if (!global.slug || !trackedGlobals.includes(global.slug)) {
+                    return global;
+                }
+                const matchedGlobal = global;
+                // --- Endpoints ---
+                const existingEndpoints = matchedGlobal.endpoints ?? [];
+                matchedGlobal.endpoints = [
+                    ...Array.isArray(existingEndpoints) ? existingEndpoints : [],
+                    {
+                        handler: getTranslateHandler({
+                            kind: 'global',
+                            slug: global.slug
+                        }),
+                        method: 'post',
+                        path: '/ai-translate'
+                    },
+                    {
+                        handler: getEstimateHandler({
+                            kind: 'global',
+                            slug: global.slug
+                        }),
+                        method: 'post',
+                        path: '/ai-translate/estimate'
+                    },
+                    {
+                        handler: getProgressHandler(global.slug),
+                        method: 'get',
+                        path: '/ai-translate/progress'
+                    }
+                ];
+                // --- Per-doc auto-translate widgets ---
+                // See collection branch above for the full rationale on why
+                // these are two separate fields instead of a single 3-state array.
+                //
+                // The descriptions say "on save" rather than "on publish":
+                // globals in Payload don't have a publish gate (no draft
+                // state by default), so every save fires after-change. Editors
+                // should know that auto-translate flows differently here.
+                //
+                // Globals don't have a numeric `id`, but they always exist once
+                // saved. The sidebar Translate button renders unconditionally —
+                // the client component reads the global slug from
+                // useDocumentInfo to build URLs.
+                matchedGlobal.fields = [
+                    ...matchedGlobal.fields,
+                    {
+                        name: '_aiTranslateOptOut',
+                        label: 'Skip auto-translate',
+                        type: 'checkbox',
+                        defaultValue: false,
+                        required: false,
+                        localized: false,
+                        access: {
+                            update: isAdminFromReq
+                        },
+                        admin: {
+                            position: 'sidebar',
+                            description: 'Admin only. Check to skip auto-translate entirely for this global on save. Manual Translate from the dialog still works. Leave unchecked to participate in normal auto-translate.'
+                        }
+                    },
+                    {
+                        name: '_aiTranslateAutoLocales',
+                        label: 'Auto-translate locales',
+                        type: 'select',
+                        hasMany: true,
+                        required: false,
+                        localized: false,
+                        options: options.targetLocales.map((code)=>({
+                                label: code,
+                                value: code
+                            })),
+                        validate: (value)=>{
+                            if (value === null || value === undefined) return true;
+                            if (!Array.isArray(value)) {
+                                return 'Must be an array of locale codes.';
+                            }
+                            const universe = new Set(options.targetLocales);
+                            const bad = value.filter((v)=>typeof v !== 'string' || !universe.has(v));
+                            if (bad.length > 0) {
+                                return `Unknown locale(s): ${bad.join(', ')}. Must be one of: ${options.targetLocales.join(', ')}.`;
+                            }
+                            return true;
+                        },
+                        access: {
+                            update: isAdminFromReq
+                        },
+                        admin: {
+                            position: 'sidebar',
+                            description: 'Admin only. Narrow which target locales auto-translate on save for this global. Leave empty to inherit defaults (translate to every enabled locale). Pick specific locales to translate to ONLY those. To skip auto-translate entirely, use the "Skip auto-translate" checkbox above — clearing this list does NOT opt out.'
+                        }
+                    },
+                    {
+                        name: '_aiTranslate',
+                        type: 'ui',
+                        admin: {
+                            position: 'sidebar',
+                            components: {
+                                Field: '@purposeinplay/payload-ai-translate/client#TranslateButton'
+                            }
+                        }
+                    }
+                ];
+                // --- Per-field translate button (opt-in) ---
+                if (options.perFieldButton) {
+                    matchedGlobal.fields = injectFieldButtons(matchedGlobal.fields, getEffectiveExcludePatterns(options));
+                }
+                // --- Auto-translate hook ---
+                if (options.automation) {
+                    // Reuse the same coalescing queue collections use, so a burst
+                    // of saves on a global (e.g. autosave debouncer firing rapidly)
+                    // collapses into a single translation pass.
+                    const hook = createTranslateGlobalAfterChangeHook(global.slug, options, queue);
+                    if (!global.hooks) {
+                        global.hooks = {};
+                    }
+                    if (!global.hooks.afterChange) {
+                        global.hooks.afterChange = [];
+                    }
+                    global.hooks.afterChange.unshift(hook);
+                }
+                return matchedGlobal;
+            });
+        }
+        // Wire the progress-store's persistence target. Done in `onInit`
+        // because we need a live `payload` instance, which only exists
+        // post-config-build. The plugin sequence here only mutates config —
+        // the actual mirror writes happen later when `createJob`/
+        // `updateJob`/`cleanup` fire during translation.
+        if (options.persistJobs) {
+            const existingOnInit = config.onInit;
+            const jobsSlug = options.jobsCollectionSlug ?? DEFAULT_JOBS_COLLECTION_SLUG;
+            config.onInit = async (payload)=>{
+                if (existingOnInit) {
+                    await existingOnInit(payload);
+                }
+                setPersistenceContext({
+                    payload: payload,
+                    collectionSlug: jobsSlug
+                });
+            };
+        }
+        // Wire the alerts persistence target. Gated on usageTracking — same
+        // gate that auto-registers the alerts collection. The module-scoped
+        // ref is read by `emitAlert` in lib/events.ts on every alert emission.
+        if (options.usageTracking?.enabled) {
+            const existingOnInit = config.onInit;
+            const alertsSlug = options.alertsCollectionSlug ?? DEFAULT_ALERTS_COLLECTION_SLUG;
+            config.onInit = async (payload)=>{
+                if (existingOnInit) {
+                    await existingOnInit(payload);
+                }
+                setAlertsContext({
+                    payload: payload,
+                    collectionSlug: alertsSlug
+                });
+            };
+        }
+        // Drive the janitor sweep. The task is registered as a Payload
+        // job, but Payload's `autoRun` only runs *queued* jobs — it does
+        // not auto-enqueue tasks on a schedule. Without an explicit driver
+        // here, the janitor never fires and stuck `running` units stay
+        // stuck forever after a worker crash or container restart. We
+        // drive it from `onInit` with two layers:
+        //
+        //   1. Boot sweep — runs once immediately so a process that comes
+        //      up after a crash reclaims orphaned units from the previous
+        //      lifetime within ~10s of becoming healthy.
+        //   2. Periodic sweep — every `bulk.janitorIntervalMs` (default
+        //      5 min) for the life of the process, so a worker dying
+        //      mid-run also gets cleaned up without waiting for a restart.
+        //
+        // In serverless / short-lived process deployments the periodic
+        // setInterval simply never fires (process is killed between
+        // invocations), but the boot sweep still runs on each cold start —
+        // which is exactly when stuck units would otherwise be problematic.
+        if (options.bulk && options.bulk.enabled !== false) {
+            const bulkConfigForJanitor = options.bulk;
+            const existingOnInit = config.onInit;
+            const unitsSlug = bulkConfigForJanitor.unitsCollectionSlug ?? DEFAULT_BULK_TRANSLATE_UNITS_COLLECTION_SLUG;
+            const usageSlug = options.usageTracking?.collectionSlug ?? DEFAULT_USAGE_COLLECTION_SLUG;
+            const janitorIntervalMs = bulkConfigForJanitor.janitorIntervalMs ?? 5 * 60_000;
+            config.onInit = async (payload)=>{
+                if (existingOnInit) {
+                    await existingOnInit(payload);
+                }
+                const sweep = async (label)=>{
+                    try {
+                        const result = await runJanitorSweep({
+                            payload,
+                            unitsSlug,
+                            batchesSlug: DEFAULT_BULK_TRANSLATE_BATCHES_COLLECTION_SLUG,
+                            usageSlug,
+                            minThresholdMs: 10 * 60_000,
+                            p99Multiplier: 2,
+                            maxAttempts: 3,
+                            p99CacheTtlMs: 5 * 60_000,
+                            callbacks: {
+                                onBatchComplete: bulkConfigForJanitor.onBatchComplete,
+                                onBatchFailed: bulkConfigForJanitor.onBatchFailed
+                            }
+                        });
+                        if (result.reset > 0 || result.failed > 0 || result.requeued > 0) {
+                            payload.logger?.info?.(`[ai-translate] janitor ${label} sweep: reset=${result.reset} failed=${result.failed} requeued=${result.requeued} thresholdMs=${result.thresholdMs}`);
+                        }
+                    } catch (err) {
+                        payload.logger?.warn?.(`[ai-translate] janitor ${label} sweep failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                };
+                // Boot sweep — fire-and-forget so onInit doesn't block server
+                // start while the sweep runs.
+                void sweep('boot');
+                // Periodic sweep. `unref()` lets the process exit naturally
+                // without the timer keeping it alive (matters for test
+                // teardown and serverless-style short-lived processes).
+                if (janitorIntervalMs > 0) {
+                    const timer = setInterval(()=>{
+                        void sweep('interval');
+                    }, janitorIntervalMs);
+                    if (typeof timer.unref === 'function') {
+                        timer.unref();
+                    }
+                }
+            };
+        }
+        return config;
+    };
+}
+// ---------------------------------------------------------------------------
+// Per-field button injection
+// ---------------------------------------------------------------------------
+const TRANSLATABLE_FIELD_TYPES = new Set([
+    'text',
+    'textarea',
+    'richText'
+]);
+function injectFieldButtons(fields, excludePatterns, pathPrefix = '') {
+    return fields.map((field)=>{
+        const f = field;
+        const type = f.type;
+        const localized = f.localized;
+        const name = f.name;
+        const fieldPath = name ? pathPrefix ? `${pathPrefix}.${name}` : name : pathPrefix;
+        // Inject afterInput on localized translatable fields
+        if (type && TRANSLATABLE_FIELD_TYPES.has(type) && localized && name) {
+            // Skip injection for fields that are excluded from translation. The
+            // server-side flow already filters these out, but rendering the button
+            // creates user confusion (e.g. clicking "Translate" on `slug`).
+            if (isExcluded(fieldPath, excludePatterns)) {
+                return field;
+            }
+            const admin = f.admin ?? {};
+            const components = admin.components ?? {};
+            return {
+                ...field,
+                admin: {
+                    ...admin,
+                    components: {
+                        ...components,
+                        afterInput: [
+                            ...components.afterInput ?? [],
+                            '@purposeinplay/payload-ai-translate/client#FieldTranslateButton'
+                        ]
+                    }
+                }
+            };
+        }
+        // Recurse into container fields
+        if (type === 'group' || type === 'array' || type === 'row' || type === 'collapsible') {
+            const subFields = f.fields;
+            if (subFields) {
+                // `row` and `collapsible` don't introduce a name segment in the path
+                const childPrefix = type === 'row' || type === 'collapsible' ? pathPrefix : fieldPath;
+                return {
+                    ...field,
+                    fields: injectFieldButtons(subFields, excludePatterns, childPrefix)
+                };
+            }
+        }
+        if (type === 'tabs') {
+            const tabs = f.tabs;
+            if (tabs) {
+                return {
+                    ...field,
+                    tabs: tabs.map((tab)=>{
+                        const tabFields = tab.fields;
+                        if (tabFields) {
+                            const tabName = tab.name;
+                            const childPrefix = tabName ? pathPrefix ? `${pathPrefix}.${tabName}` : tabName : pathPrefix;
+                            return {
+                                ...tab,
+                                fields: injectFieldButtons(tabFields, excludePatterns, childPrefix)
+                            };
+                        }
+                        return tab;
+                    })
+                };
+            }
+        }
+        if (type === 'blocks') {
+            const blocks = f.blocks;
+            if (blocks) {
+                return {
+                    ...field,
+                    blocks: blocks.map((block)=>{
+                        const blockFields = block.fields;
+                        if (blockFields) {
+                            return {
+                                ...block,
+                                fields: injectFieldButtons(blockFields, excludePatterns, fieldPath)
+                            };
+                        }
+                        return block;
+                    })
+                };
+            }
+        }
+        return field;
+    });
+}