@focus-reactive/payload-plugin-translator 0.11.3 → 0.11.5

package/README.md

@@ -562,6 +562,43 @@ createPayloadJobsRunner({ taskName: "translate_document", queueName: "translatio
 
 > By default Payload deletes a job as soon as it completes, so the "Completed" status never shows in the UI. Set `jobs: { deleteJobOnComplete: false }` in your Payload config to keep it.
 
+##### One job per document
+
+A document's target locales are queued as a **single job** that translates them one after another.
+Every write Payload makes is a whole-document version snapshot, so two locales translated in parallel
+build from the same base and the second silently drops the first's work.
+
+A later request for the same document adds its locales to that job rather than replacing it — the
+locales the job still owes are never lost. Two cases get a job of their own instead: re-translating a
+locale the live job has already finished (its log records it as done, so it would be skipped), and a
+request that picked a different source locale, strategy or publish flag — a job carries one of each
+for all its locales, so it cannot take work that chose differently.
+
+##### Optional: strict one-at-a-time per document
+
+Two requests landing at the same instant, or a re-translation of an already-finished locale, can still
+put two jobs on one document. If your content is edited often enough for that to matter, enable
+Payload's own concurrency control:
+
+```typescript
+// payload.config.ts
+export default buildConfig({
+  jobs: { enableConcurrencyControl: true },
+  // ...
+});
+```
+
+The plugin picks this up on its own — there is no option to set here. With it on, the queue holds a
+second job for a document until the running one finishes, so two jobs can never write the same
+document at once. Jobs for *different* documents still run in parallel.
+
+The cost is yours to weigh: the setting adds an indexed `concurrencyKey` column to the jobs
+collection, so a SQL database needs a migration (`payload migrate:create` then `payload migrate`);
+MongoDB needs none. A second job also waits for the next queue run rather than starting immediately.
+
+> With the setting on, a job stuck at `processing: true` blocks every other job for that document
+> until its lock is reclaimed. The plugin clears stale locks on boot — see `staleJobTimeoutMs`.
+
 #### `createSyncRunner()`
 
 Runs translations inline (no queue) — handy for development or small datasets.

package/dist/client/entities/translation/model/statusRows.js

@@ -65,7 +65,7 @@ const toRowState = (jobStatus)=>jobStatus === "failed" || jobStatus === "running
                 state: existing && !TRANSIENT.has(state) ? existing.state : state,
                 at: run.updated_at,
                 jobId: TRANSIENT.has(state) ? run.id : existing?.jobId,
-                error: run.status === "failed" ? run.error.message : undefined
+                error: run.status === "failed" ? run.error?.message : undefined
             });
         }
     }

package/dist/client/entities/translation/model/types.d.ts

@@ -16,7 +16,8 @@ export type DocumentTranslationFailed = {
     created_at: string;
     updated_at: string;
     input: InputData;
-    error: {
+    /** Unset until the job stops retrying, so a row can read `failed` with nothing to show. */
+    error?: {
         message: string;
     };
 };
@@ -36,9 +37,8 @@ export type DocumentTranslationCompleted = {
     input: InputData;
 };
 /**
- * One translation job for a single target locale. The document status feed is an array of these —
- * the latest job per target locale (see `useDocumentTranslation`), because re-translate queues an
- * independent job per locale.
+ * One row per target locale in the document status feed. Several rows can share one job id — a job
+ * carries all of a document's locales.
  */
 export type DocumentTranslation = DocumentTranslationCompleted | DocumentTranslationRunning | DocumentTranslationFailed | DocumentTranslationPending;
 export type CollectionTranslationStatusItem = {

package/dist/client/features/collection-translation-form/model/schema.d.ts

@@ -8,14 +8,14 @@ export declare const validationSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     collection_slug: string;
     source_lng: string;
-    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
+    target_lng: string | string[];
     publish_on_translation: boolean;
 }, {
     collection_slug: string;
     source_lng: string;
-    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
+    target_lng: string | string[];
     publish_on_translation?: boolean | undefined;
 }>;
 export type FormValues = z.infer<typeof validationSchema>;

package/dist/client/features/translate-document-form/model/schema.d.ts

@@ -10,8 +10,8 @@ export declare const validationSchema: z.ZodObject<{
     collection_slug: string;
     collection_id: string;
     source_lng: string;
-    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
+    target_lng: string | string[];
     publish_on_translation: boolean;
 }, {
     collection_slug: string;

package/dist/core/translation-pipeline/stages/field-collector/FieldChunkCollector.js

@@ -116,8 +116,11 @@ const asObject = (value)=>isObject(value) ? value : {};
             target: this.targetData,
             path: []
         }, walker);
+        // A detached copy, because write-back mutates an object-valued leaf (a rich-text tree) in
+        // place: seating the caller's own object here would translate their source document. Scalars
+        // are immutable, so they are seated as they are.
         for (const { dataRef, key, sourceValue } of selected){
-            dataRef[key] = sourceValue;
+            dataRef[key] = isObject(sourceValue) ? structuredClone(sourceValue) : sourceValue;
         }
         return chunks;
     }

package/dist/server/features/cancel-by-collection/handler.d.ts

@@ -1,9 +1,7 @@
 import type { PayloadRequest } from "payload";
 import type { TaskRunnerFactory } from "../../modules/task-runner";
 import type { CancelConfig } from "./model";
-/**
- * Cancels all pending translation tasks for a collection
- */
+/** Cancels every queued job for a collection; jobs in flight are left alone. */
 export declare class CancelByCollectionHandler {
     private readonly config;
     private readonly taskRunnerFactory;

package/dist/server/features/cancel-by-collection/handler.js

@@ -1,9 +1,7 @@
 import { ServerResponse } from "../../shared";
 import { isCollectionAvailable } from "../_lib/collection-utils";
 import { CancelByCollectionInputSchema } from "./model";
-/**
- * Cancels all pending translation tasks for a collection
- */ export class CancelByCollectionHandler {
+/** Cancels every queued job for a collection; jobs in flight are left alone. */ export class CancelByCollectionHandler {
     config;
     taskRunnerFactory;
     constructor(config, taskRunnerFactory){
@@ -16,11 +14,18 @@ import { CancelByCollectionInputSchema } from "./model";
         const collectionSlug = isCollectionAvailable(validationResult.data.collection_slug, this.config.availableCollections);
         if (!collectionSlug) return ServerResponse.badRequest("Collection not available for translation");
         const runner = this.taskRunnerFactory.create(req.payload);
-        const tasks = await runner.findByCollection(collectionSlug);
-        if (tasks.length === 0) return ServerResponse.noContent();
-        const pendingTaskIds = tasks.filter((task)=>task.status === "pending").map((task)=>task.id);
-        if (pendingTaskIds.length === 0) return ServerResponse.noContent();
-        await runner.cancel(pendingTaskIds);
+        const rows = await runner.findByCollection(collectionSlug, {
+            excludeCompleted: true
+        });
+        if (rows.length === 0) return ServerResponse.noContent();
+        // A job waiting to retry has every locale logged, so it has no `pending` row — filter by *not
+        // running* instead.
+        const running = new Set(rows.filter((row)=>row.status === "running").map((row)=>row.id));
+        const queuedJobIds = [
+            ...new Set(rows.map((row)=>row.id))
+        ].filter((id)=>!running.has(id));
+        if (queuedJobIds.length === 0) return ServerResponse.noContent();
+        await runner.cancel(queuedJobIds);
         return ServerResponse.noContent();
     }
 }

package/dist/server/features/enqueue-translation/handler.js

@@ -39,8 +39,6 @@ import { EnqueueInputSchema } from "./model";
         if (targets.length === 0) return ServerResponse.badRequest("No valid target locales to translate into (all requested locales were the source or unknown)");
         const collectionIds = select_all ? await getAllCollectionIds(req.payload, collectionSlug) : collection_id;
         const runner = this.taskRunnerFactory.create(req.payload);
-        // One task per (document x target locale). The runner keys/supersedes per (document, targetLng),
-        // so N concurrent targets of one document coexist (PR #75) — no runner change needed.
         const tasks = collectionIds.flatMap((id)=>targets.map((targetLng)=>({
                     collectionSlug,
                     collectionId: id,

package/dist/server/features/enqueue-translation/model.d.ts

@@ -15,8 +15,8 @@ export declare const EnqueueInputSchema: z.ZodObject<{
     collection_slug: string;
     collection_id: [string, ...string[]];
     source_lng: string;
-    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
+    target_lng: string | string[];
     publish_on_translation: boolean;
     select_all?: boolean | undefined;
 }, {

package/dist/server/modules/provenance/Provenance.service.d.ts

@@ -25,9 +25,12 @@ export declare class ProvenanceService {
     private readonly schemaMap;
     constructor(payload: Payload, store: ProvenanceStore, schemaMap: CollectionSchemaMap);
     /**
-     * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
-     * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
-     * it would capture the target translation and make every fresh translation look instantly stale.
+     * Hash the source the translation was made from — the baseline staleness is later measured against.
+     *
+     * Ordering used to matter: the pipeline wrote into object-valued leaves it shared with the caller's
+     * source, so hashing afterwards captured the translation and reported every fresh translation as
+     * stale. It now detaches those leaves, so this may be called on either side of the pipeline.
+     *
      * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
      */
     captureFingerprint(collection: CollectionSlug, sourceData: Record<string, unknown>): string | null;

package/dist/server/modules/provenance/Provenance.service.js

@@ -19,9 +19,12 @@ import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
         this.schemaMap = schemaMap;
     }
     /**
-   * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
-   * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
-   * it would capture the target translation and make every fresh translation look instantly stale.
+   * Hash the source the translation was made from — the baseline staleness is later measured against.
+   *
+   * Ordering used to matter: the pipeline wrote into object-valued leaves it shared with the caller's
+   * source, so hashing afterwards captured the translation and reported every fresh translation as
+   * stale. It now detaches those leaves, so this may be called on either side of the pipeline.
+   *
    * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
    */ captureFingerprint(collection, sourceData) {
         const schema = this.schemaMap.get(collection);

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsRunnerProvider.d.ts

@@ -2,33 +2,10 @@ import type { Config, Payload } from "payload";
 import type { TaskRunner } from "../TaskRunner.interface";
 import type { PayloadJobsRunnerOptions } from "./types";
 import type { TaskRunnerContext, TaskRunnerProvider } from "../TaskRunnerProvider.interface";
-/**
- * TaskRunnerProvider implementation using Payload Jobs.
- *
- * Configures Payload jobs, tasks, and autorun for translation processing.
- */
 export declare class PayloadJobsRunnerProvider implements TaskRunnerProvider {
     private readonly config;
     constructor(options?: PayloadJobsRunnerOptions);
     create(payload: Payload): TaskRunner;
     configure(context: TaskRunnerContext): (config: Config) => Config;
 }
-/**
- * Creates the **recommended** task runner: translations run as Payload Jobs
- * (queued, executed by autoRun cron or a manual run, with stale-lock recovery).
- * Durable across restarts and suited to production/serverless. Pass the result
- * as `translatorPlugin({ runner })`.
- *
- * @param options - Queue/task names, `autoRun` cron (or `false` to disable),
- *   `staleJobTimeoutMs`, and retry policy. See {@link PayloadJobsRunnerOptions}.
- * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
- * @example
- * ```ts
- * translatorPlugin({
- *   collections: [Posts],
- *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
- *   runner: createPayloadJobsRunner({ autoRun: { cron: '* * * * *' } }),
- * })
- * ```
- */
 export declare function createPayloadJobsRunner(options?: PayloadJobsRunnerOptions): TaskRunnerProvider;

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsRunnerProvider.js

@@ -4,7 +4,7 @@ const defaultAutoRun = {
     cron: "* * * * *",
     limit: 50
 };
-const DEFAULT_STALE_JOB_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_STALE_JOB_TIMEOUT_MS = 5 * 60 * 1000;
 const defaultValues = {
     taskName: "translate_document",
     queueName: "translations",
@@ -19,11 +19,7 @@ const defaultValues = {
         }
     }
 };
-/**
- * TaskRunnerProvider implementation using Payload Jobs.
- *
- * Configures Payload jobs, tasks, and autorun for translation processing.
- */ export class PayloadJobsRunnerProvider {
+export class PayloadJobsRunnerProvider {
     config;
     constructor(options){
         const autoRun = options?.autoRun === false ? false : options?.autoRun ? {
@@ -36,6 +32,7 @@ const defaultValues = {
         }
         this.config = {
             taskName: options?.taskName ?? defaultValues.taskName,
+            workflowName: `${options?.taskName ?? defaultValues.taskName}_locales`,
             queueName: options?.queueName ?? defaultValues.queueName,
             jobsCollection: options?.jobsCollection ?? defaultValues.jobsCollection,
             autoRun,
@@ -47,13 +44,10 @@ const defaultValues = {
         return new PayloadJobsTaskRunner(payload, this.config);
     }
     configure(context) {
-        const { taskName, queueName, retries, autoRun } = this.config;
+        const { taskName, workflowName, queueName, retries, autoRun } = this.config;
         const { handler, collections } = context;
         return (config)=>{
             const inputSchema = [
-                // Flat text reference (ID-agnostic). Current shape that jobs are
-                // written with — no relationship type validation against the target
-                // collection's ID type, so string IDs work for number-id collections.
                 {
                     type: "text",
                     name: "collection_slug",
@@ -64,14 +58,7 @@ const defaultValues = {
                     name: "collection_id",
                     required: true
                 },
-                /**
-         * Legacy relationship reference, kept as a read-only fallback so jobs
-         * queued before the ID-agnostic migration stay readable. No longer
-         * written; demoted to `required: false` so new jobs (which omit it)
-         * pass validation. Removed in the next major.
-         * See docs/DEPRECATIONS.md#jobs-input-collection-field
-         * @deprecated
-         */ {
+                {
                     type: "relationship",
                     name: "collection",
                     relationTo: collections,
@@ -105,6 +92,14 @@ const defaultValues = {
                     defaultValue: false
                 }
             ];
+            const workflowInputSchema = [
+                ...inputSchema.filter((f)=>"name" in f && f.name !== "target_lng"),
+                {
+                    type: "json",
+                    name: "target_lngs",
+                    required: true
+                }
+            ];
             const task = {
                 slug: taskName,
                 inputSchema,
@@ -124,10 +119,36 @@ const defaultValues = {
                     };
                 }
             };
+            const workflow = {
+                slug: workflowName,
+                inputSchema: workflowInputSchema,
+                retries,
+                ...config.jobs?.enableConcurrencyControl ? {
+                    concurrency: {
+                        key: ({ input })=>`${input.collection_slug}:${input.collection_id}`,
+                        exclusive: true
+                    }
+                } : {},
+                handler: async ({ job, tasks })=>{
+                    const runLocale = tasks[taskName];
+                    for(let i = 0;; i++){
+                        const { target_lngs: targets, ...shared } = job.input;
+                        const target = targets?.[i];
+                        if (target === undefined) return;
+                        await runLocale(target, {
+                            input: {
+                                ...shared,
+                                target_lng: target
+                            }
+                        });
+                    }
+                }
+            };
             if (!config.jobs) config.jobs = {};
             if (!config.jobs.tasks) config.jobs.tasks = [];
             config.jobs.tasks.push(task);
-            // Skip autoRun configuration when disabled (e.g., for Vercel/serverless deployments)
+            if (!config.jobs.workflows) config.jobs.workflows = [];
+            config.jobs.workflows.push(workflow);
             if (autoRun) {
                 const autoRunConfig = {
                     queue: queueName,
@@ -148,13 +169,6 @@ const defaultValues = {
                     ];
                 }
             }
-            // Reset stale locks on boot so jobs abandoned by a killed process
-            // (deploy/crash/timeout) become eligible for the autorun picker again.
-            // The picker requires processing:false, no error, and no pending waitUntil;
-            // a mid-run casualty (no error, no waitUntil) satisfies the rest, so
-            // clearing processing is sufficient for that case. Threshold-based, so a
-            // job genuinely in flight on another live instance (fresh updatedAt) is
-            // left alone. Wrapped so a reclaim failure never blocks startup.
             const existingOnInit = config.onInit;
             config.onInit = async (payload)=>{
                 if (existingOnInit) await existingOnInit(payload);
@@ -171,24 +185,7 @@ const defaultValues = {
         };
     }
 }
-/**
- * Creates the **recommended** task runner: translations run as Payload Jobs
- * (queued, executed by autoRun cron or a manual run, with stale-lock recovery).
- * Durable across restarts and suited to production/serverless. Pass the result
- * as `translatorPlugin({ runner })`.
- *
- * @param options - Queue/task names, `autoRun` cron (or `false` to disable),
- *   `staleJobTimeoutMs`, and retry policy. See {@link PayloadJobsRunnerOptions}.
- * @returns A {@link TaskRunnerProvider} for the plugin's `runner` option.
- * @example
- * ```ts
- * translatorPlugin({
- *   collections: [Posts],
- *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
- *   runner: createPayloadJobsRunner({ autoRun: { cron: '* * * * *' } }),
- * })
- * ```
- */ export function createPayloadJobsRunner(options) {
+export function createPayloadJobsRunner(options) {
     return new PayloadJobsRunnerProvider(options);
 }
 

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.d.ts

@@ -2,39 +2,35 @@ import type { Payload, CollectionSlug } from "payload";
 import type { TaskFilter, TaskRunner } from "../TaskRunner.interface";
 import type { Task, TaskInput, RunResult } from "../types";
 import type { PayloadJobsRunnerConfig } from "./types";
-/**
- * TaskRunner implementation using Payload Jobs.
- *
- * Handles queuing, cancellation, status tracking, and execution of translation tasks.
- */
 export declare class PayloadJobsTaskRunner implements TaskRunner {
     private readonly payload;
     private readonly config;
     constructor(payload: Payload, config: PayloadJobsRunnerConfig);
     enqueue(tasks: TaskInput[]): Promise<void>;
+    private serve;
+    private extendJob;
+    private queueWorkflow;
     cancel(taskIds: string[]): Promise<void>;
     run(taskId: string): Promise<RunResult>;
     /**
-     * Clear stale `processing` locks — still processing, not completed, `updatedAt` older than
-     * `staleJobTimeoutMs` — so abandoned jobs are eligible for the autorun picker again. A job that
-     * exhausted its retries carries `hasError: true` and stays excluded from autorun even after its
-     * lock is cleared; only a manual `run()` recovers it.
+     * A job that exhausted its retries carries `hasError: true` and stays excluded from the picker even
+     * after its lock is cleared; only a manual `run()` recovers it.
      * @returns how many locks were cleared.
      */
     reclaimStaleJobs(): Promise<number>;
-    /** Clears the `processing` lock on every job matching `where`. `depth: 0` — only the count is read. */
-    private resetProcessing;
+    /**
+     * `payload.update`, not the adapter write `extendJob` uses, so the jobs collection's `beforeChange`
+     * hook still runs — it is what keeps a cancelled job cancelled.
+     */
+    private clearPickerBlockers;
     private isStale;
     /**
-     * Find translation jobs for a collection.
-     *
-     * Only `taskSlug` and `completedAt` reach the database; slug and document ids are matched in memory
-     * because a job's collection reference may sit in either the flat-text fields or the legacy
-     * relationship shape (`readCollectionRef`), so a `where` on `input.collection_slug` would silently
-     * drop every pre-migration job. `excludeCompleted` is what bounds the read — see issue #108.
+     * Matched in memory, not in a `where`: a job's collection reference sits either in the flat text
+     * fields or in the legacy relationship shape (see `readCollectionRef`), so `input.collection_slug`
+     * as a filter would silently drop every pre-migration job.
      */
     findByCollection(collectionSlug: CollectionSlug, filter?: Array<string | number> | TaskFilter): Promise<Task[]>;
-    private groupByCollection;
-    private cancelAndDeleteJobs;
-    private findJobsInternal;
+    private ownJobs;
+    private findJobById;
+    private findRawJobs;
 }

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.js

@@ -1,14 +1,30 @@
 import { toTaskFilter } from "../toTaskFilter";
-import { normalizeJob } from "./normalizeJob";
-// A translation job's supersession identity: same document AND same target locale. IDs are
-// String()-normalized to match the stored (string) form, so a number id compares equal to its
-// persisted job.
-const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${targetLng}`;
+import { normalizeJobLocales } from "./normalizeJob";
+import { planEnqueue } from "./planEnqueue";
+import { readCollectionRef } from "./readCollectionRef";
+const APPEND_ATTEMPTS = 2;
 /**
- * TaskRunner implementation using Payload Jobs.
- *
- * Handles queuing, cancellation, status tracking, and execution of translation tasks.
- */ export class PayloadJobsTaskRunner {
+ * Groups served at once: a `select_all` enqueue can span thousands, each costing two writes and a
+ * read, and the ceiling is the database pool rather than the CPU.
+ */ const ENQUEUE_CONCURRENCY = 10;
+function requestShape(task) {
+    return {
+        collectionSlug: task.collectionSlug,
+        collectionId: String(task.collectionId),
+        sourceLng: task.sourceLng,
+        strategy: task.strategy,
+        publishOnTranslation: task.publishOnTranslation
+    };
+}
+/** `pickHost` matches on the same shape, so no two groups can pick the same host job — which is what
+ * makes the parallel `serve` calls safe. */ function requestKey(task) {
+    return JSON.stringify(requestShape(task));
+}
+function documentKey(collectionSlug, collectionId) {
+    // NUL: no slug or id can contain it, so two different documents cannot produce one key.
+    return `${collectionSlug}\u0000${collectionId}`;
+}
+export class PayloadJobsTaskRunner {
     payload;
     config;
     constructor(payload, config){
@@ -16,91 +32,161 @@ const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${
         this.config = config;
     }
     async enqueue(tasks) {
-        const byCollection = this.groupByCollection(tasks);
-        for (const [collectionSlug, items] of byCollection){
-            const documentIds = items.map((t)=>t.collectionId);
-            // Finished jobs must stay out of this set: superseding deletes (`cancelAndDeleteJobs` reaches
-            // `payload.delete`), so a completed job for the same (document, locale) would be erased along
-            // with the pending one.
-            const existing = await this.findByCollection(collectionSlug, {
-                documentIds,
-                excludeCompleted: true
-            });
-            // Supersede only jobs for the SAME (document, target locale) being re-enqueued — never a
-            // concurrent job for a *different* locale of the same document. Cancelling per-document would
-            // kill an in-flight translation of another locale (the concurrent re-translate bug).
-            const supersededKeys = new Set(items.map((t)=>documentLocaleKey(t.collectionId, t.targetLng)));
-            const toCancel = existing.filter((t)=>supersededKeys.has(documentLocaleKey(t.input.collectionId, t.input.targetLng)));
-            if (toCancel.length > 0) {
-                await this.cancelAndDeleteJobs(toCancel.map((t)=>t.id));
+        const byRequest = new Map();
+        for (const task of tasks){
+            const key = requestKey(task);
+            const group = byRequest.get(key) ?? [];
+            group.push(task);
+            byRequest.set(key, group);
+        }
+        const live = await this.findRawJobs({
+            completedAt: {
+                exists: false
             }
+        });
+        const liveByDocument = new Map();
+        for (const job of live){
+            const { collectionSlug, collectionId } = readCollectionRef(job.input);
+            const key = documentKey(collectionSlug, collectionId);
+            liveByDocument.set(key, [
+                ...liveByDocument.get(key) ?? [],
+                job
+            ]);
         }
-        await Promise.all(tasks.map((task)=>this.payload.jobs.queue({
-                task: this.config.taskName,
-                queue: this.config.queueName,
-                // Debounce: when set, Payload holds the job until this instant. A superseding enqueue for
-                // the same (document, targetLng) cancels the pending delayed job first (see enqueue above),
-                // so rapid source edits coalesce to the final one. Undefined for the manual path.
-                waitUntil: task.waitUntil,
-                input: {
-                    // Flat text reference (ID-agnostic). Stored as a string — no
-                    // relationship type validation against the collection's ID type,
-                    // which is what previously left number-id jobs stuck in processing.
-                    // This is the single write boundary, so `String(...)` here is the
-                    // one place IDs are normalized for storage.
-                    collection_slug: task.collectionSlug,
-                    collection_id: String(task.collectionId),
-                    source_lng: task.sourceLng,
-                    target_lng: task.targetLng,
-                    strategy: task.strategy,
-                    publish_on_translation: task.publishOnTranslation
-                }
-            })));
+        const exclusiveQueue = Boolean(this.payload.config.jobs?.enableConcurrencyControl);
+        const groups = [
+            ...byRequest.values()
+        ];
+        for(let i = 0; i < groups.length; i += ENQUEUE_CONCURRENCY){
+            await Promise.all(groups.slice(i, i + ENQUEUE_CONCURRENCY).map((group)=>this.serve(group, liveByDocument, exclusiveQueue)));
+        }
+    }
+    async serve(group, liveByDocument, exclusiveQueue) {
+        const [first] = group;
+        const request = requestShape(first);
+        const plan = planEnqueue({
+            live: liveByDocument.get(documentKey(request.collectionSlug, request.collectionId)) ?? [],
+            request,
+            requested: group.map((t)=>t.targetLng),
+            exclusiveQueue
+        });
+        const undelivered = plan.host ? await this.extendJob(plan.host, plan.append, first.waitUntil) : [];
+        const queue = [
+            ...plan.queue,
+            ...undelivered
+        ];
+        if (queue.length > 0) await this.queueWorkflow(request, queue, first.waitUntil);
+    }
+    async extendJob(job, locales, waitUntil) {
+        let current = job;
+        let undelivered = locales;
+        // `input` is one JSON column, so a concurrent append replaces the whole list; the union makes a
+        // retry from the stored row harmless.
+        for(let attempt = 0; attempt < APPEND_ATTEMPTS; attempt++){
+            const listed = current.input?.target_lngs ?? [];
+            const missing = locales.filter((locale)=>!listed.includes(locale));
+            const debounce = waitUntil && !current.processing ? waitUntil.toISOString() : undefined;
+            if (missing.length === 0 && !debounce) return [];
+            // Not `payload.update`: it rewrites the whole row and reverts log entries written in between.
+            // See D2 of docs/plans/2026-09-08-one-live-job-per-document.task.md.
+            await this.payload.db.updateOne({
+                collection: this.config.jobsCollection,
+                id: job.id,
+                data: {
+                    input: {
+                        ...current.input,
+                        target_lngs: [
+                            ...listed,
+                            ...missing
+                        ]
+                    },
+                    ...debounce ? {
+                        waitUntil: debounce
+                    } : {}
+                },
+                returning: false
+            });
+            const reread = await this.findJobById(job.id);
+            if (!reread || reread.completedAt) return locales;
+            current = reread;
+            const stored = new Set(current.input?.target_lngs);
+            undelivered = locales.filter((locale)=>!stored.has(locale));
+            if (undelivered.length === 0) return [];
+        }
+        return undelivered;
+    }
+    async queueWorkflow(request, targetLngs, waitUntil) {
+        const input = {
+            collection_slug: request.collectionSlug,
+            collection_id: request.collectionId,
+            source_lng: request.sourceLng,
+            target_lngs: targetLngs,
+            strategy: request.strategy,
+            publish_on_translation: request.publishOnTranslation
+        };
+        // Cast: `jobs.queue` is typed over the host's generated slugs, which cannot include a workflow
+        // registered at config time.
+        const queueJob = this.payload.jobs.queue;
+        await queueJob({
+            workflow: this.config.workflowName,
+            queue: this.config.queueName,
+            waitUntil,
+            input
+        });
     }
     async cancel(taskIds) {
         if (taskIds.length === 0) return;
-        await this.cancelAndDeleteJobs(taskIds);
-    }
-    async run(taskId) {
-        const tasks = await this.findJobsInternal({
-            id: {
-                equals: taskId
+        // Mark then delete: the delete alone would take the row out of the status feed under
+        // `deleteJobOnComplete: false` without recording why it went. The mark does not reach a running
+        // handler — see D1 of docs/plans/2026-09-08-one-live-job-per-document.task.md.
+        await this.payload.jobs.cancel({
+            where: {
+                id: {
+                    in: taskIds
+                }
+            },
+            queue: this.config.queueName
+        });
+        await this.payload.delete({
+            collection: this.config.jobsCollection,
+            where: {
+                and: [
+                    this.ownJobs(),
+                    {
+                        id: {
+                            in: taskIds
+                        }
+                    }
+                ]
             }
-        }, {
-            limit: 1
         });
-        const task = tasks[0];
-        if (!task) {
+    }
+    async run(taskId) {
+        const job = await this.findJobById(taskId);
+        if (!job) {
             return {
                 success: false,
                 error: "not_found"
             };
         }
-        if (task.completedAt) {
+        if (job.completedAt) {
             return {
                 success: false,
                 error: "already_completed"
             };
         }
-        if (task.status === "running") {
-            // The picker below selects only `processing: false`, so a stale lock must be cleared first.
-            if (!this.isStale(task.updatedAt)) {
-                return {
-                    success: false,
-                    error: "already_running"
-                };
-            }
-            await this.resetProcessing({
-                id: {
-                    equals: taskId
-                }
-            });
+        if (job.processing && !this.isStale(job.updatedAt)) {
+            return {
+                success: false,
+                error: "already_running"
+            };
         }
-        // `where` picker, not `payload.jobs.runByID({ id })`: in `runJobs` the guard block
-        // (processing:false, hasError not true, waitUntil due) is built only for the non-id branch, so
-        // the id path would re-run a job that already exhausted its retries. Checked against payload
-        // 3.84.1.
-        await this.payload.jobs.run({
+        if (job.processing || job.error) {
+            await this.clearPickerBlockers(taskId);
+        }
+        // Not `jobs.runByID`: payload 3.84.1 builds the picker guard (processing / hasError / waitUntil)
+        // only on the `where` path, so the id path re-runs a job that exhausted its retries.
+        const result = await this.payload.jobs.run({
             queue: this.config.queueName,
             where: {
                 id: {
@@ -109,68 +195,81 @@ const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${
             },
             limit: 1
         });
+        const pickerTookNothing = Object.keys(result?.jobStatus ?? {}).length === 0;
+        if (pickerTookNothing) {
+            return {
+                success: false,
+                error: "already_running"
+            };
+        }
         return {
             success: true
         };
     }
     /**
-   * Clear stale `processing` locks — still processing, not completed, `updatedAt` older than
-   * `staleJobTimeoutMs` — so abandoned jobs are eligible for the autorun picker again. A job that
-   * exhausted its retries carries `hasError: true` and stays excluded from autorun even after its
-   * lock is cleared; only a manual `run()` recovers it.
+   * A job that exhausted its retries carries `hasError: true` and stays excluded from the picker even
+   * after its lock is cleared; only a manual `run()` recovers it.
    * @returns how many locks were cleared.
    */ async reclaimStaleJobs() {
         const cutoff = new Date(Date.now() - this.config.staleJobTimeoutMs).toISOString();
-        return this.resetProcessing({
-            and: [
-                {
-                    taskSlug: {
-                        equals: this.config.taskName
-                    }
-                },
-                {
-                    processing: {
-                        equals: true
-                    }
-                },
-                {
-                    completedAt: {
-                        exists: false
-                    }
-                },
-                {
-                    updatedAt: {
-                        less_than: cutoff
-                    }
-                }
-            ]
-        });
-    }
-    /** Clears the `processing` lock on every job matching `where`. `depth: 0` — only the count is read. */ async resetProcessing(where) {
         const result = await this.payload.update({
             collection: this.config.jobsCollection,
             depth: 0,
-            where,
+            where: {
+                and: [
+                    this.ownJobs(),
+                    {
+                        processing: {
+                            equals: true
+                        }
+                    },
+                    {
+                        completedAt: {
+                            exists: false
+                        }
+                    },
+                    {
+                        updatedAt: {
+                            less_than: cutoff
+                        }
+                    }
+                ]
+            },
             data: {
                 processing: false
             }
         });
         return result.docs.length;
     }
+    /**
+   * `payload.update`, not the adapter write `extendJob` uses, so the jobs collection's `beforeChange`
+   * hook still runs — it is what keeps a cancelled job cancelled.
+   */ async clearPickerBlockers(taskId) {
+        await this.payload.update({
+            collection: this.config.jobsCollection,
+            depth: 0,
+            where: {
+                id: {
+                    equals: taskId
+                }
+            },
+            data: {
+                processing: false,
+                hasError: false,
+                error: null,
+                waitUntil: null
+            }
+        });
+    }
     isStale(updatedAt) {
         const parsed = Date.parse(updatedAt);
-        // Unknown/corrupt timestamp → treat as stale so the job can be recovered
-        // rather than permanently refused as already-running.
         if (Number.isNaN(parsed)) return true;
         return Date.now() - parsed > this.config.staleJobTimeoutMs;
     }
     /**
-   * Find translation jobs for a collection.
-   *
-   * Only `taskSlug` and `completedAt` reach the database; slug and document ids are matched in memory
-   * because a job's collection reference may sit in either the flat-text fields or the legacy
-   * relationship shape (`readCollectionRef`), so a `where` on `input.collection_slug` would silently
-   * drop every pre-migration job. `excludeCompleted` is what bounds the read — see issue #108.
+   * Matched in memory, not in a `where`: a job's collection reference sits either in the flat text
+   * fields or in the legacy relationship shape (see `readCollectionRef`), so `input.collection_slug`
+   * as a filter would silently drop every pre-migration job.
    */ async findByCollection(collectionSlug, filter) {
         const { documentIds, excludeCompleted } = toTaskFilter(filter);
         const where = excludeCompleted ? {
@@ -178,64 +277,54 @@ const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${
                 exists: false
             }
         } : undefined;
-        const all = await this.findJobsInternal(where, {
-            pagination: false
-        });
-        const bySlug = all.filter((t)=>t.input.collectionSlug === collectionSlug);
-        if (!documentIds?.length) return bySlug;
-        const wanted = new Set(documentIds.map(String));
-        return bySlug.filter((t)=>wanted.has(t.input.collectionId));
-    }
-    groupByCollection(tasks) {
-        const map = new Map();
-        for (const task of tasks){
-            const existing = map.get(task.collectionSlug) ?? [];
-            existing.push(task);
-            map.set(task.collectionSlug, existing);
-        }
-        return map;
+        const wanted = documentIds?.length ? new Set(documentIds.map(String)) : undefined;
+        const jobs = await this.findRawJobs(where);
+        return jobs.filter((job)=>{
+            const ref = readCollectionRef(job.input);
+            return ref.collectionSlug === collectionSlug && (!wanted || wanted.has(ref.collectionId));
+        }).flatMap(normalizeJobLocales);
     }
-    async cancelAndDeleteJobs(taskIds) {
-        if (taskIds.length === 0) return;
-        // Both, in this order: `jobs.cancel` only writes `{ error: { cancelled: true }, hasError: true,
-        // processing: false }`, which is what signals a running handler to abort. The delete then removes
-        // the row — under `deleteJobOnComplete: false` a cancelled job would otherwise sit in the status
-        // feed forever.
-        await this.payload.jobs.cancel({
-            where: {
-                id: {
-                    in: taskIds
-                }
-            },
-            queue: this.config.queueName
-        });
-        await this.payload.delete({
-            collection: this.config.jobsCollection,
-            where: {
-                id: {
-                    in: taskIds
+    ownJobs() {
+        // Pre-workflow jobs are still in the table: docs/DEPRECATIONS.md#jobs-per-locale-task-shape
+        return {
+            or: [
+                {
+                    workflowSlug: {
+                        equals: this.config.workflowName
+                    }
+                },
+                {
+                    taskSlug: {
+                        equals: this.config.taskName
+                    }
                 }
+            ]
+        };
+    }
+    async findJobById(id) {
+        const [job] = await this.findRawJobs({
+            id: {
+                equals: id
             }
         });
+        return job;
     }
-    async findJobsInternal(where, params) {
+    async findRawJobs(where) {
         const and = [
-            {
-                taskSlug: {
-                    equals: this.config.taskName
-                }
-            }
+            this.ownJobs()
         ];
         if (where) and.push(where);
         const response = await this.payload.find({
             collection: this.config.jobsCollection,
-            limit: params?.limit,
-            pagination: params?.pagination,
+            // The legacy `input.collection` is a declared relationship; at the default depth Payload
+            // populates it, and `readCollectionRef` would then read a document where it wants an id.
+            depth: 0,
+            pagination: false,
             where: {
                 and
             }
         });
-        return response.docs.map(normalizeJob);
+        return response.docs;
     }
 }
 

package/dist/server/modules/task-runner/payload-jobs-runner/normalizeJob.d.ts

@@ -1,6 +1,14 @@
 import type { Task } from "../types";
-import type { PayloadJob } from "./types";
+import type { JobLogEntry, PayloadJob } from "./types";
+export declare function isCancelled(error: unknown): boolean;
+export declare function normalizeJob(job: PayloadJob): Task;
 /**
- * Transform Payload job to normalized Task
+ * One {@link Task} per target locale, its state read from {@link latestLogByLocale}. A pre-workflow
+ * job carries a single `target_lng` and expands to itself.
  */
-export declare function normalizeJob(job: PayloadJob): Task;
+export declare function normalizeJobLocales(job: PayloadJob): Task[];
+/**
+ * Each locale's most recent log entry: Payload appends to `log` chronologically, so last-write-wins
+ * leaves the latest attempt.
+ */
+export declare function latestLogByLocale(job: PayloadJob): Map<string, JobLogEntry>;

package/dist/server/modules/task-runner/payload-jobs-runner/normalizeJob.js

@@ -1,7 +1,20 @@
 import { readCollectionRef } from "./readCollectionRef";
-/**
- * Transform Payload job to normalized Task
- */ export function normalizeJob(job) {
+function getJobStatus(job) {
+    if (job.completedAt) return "completed";
+    if (job.processing) return "running";
+    if (job.error) return "failed";
+    return "pending";
+}
+function extractErrorMessage(error) {
+    if (error && typeof error === "object" && "message" in error && typeof error.message === "string") {
+        return error.message;
+    }
+    return "Unknown error";
+}
+export function isCancelled(error) {
+    return error !== null && typeof error === "object" && "cancelled" in error && typeof error.cancelled === "boolean" && error.cancelled;
+}
+export function normalizeJob(job) {
     const { collectionSlug, collectionId } = readCollectionRef(job.input);
     return {
         id: job.id,
@@ -23,20 +36,49 @@ import { readCollectionRef } from "./readCollectionRef";
         cancelled: isCancelled(job.error)
     };
 }
-function getJobStatus(job) {
-    if (job.completedAt) return "completed";
-    if (job.processing) return "running";
-    if (job.error) return "failed";
-    return "pending";
+/**
+ * One {@link Task} per target locale, its state read from {@link latestLogByLocale}. A pre-workflow
+ * job carries a single `target_lng` and expands to itself.
+ */ export function normalizeJobLocales(job) {
+    const targets = job.input?.target_lngs;
+    if (!Array.isArray(targets) || targets.length === 0) return [
+        normalizeJob(job)
+    ];
+    const base = normalizeJob(job);
+    const latestByLocale = latestLogByLocale(job);
+    return targets.map((targetLng)=>{
+        const entry = latestByLocale.get(targetLng);
+        if (!entry) return {
+            ...base,
+            input: {
+                ...base.input,
+                targetLng
+            }
+        };
+        const succeeded = entry.state === "succeeded";
+        return {
+            ...base,
+            status: succeeded ? "completed" : "failed",
+            completedAt: succeeded ? entry.completedAt ?? undefined : undefined,
+            error: succeeded ? undefined : base.error,
+            cancelled: succeeded ? false : base.cancelled,
+            input: {
+                ...base.input,
+                targetLng
+            }
+        };
+    });
 }
-function extractErrorMessage(error) {
-    if (error && typeof error === "object" && "message" in error && typeof error.message === "string") {
-        return error.message;
+/**
+ * Each locale's most recent log entry: Payload appends to `log` chronologically, so last-write-wins
+ * leaves the latest attempt.
+ */ export function latestLogByLocale(job) {
+    const byLocale = new Map();
+    for (const entry of job.log ?? []){
+        const lng = entry?.input?.target_lng;
+        if (typeof lng === "string") byLocale.set(lng, entry);
     }
-    return "Unknown error";
-}
-function isCancelled(error) {
-    return error !== null && typeof error === "object" && "cancelled" in error && typeof error.cancelled === "boolean" && error.cancelled;
+    return byLocale;
 }
 
 //# sourceMappingURL=normalizeJob.js.map

package/dist/server/modules/task-runner/payload-jobs-runner/planEnqueue.d.ts

@@ -0,0 +1,33 @@
+import type { CollectionSlug } from "payload";
+import type { PayloadJob } from "./types";
+/** The part of a request that every locale in it shares. */
+export type RequestShape = {
+    collectionSlug: CollectionSlug;
+    collectionId: string;
+    sourceLng: string;
+    strategy: string;
+    publishOnTranslation: boolean;
+};
+/**
+ * `append` and `queue` are independent: a request can both extend a live job and need a job of its
+ * own, when a locale it asks for has already been translated by that job.
+ */
+export type EnqueuePlan = {
+    host: PayloadJob | null;
+    append: string[];
+    queue: string[];
+};
+/**
+ * One live job per document: a later request extends that job's locale list rather than replacing it.
+ *
+ * @param live - non-completed jobs for **this document only**; the caller filters by document.
+ * @param requested - target locales in request order; duplicates ignored.
+ * @param exclusiveQueue - the host's `enableConcurrencyControl`; with it on a running job is queued
+ *   behind rather than extended.
+ */
+export declare function planEnqueue(args: {
+    live: PayloadJob[];
+    request: RequestShape;
+    requested: string[];
+    exclusiveQueue: boolean;
+}): EnqueuePlan;

package/dist/server/modules/task-runner/payload-jobs-runner/planEnqueue.js

@@ -0,0 +1,51 @@
+import { isCancelled, latestLogByLocale } from "./normalizeJob";
+/**
+ * One live job per document: a later request extends that job's locale list rather than replacing it.
+ *
+ * @param live - non-completed jobs for **this document only**; the caller filters by document.
+ * @param requested - target locales in request order; duplicates ignored.
+ * @param exclusiveQueue - the host's `enableConcurrencyControl`; with it on a running job is queued
+ *   behind rather than extended.
+ */ export function planEnqueue(args) {
+    const requested = [
+        ...new Set(args.requested)
+    ];
+    const host = pickHost(args.live, args.request);
+    if (!host) return {
+        host: null,
+        append: [],
+        queue: requested
+    };
+    // Already-succeeded locales need a fresh job: the workflow passes the locale as the task id, so
+    // Payload's restoration would skip them (see the workflow handler in PayloadJobsRunnerProvider).
+    const settled = latestLogByLocale(host);
+    const done = requested.filter((locale)=>settled.get(locale)?.state === "succeeded");
+    const listed = new Set(host.input?.target_lngs);
+    const missing = requested.filter((locale)=>!listed.has(locale));
+    if (args.exclusiveQueue && host.processing) {
+        return {
+            host: null,
+            append: [],
+            queue: [
+                ...missing,
+                ...done
+            ]
+        };
+    }
+    return {
+        host,
+        append: missing,
+        queue: done
+    };
+}
+/**
+ * A job carries one source locale, one strategy and one publish flag for all of its locales, so it can
+ * host only a request that chose the same three — otherwise the request runs under settings the user
+ * did not pick.
+ */ function pickHost(live, request) {
+    const usable = live.filter((job)=>Array.isArray(job.input?.target_lngs) && !isCancelled(job.error) && job.input?.source_lng === request.sourceLng && job.input?.strategy === request.strategy && (job.input?.publish_on_translation ?? false) === request.publishOnTranslation);
+    const newestFirst = usable.sort((a, b)=>Date.parse(b.createdAt) - Date.parse(a.createdAt));
+    return newestFirst[0] ?? null;
+}
+
+//# sourceMappingURL=planEnqueue.js.map

package/dist/server/modules/task-runner/payload-jobs-runner/types.d.ts

@@ -72,16 +72,16 @@ export type PayloadJobsRunnerOptions = {
  */
 export type PayloadJobsRunnerConfig = {
     taskName: string;
+    /** Derived from `taskName`; deliberately not a plugin option. */
+    workflowName: string;
     queueName: string;
     jobsCollection: CollectionSlug;
     autoRun: false | Required<AutoRunConfig>;
     staleJobTimeoutMs: number;
     retries?: PayloadJobsRunnerOptions["retries"];
 };
-/**
- * Raw Payload job structure
- */
 export type PayloadJob = {
+    log?: JobLogEntry[];
     id: string;
     completedAt?: string | null;
     createdAt: string;
@@ -103,7 +103,25 @@ export type PayloadJob = {
         };
         source_lng?: string;
         target_lng?: string;
+        target_lngs?: string[];
         strategy?: string;
         publish_on_translation?: boolean;
     };
 };
+/** Snake_case because Payload persists these keys verbatim in the job row. */
+export type StoredWorkflowInput = {
+    collection_slug: CollectionSlug;
+    collection_id: string;
+    source_lng: string;
+    target_lngs: string[];
+    strategy: string;
+    publish_on_translation: boolean;
+};
+/** Written by Payload only once a task settles — an absent entry means that locale has not run. */
+export type JobLogEntry = {
+    state: "succeeded" | "failed";
+    completedAt?: string | null;
+    input?: {
+        target_lng?: string;
+    };
+};

package/dist/server/modules/task-runner/payload-jobs-runner/types.js

@@ -1,5 +1,3 @@
-/**
- * Raw Payload job structure
- */ export { };
+/** Written by Payload only once a task settles — an absent entry means that locale has not run. */ export { };
 
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",