@focus-reactive/payload-plugin-translator 0.8.2 → 0.9.0

package/README.md

@@ -196,6 +196,43 @@ Dismiss acknowledges the drift without re-translating; the marker stays hidden u
 changes again. When `provenance` is disabled nothing is shown. Note the fingerprint is text-only, so
 formatting-only edits to rich text do not mark a locale stale.
 
+### Auto-translate on source change
+
+_Since v0.9.0._
+
+Opt in per collection with `withAutoTranslate` and the plugin queues translations automatically when a
+document's source-locale content changes — no manual trigger. Off by default; a collection is enabled
+only by wrapping it.
+
+```ts
+import { translatorPlugin, withAutoTranslate, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
+
+translatorPlugin({
+  collections: [withAutoTranslate(Posts, { targets: ["de", "fr"], debounceMs: 2000 })],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+});
+```
+
+| Option | Type | Default | Meaning |
+| ------ | ---- | ------- | ------- |
+| `targets` | `string[]` | — | Locales to translate into. The source locale is always excluded. |
+| `strategy` | `"overwrite" \| "skip_existing"` | `"overwrite"` | How target content is written. |
+| `debounceMs` | `number` | `0` | Delay before the job runs, coalescing rapid edits (see below). |
+| `sourceLocale` | `string` | `localization.defaultLocale` | Override the source locale for this collection. |
+
+Behaviour: fires only on a **published** source save (draft/autosave saves are ignored; a collection
+without drafts treats every save as published); skips when no translatable content actually changed
+(same fingerprint as stale-detection); coalesces rapid edits via `debounceMs`; the translation is saved
+with the source document's status (published source → published translation); never re-triggers on its
+own translation writes; and never fails the editor's save (best-effort — failures are logged).
+
+> **Requires a working job runner.** Auto-translate only **enqueues** jobs — they run via the task
+> runner (`createPayloadJobsRunner`) and its autorun loop. On serverless platforms such as **Vercel**,
+> cron-based autorun may not run automatically, so enqueued translations can sit unexecuted until
+> triggered — e.g. an external cron hitting the run endpoint, or a self-hosted worker. Make sure your
+> deployment actually executes queued jobs before relying on auto-translate.
+
 ### Lifecycle callbacks
 
 _Since v0.7.0._

package/dist/auto-translate-config.d.ts

@@ -0,0 +1,40 @@
+import type { CollectionConfig } from "payload";
+import type { AutoTranslateConfig } from "./core/auto-translate-config";
+export type { AutoTranslateConfig };
+export type { AutoTranslateStrategy } from "./core/auto-translate-config";
+/**
+ * Enable opt-in **auto-translate** for a collection: when a document's source-locale content changes
+ * (and is published), the plugin automatically queues translations into the configured target locales.
+ * Off by default — a collection is opted in only by wrapping it with this helper. The rule is stamped
+ * onto `collection.custom` (the input is not mutated; a new collection is returned), mirroring
+ * `withFieldTranslation` at the field level.
+ *
+ * Behaviour: fires only on a **published** source save (draft/autosave saves are ignored; a collection
+ * without drafts treats every save as published); skips when no translatable content actually changed
+ * (drift-gate); coalesces rapid edits via `debounceMs`; never re-triggers on its own translation
+ * writes; and never fails the editor's save (best-effort).
+ *
+ * **Requires a working job runner.** Auto-translate only ENQUEUES jobs — they run via the plugin's
+ * task runner (`createPayloadJobsRunner`) and its autorun loop. On serverless platforms such as
+ * **Vercel**, cron-based autorun may not run automatically, so enqueued translations can sit
+ * unexecuted until triggered — e.g. an external cron hitting the run-translation endpoint, or a
+ * self-hosted worker. Ensure your deployment actually executes queued jobs before relying on this.
+ *
+ * @param collection - The collection to opt in.
+ * @param config - Target locales (+ optional strategy, debounce, source-locale override).
+ * @returns A new collection with the auto-translate rule applied (the input is not mutated).
+ *
+ * @example
+ * ```ts
+ * import { withAutoTranslate } from '@focus-reactive/payload-plugin-translator'
+ *
+ * translatorPlugin({
+ *   collections: [withAutoTranslate(Posts, { targets: ['de', 'fr'], debounceMs: 2000 })],
+ *   translationProvider,
+ *   runner,
+ * })
+ * ```
+ *
+ * @since 0.9.0
+ */
+export declare function withAutoTranslate(collection: CollectionConfig, config: AutoTranslateConfig): CollectionConfig;

package/dist/auto-translate-config.js

@@ -0,0 +1,46 @@
+import { AUTO_TRANSLATE_CUSTOM_KEY } from "./core/auto-translate-config";
+/**
+ * Enable opt-in **auto-translate** for a collection: when a document's source-locale content changes
+ * (and is published), the plugin automatically queues translations into the configured target locales.
+ * Off by default — a collection is opted in only by wrapping it with this helper. The rule is stamped
+ * onto `collection.custom` (the input is not mutated; a new collection is returned), mirroring
+ * `withFieldTranslation` at the field level.
+ *
+ * Behaviour: fires only on a **published** source save (draft/autosave saves are ignored; a collection
+ * without drafts treats every save as published); skips when no translatable content actually changed
+ * (drift-gate); coalesces rapid edits via `debounceMs`; never re-triggers on its own translation
+ * writes; and never fails the editor's save (best-effort).
+ *
+ * **Requires a working job runner.** Auto-translate only ENQUEUES jobs — they run via the plugin's
+ * task runner (`createPayloadJobsRunner`) and its autorun loop. On serverless platforms such as
+ * **Vercel**, cron-based autorun may not run automatically, so enqueued translations can sit
+ * unexecuted until triggered — e.g. an external cron hitting the run-translation endpoint, or a
+ * self-hosted worker. Ensure your deployment actually executes queued jobs before relying on this.
+ *
+ * @param collection - The collection to opt in.
+ * @param config - Target locales (+ optional strategy, debounce, source-locale override).
+ * @returns A new collection with the auto-translate rule applied (the input is not mutated).
+ *
+ * @example
+ * ```ts
+ * import { withAutoTranslate } from '@focus-reactive/payload-plugin-translator'
+ *
+ * translatorPlugin({
+ *   collections: [withAutoTranslate(Posts, { targets: ['de', 'fr'], debounceMs: 2000 })],
+ *   translationProvider,
+ *   runner,
+ * })
+ * ```
+ *
+ * @since 0.9.0
+ */ export function withAutoTranslate(collection, config) {
+    return {
+        ...collection,
+        custom: {
+            ...collection.custom ?? {},
+            [AUTO_TRANSLATE_CUSTOM_KEY]: config
+        }
+    };
+}
+
+//# sourceMappingURL=auto-translate-config.js.map

package/dist/client/entities/translation/index.d.ts

@@ -7,6 +7,7 @@ import { useCollectionTranslationStatus } from "./api/queries/useCollectionTrans
 import { useDocumentStaleness } from "./api/queries/useDocumentStaleness";
 import { useDocumentTranslation } from "./api/queries/useDocumentTranslation";
 export { TranslationStatusList } from "./ui/TranslationStatusList";
+export { AutoTranslateMarker } from "./ui/AutoTranslateMarker";
 export declare const TranslationsApi: {
     useRunDocumentTranslation: typeof useRunDocumentTranslation;
     useQueueDocumentTranslation: typeof useQueueDocumentTranslation;

package/dist/client/entities/translation/index.js

@@ -7,6 +7,7 @@ import { useCollectionTranslationStatus } from "./api/queries/useCollectionTrans
 import { useDocumentStaleness } from "./api/queries/useDocumentStaleness";
 import { useDocumentTranslation } from "./api/queries/useDocumentTranslation";
 export { TranslationStatusList } from "./ui/TranslationStatusList";
+export { AutoTranslateMarker } from "./ui/AutoTranslateMarker";
 export const TranslationsApi = {
     useRunDocumentTranslation,
     useQueueDocumentTranslation,

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

@@ -0,0 +1,15 @@
+/** The auto-translate facts the marker renders — resolved from a collection's opt-in config. */
+export type AutoTranslateSummary = {
+    targets: string[];
+    sourceLocale: string;
+};
+/**
+ * Resolve a collection's auto-translate summary for the popup marker, or `null` when it should not
+ * render. Reads the opt-in from the collection's `custom` (propagated onto the registered collection at
+ * init), resolves the source locale (per-collection override else the config default), and drops the
+ * source from the displayed targets. Returns `null` when off, when no source locale is resolvable, or
+ * when no target remains — so the caller renders the marker only when it is both enabled and meaningful.
+ */
+export declare function resolveAutoTranslateSummary(collection: {
+    custom?: Record<string, unknown>;
+} | undefined, defaultLocale: string | undefined): AutoTranslateSummary | null;

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

@@ -0,0 +1,22 @@
+import { getAutoTranslateConfig } from "../../../../core/auto-translate-config";
+/**
+ * Resolve a collection's auto-translate summary for the popup marker, or `null` when it should not
+ * render. Reads the opt-in from the collection's `custom` (propagated onto the registered collection at
+ * init), resolves the source locale (per-collection override else the config default), and drops the
+ * source from the displayed targets. Returns `null` when off, when no source locale is resolvable, or
+ * when no target remains — so the caller renders the marker only when it is both enabled and meaningful.
+ */ export function resolveAutoTranslateSummary(collection, defaultLocale) {
+    if (!collection) return null;
+    const config = getAutoTranslateConfig(collection);
+    if (!config) return null;
+    const sourceLocale = config.sourceLocale ?? defaultLocale;
+    if (!sourceLocale) return null;
+    const targets = config.targets.filter((target)=>target !== sourceLocale);
+    if (targets.length === 0) return null;
+    return {
+        targets,
+        sourceLocale
+    };
+}
+
+//# sourceMappingURL=autoTranslateSummary.js.map

package/dist/client/entities/translation/ui/AutoTranslateMarker/AutoTranslateMarker.d.ts

@@ -0,0 +1,14 @@
+type AutoTranslateMarkerProps = {
+    /** Target locale codes this collection auto-translates into (source already excluded). */
+    targets: string[];
+    /** The resolved source locale code changes are watched on. */
+    sourceLocale: string;
+};
+/**
+ * A quiet, off-to-the-side marker in the translation popups' header (document + collection): a single
+ * muted icon that a collection is opted into auto-translate. The detail lives in the tooltip, not the
+ * layout — this is ambient config the editor rarely needs, so it stays out of the popup's main vertical
+ * flow (title / Translate / Status). Rendered only when auto-translate is enabled.
+ */
+export declare function AutoTranslateMarker({ targets, sourceLocale }: AutoTranslateMarkerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/client/entities/translation/ui/AutoTranslateMarker/AutoTranslateMarker.js

@@ -0,0 +1,34 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AutoTranslateIcon } from "../../../../shared/lib/assets/icons/AutoTranslateIcon";
+import Tooltip from "../../../../shared/ui/Tooltip";
+import styles from "./styles.module.scss";
+/**
+ * A quiet, off-to-the-side marker in the translation popups' header (document + collection): a single
+ * muted icon that a collection is opted into auto-translate. The detail lives in the tooltip, not the
+ * layout — this is ambient config the editor rarely needs, so it stays out of the popup's main vertical
+ * flow (title / Translate / Status). Rendered only when auto-translate is enabled.
+ */ export function AutoTranslateMarker({ targets, sourceLocale }) {
+    return /*#__PURE__*/ _jsx(Tooltip, {
+        content: /*#__PURE__*/ _jsxs("span", {
+            className: styles.tip,
+            children: [
+                "Auto-translate is on. Publishing changes to the source (",
+                /*#__PURE__*/ _jsx("code", {
+                    children: sourceLocale
+                }),
+                ") content queues translations into ",
+                targets.join(" · "),
+                "."
+            ]
+        }),
+        children: /*#__PURE__*/ _jsx("span", {
+            className: styles.marker,
+            tabIndex: 0,
+            "aria-label": "Auto-translate enabled",
+            children: /*#__PURE__*/ _jsx(AutoTranslateIcon, {})
+        })
+    });
+}
+
+//# sourceMappingURL=AutoTranslateMarker.js.map

package/dist/client/entities/translation/ui/AutoTranslateMarker/index.d.ts

@@ -0,0 +1 @@
+export { AutoTranslateMarker } from "./AutoTranslateMarker";

package/dist/client/entities/translation/ui/AutoTranslateMarker/index.js

@@ -0,0 +1,3 @@
+export { AutoTranslateMarker } from "./AutoTranslateMarker";
+
+//# sourceMappingURL=index.js.map

package/dist/client/entities/translation/ui/AutoTranslateMarker/styles.module.scss

@@ -0,0 +1,30 @@
+// A muted, low-emphasis header marker — no border, no fill; it sits at the edge of the title row and
+// carries all detail in its tooltip, so it never competes with the popup's main flow.
+.marker {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--theme-elevation-400, #a5a5a5);
+  cursor: help;
+  outline: none;
+}
+
+.marker:hover {
+  color: var(--theme-elevation-600, #6d6d6d);
+}
+
+.marker:focus-visible {
+  outline: 2px solid var(--theme-elevation-400, #a5a5a5);
+  outline-offset: 2px;
+  border-radius: 3px;
+}
+
+.tip {
+  display: block;
+  max-width: 15rem;
+  line-height: 1.35;
+}
+
+.tip code {
+  font-family: var(--font-mono, ui-monospace, monospace);
+}

package/dist/client/shared/lib/assets/icons/AutoTranslateIcon.d.ts

@@ -0,0 +1,3 @@
+/** A lightning bolt — connotes "fires automatically" (on the publish event). Used by the
+ * auto-translate marker to distinguish automatic translation from the manual translate control. */
+export declare const AutoTranslateIcon: () => import("react/jsx-runtime").JSX.Element;

package/dist/client/shared/lib/assets/icons/AutoTranslateIcon.js

@@ -0,0 +1,14 @@
+/** A lightning bolt — connotes "fires automatically" (on the publish event). Used by the
+ * auto-translate marker to distinguish automatic translation from the manual translate control. */ import { jsx as _jsx } from "react/jsx-runtime";
+export const AutoTranslateIcon = ()=>/*#__PURE__*/ _jsx("svg", {
+        fill: "currentColor",
+        width: "1em",
+        height: "1em",
+        viewBox: "0 0 24 24",
+        xmlns: "http://www.w3.org/2000/svg",
+        children: /*#__PURE__*/ _jsx("path", {
+            d: "M13 2 L4.5 13.5 H11 L10 22 L19.5 10 H12.5 Z"
+        })
+    });
+
+//# sourceMappingURL=AutoTranslateIcon.js.map

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.d.ts

@@ -1,5 +1,7 @@
+import type { AutoTranslateSummary } from "../../../entities/translation/model/autoTranslateSummary";
 type BulkTranslationDashboardProps = {
     hasDrafts: boolean;
+    autoTranslate: AutoTranslateSummary | null;
 };
-export default function BulkTranslationDashboard({ hasDrafts }: BulkTranslationDashboardProps): import("react/jsx-runtime").JSX.Element;
+export default function BulkTranslationDashboard({ hasDrafts, autoTranslate, }: BulkTranslationDashboardProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { toast, useLocale, useSelection } from "@payloadcms/ui";
 import { SelectAllStatus } from "@payloadcms/ui/providers/Selection";
 import { useEffect, useMemo } from "react";
-import { deriveCollectionPanelStatus, TranslationsApi } from "../../../entities/translation";
+import { AutoTranslateMarker, deriveCollectionPanelStatus, TranslationsApi } from "../../../entities/translation";
 import { CollectionTranslationForm, FORM_FIELDS } from "../../../features/collection-translation-form";
 import { CollectionTranslationFormModel } from "../../../features/collection-translation-form/index.client";
 import CollectionTranslationPopup from "../../../features/collection-translation-popup";
@@ -11,7 +11,7 @@ import { CollectionTranslationProgress } from "../../../features/collection-tran
 import { handleFormError } from "../../../shared/lib/forms/handle-form-error";
 import { useCollectionDashboardUrlParams } from "../../../shared/lib/payload/hooks/useCollectionDashboardUrlParams";
 import styles from "./styles.module.scss";
-export default function BulkTranslationDashboard({ hasDrafts }) {
+export default function BulkTranslationDashboard({ hasDrafts, autoTranslate }) {
     const locale = useLocale();
     const { collection } = useCollectionDashboardUrlParams();
     const documentsSelection = useSelection();
@@ -58,9 +58,18 @@ export default function BulkTranslationDashboard({ hasDrafts }) {
         status: panelStatus,
         selectedCount: selectedCount,
         children: [
-            /*#__PURE__*/ _jsx("h4", {
-                className: styles.title,
-                children: "Bulk translation"
+            /*#__PURE__*/ _jsxs("div", {
+                className: styles.header,
+                children: [
+                    /*#__PURE__*/ _jsx("h4", {
+                        className: styles.title,
+                        children: "Bulk translation"
+                    }),
+                    autoTranslate && /*#__PURE__*/ _jsx(AutoTranslateMarker, {
+                        targets: autoTranslate.targets,
+                        sourceLocale: autoTranslate.sourceLocale
+                    })
+                ]
             }),
             /*#__PURE__*/ _jsxs("section", {
                 className: styles.section,

package/dist/client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.server.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { headers as getHeaders } from "next/headers";
 import { collectionHasDrafts } from "../../../../server/shared/guards";
+import { resolveAutoTranslateSummary } from "../../../entities/translation/model/autoTranslateSummary";
 import BulkTranslationDashboard from "./BulkTranslationDashboard";
 const BulkTranslationDashboardServer = async (props)=>{
     const headers = await getHeaders();
@@ -15,8 +16,10 @@ const BulkTranslationDashboardServer = async (props)=>{
     if (!props.collectionSlug) return null;
     const collection = props.payload.collections[props.collectionSlug]?.config;
     const hasDrafts = collection ? collectionHasDrafts(collection) : false;
+    const autoTranslate = resolveAutoTranslateSummary(collection, props.payload.config.localization ? props.payload.config.localization.defaultLocale : undefined);
     return /*#__PURE__*/ _jsx(BulkTranslationDashboard, {
-        hasDrafts: hasDrafts
+        hasDrafts: hasDrafts,
+        autoTranslate: autoTranslate
     });
 };
 export default BulkTranslationDashboardServer;

package/dist/client/widgets/bulk-translation-dashboard/ui/styles.module.scss

@@ -1,3 +1,12 @@
+// Title row: the section heading on the left, ambient markers (e.g. auto-translate) pushed to the
+// right edge so they stay out of the popup's main vertical flow.
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
 .title {
   margin: 0;
   font-size: 0.8125rem;

package/dist/client/widgets/translate-document/ui/TranslateDocument.d.ts

@@ -1,5 +1,7 @@
+import type { AutoTranslateSummary } from "../../../entities/translation/model/autoTranslateSummary";
 type TranslateDocumentProps = {
     hasDrafts: boolean;
+    autoTranslate: AutoTranslateSummary | null;
 };
-declare const TranslateDocument: ({ hasDrafts }: TranslateDocumentProps) => import("react/jsx-runtime").JSX.Element;
+declare const TranslateDocument: ({ hasDrafts, autoTranslate }: TranslateDocumentProps) => import("react/jsx-runtime").JSX.Element;
 export default TranslateDocument;

package/dist/client/widgets/translate-document/ui/TranslateDocument.js

@@ -2,14 +2,14 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { toast, useLocale } from "@payloadcms/ui";
 import { useEffect, useMemo } from "react";
-import { buildTranslationStatusRows, deriveDocumentRunStatus, derivePanelStatus, TranslationsApi, TranslationStatusList } from "../../../entities/translation";
+import { AutoTranslateMarker, buildTranslationStatusRows, deriveDocumentRunStatus, derivePanelStatus, TranslationsApi, TranslationStatusList } from "../../../entities/translation";
 import { OpenDocumentTranslationPopup } from "../../../features/open-document-translation-popup";
 import { DocumentTranslationForm, FORM_FIELDS } from "../../../features/translate-document-form";
 import { DocumentTranslationFormModel } from "../../../features/translate-document-form/index.client";
 import { handleFormError } from "../../../shared/lib/forms/handle-form-error";
 import { useCollectionDocumentUrlParams } from "../../../shared/lib/payload/hooks/useCollectionDocumentUrlParams";
 import styles from "./styles.module.scss";
-const TranslateDocument = ({ hasDrafts })=>{
+const TranslateDocument = ({ hasDrafts, autoTranslate })=>{
     const locale = useLocale();
     const params = useCollectionDocumentUrlParams();
     const queueTranslationApi = TranslationsApi.useQueueDocumentTranslation();
@@ -72,9 +72,18 @@ const TranslateDocument = ({ hasDrafts })=>{
         status: panelStatus,
         children: ({ close })=>/*#__PURE__*/ _jsxs(_Fragment, {
                 children: [
-                    /*#__PURE__*/ _jsx("h4", {
-                        className: styles.title,
-                        children: "Document translation"
+                    /*#__PURE__*/ _jsxs("div", {
+                        className: styles.header,
+                        children: [
+                            /*#__PURE__*/ _jsx("h4", {
+                                className: styles.title,
+                                children: "Document translation"
+                            }),
+                            autoTranslate && /*#__PURE__*/ _jsx(AutoTranslateMarker, {
+                                targets: autoTranslate.targets,
+                                sourceLocale: autoTranslate.sourceLocale
+                            })
+                        ]
                     }),
                     /*#__PURE__*/ _jsxs("section", {
                         className: styles.section,

package/dist/client/widgets/translate-document/ui/TranslateDocument.server.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { headers as getHeaders } from "next/headers";
 import { collectionHasDrafts } from "../../../../server/shared/guards";
+import { resolveAutoTranslateSummary } from "../../../entities/translation/model/autoTranslateSummary";
 import TranslateDocument from "./TranslateDocument";
 async function TranslateDocumentServer(props) {
     const headers = await getHeaders();
@@ -14,8 +15,10 @@ async function TranslateDocumentServer(props) {
     if (!hasAccess) return null;
     if (!props.id) return null;
     const hasDrafts = collectionHasDrafts(props.collection);
+    const autoTranslate = resolveAutoTranslateSummary(props.collection, props.payload.config.localization ? props.payload.config.localization.defaultLocale : undefined);
     return /*#__PURE__*/ _jsx(TranslateDocument, {
-        hasDrafts: hasDrafts
+        hasDrafts: hasDrafts,
+        autoTranslate: autoTranslate
     });
 }
 export default TranslateDocumentServer;

package/dist/client/widgets/translate-document/ui/styles.module.scss

@@ -1,3 +1,12 @@
+// Title row: the section heading on the left, ambient markers (e.g. auto-translate) pushed to the
+// right edge so they stay out of the popup's main vertical flow.
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
 .title {
   margin: 0;
   font-size: 0.8125rem;

package/dist/core/auto-translate/hasSourceContentChanged.d.ts

@@ -0,0 +1,21 @@
+import type { FieldLike } from "../field-traversal";
+/**
+ * Whether a source-locale save actually changed translatable content — the auto-translate drift-gate,
+ * in one place. Compares the translatable-content fingerprint of the previous vs the current document
+ * (the same hash the provenance write/read path uses via {@link computeSourceFingerprint}), so a save
+ * that touched only non-translatable fields never triggers a re-translation.
+ *
+ * A create (no `previousDoc`) counts as changed: there is nothing to diff against, and the new
+ * document's translatable content is by definition not yet translated.
+ *
+ * Pure and payload-free (sibling of `core/provenance` `isRecordStale`) so the gate is testable without
+ * a database; the server hook supplies the two documents Payload already hands to `afterChange` plus
+ * the original field schema.
+ *
+ * @param previousDoc - The source document before this save, or `null`/`undefined` on create.
+ * @param nextDoc - The source document after this save.
+ * @param schema - The ORIGINAL (un-sanitized) field schema for the collection.
+ * @returns `true` when translatable content changed (or on create); `false` when unchanged.
+ * @since 0.9.0
+ */
+export declare function hasSourceContentChanged(previousDoc: Record<string, unknown> | null | undefined, nextDoc: Record<string, unknown>, schema: FieldLike[]): boolean;

package/dist/core/auto-translate/hasSourceContentChanged.js

@@ -0,0 +1,25 @@
+import { computeSourceFingerprint } from "../content-projection/computeSourceFingerprint";
+/**
+ * Whether a source-locale save actually changed translatable content — the auto-translate drift-gate,
+ * in one place. Compares the translatable-content fingerprint of the previous vs the current document
+ * (the same hash the provenance write/read path uses via {@link computeSourceFingerprint}), so a save
+ * that touched only non-translatable fields never triggers a re-translation.
+ *
+ * A create (no `previousDoc`) counts as changed: there is nothing to diff against, and the new
+ * document's translatable content is by definition not yet translated.
+ *
+ * Pure and payload-free (sibling of `core/provenance` `isRecordStale`) so the gate is testable without
+ * a database; the server hook supplies the two documents Payload already hands to `afterChange` plus
+ * the original field schema.
+ *
+ * @param previousDoc - The source document before this save, or `null`/`undefined` on create.
+ * @param nextDoc - The source document after this save.
+ * @param schema - The ORIGINAL (un-sanitized) field schema for the collection.
+ * @returns `true` when translatable content changed (or on create); `false` when unchanged.
+ * @since 0.9.0
+ */ export function hasSourceContentChanged(previousDoc, nextDoc, schema) {
+    if (!previousDoc) return true;
+    return computeSourceFingerprint(previousDoc, schema) !== computeSourceFingerprint(nextDoc, schema);
+}
+
+//# sourceMappingURL=hasSourceContentChanged.js.map

package/dist/core/auto-translate/index.d.ts

@@ -0,0 +1 @@
+export { hasSourceContentChanged } from "./hasSourceContentChanged";

package/dist/core/auto-translate/index.js

@@ -0,0 +1,3 @@
+export { hasSourceContentChanged } from "./hasSourceContentChanged";
+
+//# sourceMappingURL=index.js.map

package/dist/core/auto-translate-config/getAutoTranslateConfig.d.ts

@@ -0,0 +1,14 @@
+import type { AutoTranslateConfig } from "./types";
+/**
+ * Read a collection's auto-translate rule from its `custom` bag, or `null` when the collection is not
+ * opted in. Payload-free (only the `custom` extension point is read), mirroring
+ * `getFieldTranslationConfig` at the field level. Returns `null` when the key is absent OR holds a value
+ * that is not a valid config, so a foreign `custom.{key}` collision can never crash a caller.
+ *
+ * @param collection - The collection to read (only its `custom` extension point is inspected).
+ * @returns The auto-translate config, or `null` when absent/malformed.
+ * @since 0.9.0
+ */
+export declare function getAutoTranslateConfig(collection: {
+    custom?: Record<string, unknown>;
+}): AutoTranslateConfig | null;

package/dist/core/auto-translate-config/getAutoTranslateConfig.js

@@ -0,0 +1,29 @@
+import { isObject } from "../utils/isObject";
+import { AUTO_TRANSLATE_CUSTOM_KEY } from "./types";
+/**
+ * Structural guard: is `value` a well-formed auto-translate config? Validates the one crash-critical
+ * invariant — `targets` is an array of strings — so a foreign value that a consumer happened to store
+ * under {@link AUTO_TRANSLATE_CUSTOM_KEY} (the key is a shared `custom` namespace, so a collision, while
+ * unlikely, is possible) is treated as "not opted in" rather than crashing the readers that dereference
+ * `targets`.
+ */ function isAutoTranslateConfig(value) {
+    if (!isObject(value)) return false;
+    const { targets } = value;
+    return Array.isArray(targets) && targets.every((target)=>typeof target === "string");
+}
+/**
+ * Read a collection's auto-translate rule from its `custom` bag, or `null` when the collection is not
+ * opted in. Payload-free (only the `custom` extension point is read), mirroring
+ * `getFieldTranslationConfig` at the field level. Returns `null` when the key is absent OR holds a value
+ * that is not a valid config, so a foreign `custom.{key}` collision can never crash a caller.
+ *
+ * @param collection - The collection to read (only its `custom` extension point is inspected).
+ * @returns The auto-translate config, or `null` when absent/malformed.
+ * @since 0.9.0
+ */ export function getAutoTranslateConfig(collection) {
+    if (!isObject(collection.custom)) return null;
+    const value = collection.custom[AUTO_TRANSLATE_CUSTOM_KEY];
+    return isAutoTranslateConfig(value) ? value : null;
+}
+
+//# sourceMappingURL=getAutoTranslateConfig.js.map

package/dist/core/auto-translate-config/index.d.ts

@@ -0,0 +1,3 @@
+export { getAutoTranslateConfig } from "./getAutoTranslateConfig";
+export { AUTO_TRANSLATE_CUSTOM_KEY } from "./types";
+export type { AutoTranslateConfig, AutoTranslateStrategy } from "./types";

package/dist/core/auto-translate-config/index.js

@@ -0,0 +1,4 @@
+export { getAutoTranslateConfig } from "./getAutoTranslateConfig";
+export { AUTO_TRANSLATE_CUSTOM_KEY } from "./types";
+
+//# sourceMappingURL=index.js.map

package/dist/core/auto-translate-config/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Key under a collection's `custom` bag where its auto-translate rule is stamped by `withAutoTranslate`
+ * and read back by {@link getAutoTranslateConfig}. Mirrors the field-level `TRANSLATE_KIT_CUSTOM_KEY`
+ * pattern — a single typed key so writer and reader never diverge.
+ */
+export declare const AUTO_TRANSLATE_CUSTOM_KEY = "translatorAutoTranslate";
+/**
+ * Translation strategy for auto-enqueued jobs (matches the task-runner's strategy union):
+ * - `"overwrite"` — (re)translate every target field, replacing any existing target-locale value.
+ * - `"skip_existing"` — only fill target fields that are currently empty, leaving existing translations
+ *   untouched.
+ * @since 0.9.0
+ */
+export type AutoTranslateStrategy = "overwrite" | "skip_existing";
+/**
+ * A collection's opt-in auto-translate rule (developer-configured, v1). Presence of this config on a
+ * collection = opted in; absence = off (the default).
+ * @since 0.9.0
+ */
+export type AutoTranslateConfig = {
+    /** Target locales to translate into when the source changes. The source locale is always excluded. */
+    targets: string[];
+    /** Translation strategy; defaults to `"overwrite"`. */
+    strategy?: AutoTranslateStrategy;
+    /**
+     * Delay (ms) before the queued job runs, coalescing rapid edits via the job runner's
+     * per-(document, locale) supersession. `0`/omitted = enqueue immediately.
+     */
+    debounceMs?: number;
+    /** Override the source locale for this collection; defaults to `localization.defaultLocale`. */
+    sourceLocale?: string;
+};

package/dist/core/auto-translate-config/types.js

@@ -0,0 +1,7 @@
+/**
+ * Key under a collection's `custom` bag where its auto-translate rule is stamped by `withAutoTranslate`
+ * and read back by {@link getAutoTranslateConfig}. Mirrors the field-level `TRANSLATE_KIT_CUSTOM_KEY`
+ * pattern — a single typed key so writer and reader never diverge.
+ */ export const AUTO_TRANSLATE_CUSTOM_KEY = "translatorAutoTranslate";
+
+//# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { documentLevel, collectionLevel, fieldLevel } from "./composition/levels
 export type { TranslationLevel } from "./server/modules/translation-levels";
 export { withFieldTranslation } from "./field-config";
 export type { FieldTranslationConfig } from "./field-config";
+export { withAutoTranslate } from "./auto-translate-config";
+export type { AutoTranslateConfig, AutoTranslateStrategy } from "./auto-translate-config";
 export { createTranslatePlugin, TranslateCollectionPlugin } from "./plugin";
 export type { TranslateCollectionPluginConfig } from "./plugin";
 export { OpenAITranslationProvider } from "./translation-providers";

package/dist/index.js

@@ -8,6 +8,10 @@ export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task
 export { documentLevel, collectionLevel, fieldLevel } from "./composition/levels";
 // Field config
 export { withFieldTranslation } from "./field-config";
+// Auto-translate — opt-in, per-collection auto-translation on source-locale change (#51). Wrap a
+// collection with `withAutoTranslate`; requires a working job runner/autorun to execute (see the
+// JSDoc for the Vercel/serverless caveat). Since v0.9.0.
+export { withAutoTranslate } from "./auto-translate-config";
 // Deprecated exports (for backwards compatibility)
 export { createTranslatePlugin, TranslateCollectionPlugin } from "./plugin";
 export { OpenAITranslationProvider } from "./translation-providers";

package/dist/plugin.js

@@ -1,4 +1,5 @@
 import { CacheProviderExport } from "./client/app/cache/CacheProvider.export";
+import { configureAutoTranslate } from "./server/modules/auto-translate";
 import { configureProvenance } from "./server/modules/provenance";
 import { wireTranslateRunner } from "./server/features/translate-document";
 import { documentLevel, collectionLevel } from "./composition/levels";
@@ -36,6 +37,9 @@ import { normalizePath } from "./server/shared";
                 lifecycle: lifecycle ?? {},
                 collections: Array.from(collectionSlugs)
             });
+            // Auto-translate (#51) reads its opt-in from each collection's `custom` (via `withAutoTranslate`);
+            // needs the runner's factory, so it wires after `wireTranslateRunner`.
+            const autoTranslateModule = configureAutoTranslate(collections, schemaMap, taskRunnerFactory);
             const activeLevels = levels ?? [
                 documentLevel(),
                 collectionLevel()
@@ -52,6 +56,7 @@ import { normalizePath } from "./server/shared";
             for (const level of activeLevels)level.extend(builder);
             builder.addConfigModifier(runnerConfigModifier);
             builder.addConfigModifier(provenanceModule.configure(collectionSlugs));
+            builder.addConfigModifier(autoTranslateModule.configure(collectionSlugs));
             builder.addAdminProvider(new CacheProviderExport(basePath));
             // The single place the Payload config is mutated.
             return builder.applyTo(config);

package/dist/server/features/translate-document/handler.js

@@ -1,6 +1,7 @@
 import { APIError } from "payload";
 import { translateContent } from "../../../core/translation-pipeline";
 import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
+import { AUTO_TRANSLATE_SKIP_CONTEXT_KEY } from "../../../types/AutoTranslateContext";
 /**
  * Translates a single document from source language to target language. Provenance is delegated to
  * {@link ProvenanceService}: this handler only decides *when* to capture the source fingerprint
@@ -73,7 +74,14 @@ import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
             data: translatedData,
             autosave: isAutosaveEnabled,
             locale: targetLng,
-            fallbackLocale: sourceLng
+            fallbackLocale: sourceLng,
+            // Mark this as a translator-authored write so the auto-translate afterChange hook (#51) skips it
+            // — the loop guard's second barrier, alongside the source-locale check. This write always targets
+            // the TARGET locale, so it is already exempt by locale; the flag also covers any future write
+            // path that could touch the source locale.
+            context: {
+                [AUTO_TRANSLATE_SKIP_CONTEXT_KEY]: true
+            }
         });
     }
 }

package/dist/server/modules/auto-translate/AutoTranslate.policy.d.ts

@@ -0,0 +1,79 @@
+import type { CollectionSlug } from "payload";
+import type { AutoTranslateConfig } from "../../../core/auto-translate-config";
+import type { TaskInput } from "../task-runner/types";
+/** A collection's auto-translate rule with defaults resolved — the shape the hook consumes. */
+export type NormalizedAutoTranslatePolicy = {
+    targets: string[];
+    strategy: "overwrite" | "skip_existing";
+    debounceMs: number;
+    sourceLocale?: string;
+};
+/**
+ * Resolve the effective auto-translate policy for a document, or `null` when off. The `doc` parameter
+ * is the reserved seam for the future document-level manager override (#51 D7): v1 resolves at the
+ * collection level and IGNORES `doc`; a later phase supplies a second implementation that consults the
+ * document, without changing the hook, drift-gate, debounce, or wiring.
+ */
+export type AutoTranslatePolicyResolver = (collectionSlug: string, doc: Record<string, unknown>) => NormalizedAutoTranslatePolicy | null;
+/** Apply defaults to a raw config: strategy → "overwrite", debounce → 0. Duplicate target locales are
+ * de-duplicated so a misconfigured `targets: ["de","de"]` never enqueues two racing jobs for the same
+ * (document, locale) in one batch (the runner's supersession only dedupes against already-stored jobs). */
+export declare function normalizeAutoTranslateConfig(config: AutoTranslateConfig): NormalizedAutoTranslatePolicy;
+/**
+ * A minimal localization shape — the set of configured locale codes, in either form Payload accepts
+ * (`"en"` or `{ code: "en" }`). Payload's `Config["localization"]` is structurally assignable, so the
+ * caller passes it straight in with no adapter and tests pass a tiny literal.
+ */
+export type LocalizationLike = false | {
+    locales: Array<string | {
+        code: string;
+    }>;
+};
+/** Extract the configured locale codes, or `null` when localization is disabled/absent. */
+export declare function extractLocaleCodes(localization: LocalizationLike | undefined): Set<string> | null;
+/** Outcome of validating a policy's locales against the configured set — the filtered policy plus what
+ * was dropped, so the caller can warn precisely. */
+export type PolicyLocaleFilter = {
+    policy: NormalizedAutoTranslatePolicy;
+    droppedTargets: string[];
+    droppedSourceLocale: string | null;
+};
+/**
+ * Drop targets (and a `sourceLocale` override) that are not configured locales, so a mistyped locale in
+ * `withAutoTranslate` never reaches the pipeline — where it would silently burn a provider call and
+ * either error at the DB (Postgres locale enum) or write orphaned, invisible data (Mongo/SQLite). Pure:
+ * returns a new policy and reports the drops; the caller (config-time wiring) emits the warning.
+ */
+export declare function filterPolicyToKnownLocales(policy: NormalizedAutoTranslatePolicy, knownLocales: Set<string>): PolicyLocaleFilter;
+/**
+ * The v1 (collection-level) resolver. Ignores `doc` — see {@link AutoTranslatePolicyResolver}. This is
+ * the single seam a future document-level manager replaces.
+ */
+export declare function makeCollectionPolicyResolver(policies: Map<string, NormalizedAutoTranslatePolicy>): AutoTranslatePolicyResolver;
+/**
+ * Publish-gate (#51 D8): a drafts-enabled collection auto-translates only on a **published** save;
+ * autosave/draft saves are ignored. A collection without drafts has no `_status`, so every save
+ * qualifies. Applies uniformly to create and update.
+ */
+export declare function passesPublishGate(doc: Record<string, unknown>, hasDrafts: boolean): boolean;
+/**
+ * Mirror the source document's status onto the translation (#51 D9). Combined with the publish-gate,
+ * the source is published whenever we reach enqueue, so translations publish; a no-drafts collection
+ * publishes too. Deliberately identical to {@link passesPublishGate} today — kept as a SEPARATE
+ * function (not merged) because it diverges once a future document-level manager (R8) can bypass the
+ * gate and translate a still-draft source; do not collapse the two.
+ */
+export declare function resolvePublishOnTranslation(doc: Record<string, unknown>, hasDrafts: boolean): boolean;
+/**
+ * Build one {@link TaskInput} per configured target locale (the source locale is always excluded).
+ * `waitUntil` encodes the debounce; `now` is injected so the timestamp is deterministic in tests.
+ */
+export declare function buildAutoTranslateTasks(args: {
+    policy: NormalizedAutoTranslatePolicy;
+    collectionSlug: CollectionSlug;
+    documentId: string;
+    sourceLocale: string;
+    doc: Record<string, unknown>;
+    hasDrafts: boolean;
+    now: number;
+}): TaskInput[];

package/dist/server/modules/auto-translate/AutoTranslate.policy.js

@@ -0,0 +1,77 @@
+/** Apply defaults to a raw config: strategy → "overwrite", debounce → 0. Duplicate target locales are
+ * de-duplicated so a misconfigured `targets: ["de","de"]` never enqueues two racing jobs for the same
+ * (document, locale) in one batch (the runner's supersession only dedupes against already-stored jobs). */ export function normalizeAutoTranslateConfig(config) {
+    return {
+        targets: [
+            ...new Set(config.targets)
+        ],
+        strategy: config.strategy ?? "overwrite",
+        debounceMs: config.debounceMs ?? 0,
+        sourceLocale: config.sourceLocale
+    };
+}
+/** Extract the configured locale codes, or `null` when localization is disabled/absent. */ export function extractLocaleCodes(localization) {
+    if (!localization) return null;
+    return new Set(localization.locales.map((locale)=>typeof locale === "string" ? locale : locale.code));
+}
+/**
+ * Drop targets (and a `sourceLocale` override) that are not configured locales, so a mistyped locale in
+ * `withAutoTranslate` never reaches the pipeline — where it would silently burn a provider call and
+ * either error at the DB (Postgres locale enum) or write orphaned, invisible data (Mongo/SQLite). Pure:
+ * returns a new policy and reports the drops; the caller (config-time wiring) emits the warning.
+ */ export function filterPolicyToKnownLocales(policy, knownLocales) {
+    const droppedTargets = policy.targets.filter((target)=>!knownLocales.has(target));
+    const sourceUnknown = policy.sourceLocale !== undefined && !knownLocales.has(policy.sourceLocale);
+    return {
+        policy: {
+            ...policy,
+            targets: policy.targets.filter((target)=>knownLocales.has(target)),
+            sourceLocale: sourceUnknown ? undefined : policy.sourceLocale
+        },
+        droppedTargets,
+        droppedSourceLocale: sourceUnknown ? policy.sourceLocale ?? null : null
+    };
+}
+/**
+ * The v1 (collection-level) resolver. Ignores `doc` — see {@link AutoTranslatePolicyResolver}. This is
+ * the single seam a future document-level manager replaces.
+ */ export function makeCollectionPolicyResolver(policies) {
+    return (collectionSlug, _doc)=>policies.get(collectionSlug) ?? null;
+}
+/**
+ * Publish-gate (#51 D8): a drafts-enabled collection auto-translates only on a **published** save;
+ * autosave/draft saves are ignored. A collection without drafts has no `_status`, so every save
+ * qualifies. Applies uniformly to create and update.
+ */ export function passesPublishGate(doc, hasDrafts) {
+    if (!hasDrafts) return true;
+    return doc._status === "published";
+}
+/**
+ * Mirror the source document's status onto the translation (#51 D9). Combined with the publish-gate,
+ * the source is published whenever we reach enqueue, so translations publish; a no-drafts collection
+ * publishes too. Deliberately identical to {@link passesPublishGate} today — kept as a SEPARATE
+ * function (not merged) because it diverges once a future document-level manager (R8) can bypass the
+ * gate and translate a still-draft source; do not collapse the two.
+ */ export function resolvePublishOnTranslation(doc, hasDrafts) {
+    if (!hasDrafts) return true;
+    return doc._status === "published";
+}
+/**
+ * Build one {@link TaskInput} per configured target locale (the source locale is always excluded).
+ * `waitUntil` encodes the debounce; `now` is injected so the timestamp is deterministic in tests.
+ */ export function buildAutoTranslateTasks(args) {
+    const { policy, collectionSlug, documentId, sourceLocale, doc, hasDrafts, now } = args;
+    const publishOnTranslation = resolvePublishOnTranslation(doc, hasDrafts);
+    const waitUntil = policy.debounceMs > 0 ? new Date(now + policy.debounceMs) : undefined;
+    return policy.targets.filter((target)=>target !== sourceLocale).map((target)=>({
+            collectionSlug,
+            collectionId: documentId,
+            sourceLng: sourceLocale,
+            targetLng: target,
+            strategy: policy.strategy,
+            publishOnTranslation,
+            waitUntil
+        }));
+}
+
+//# sourceMappingURL=AutoTranslate.policy.js.map

package/dist/server/modules/auto-translate/AutoTranslate.shapes.d.ts

@@ -0,0 +1,22 @@
+import type { CollectionAfterChangeHook } from "payload";
+/**
+ * The minimal slice of a Payload collection the auto-translate wiring mutates: its `slug` and the
+ * `afterChange` hook slot. A real `CollectionConfig` is structurally assignable to this, so call sites
+ * pass the live collection with no adapter and tests pass a `{ slug: "posts" }` literal. Keeps
+ * `injectAutoTranslateHook` off the god-`CollectionConfig` type (own shape — provenance's is not reused,
+ * per the module-owns-its-shape convention). The only Payload type imported is the hook callback
+ * contract, which legitimately stays framework-typed.
+ */
+export type AutoTranslateManagedEntry = {
+    slug: string;
+    hooks?: {
+        afterChange?: CollectionAfterChangeHook[];
+    };
+    /** The `custom` bag — the opt-in is propagated here so the admin UI can read it back off the
+     * REGISTERED collection (which may be a different object than the one `withAutoTranslate` wrapped). */
+    custom?: Record<string, unknown>;
+};
+/** The minimal config host: a mutable `collections` array. A real Payload `Config` plugs straight in. */
+export type AutoTranslateManagedConfig = {
+    collections?: AutoTranslateManagedEntry[];
+};

package/dist/server/modules/auto-translate/AutoTranslate.shapes.js

@@ -0,0 +1,3 @@
+/** The minimal config host: a mutable `collections` array. A real Payload `Config` plugs straight in. */ export { };
+
+//# sourceMappingURL=AutoTranslate.shapes.js.map

package/dist/server/modules/auto-translate/AutoTranslate.wiring.d.ts

@@ -0,0 +1,21 @@
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+import type { ConfigModifier } from "../../../types/ConfigModifier";
+import type { TaskRunnerFactory } from "../task-runner";
+/** A collection as the plugin receives it — only `slug` + `custom` are read to resolve the opt-in. */
+type ConfigurableCollection = {
+    slug: string;
+    custom?: Record<string, unknown>;
+};
+/** Everything the auto-translate module contributes at config time (mirrors `ProvenanceModule`). */
+export type AutoTranslateModule = {
+    configure(managedSlugs: Set<string>): ConfigModifier;
+};
+/**
+ * Turn the opt-in `withAutoTranslate` config (read from each collection's `custom`) into a
+ * self-contained {@link AutoTranslateModule} — mirrors `configureProvenance`. Builds the per-collection
+ * policy map + resolver once, then returns a `configure(managedSlugs) → ConfigModifier` that injects a
+ * single best-effort `afterChange` hook onto every enabled + managed collection. When no collection
+ * opted in, `configure` is a no-op (no hook, no behaviour change).
+ */
+export declare function configureAutoTranslate(collections: ConfigurableCollection[], schemaMap: CollectionSchemaMap, taskRunnerFactory: TaskRunnerFactory): AutoTranslateModule;
+export {};

package/dist/server/modules/auto-translate/AutoTranslate.wiring.js

@@ -0,0 +1,68 @@
+import { getAutoTranslateConfig } from "../../../core/auto-translate-config";
+import { extractLocaleCodes, filterPolicyToKnownLocales, makeCollectionPolicyResolver, normalizeAutoTranslateConfig } from "./AutoTranslate.policy";
+import { injectAutoTranslateHook, makeAutoTranslateHook, propagateAutoTranslateCustom } from "./AutoTranslateEnqueue.hook";
+const NOOP = (config)=>config;
+/** Emit one clear config-time warning per collection whose auto-translate config named unknown locales. */ function warnDroppedLocales(slug, filtered, knownLocales) {
+    const known = [
+        ...knownLocales
+    ].join(", ");
+    if (filtered.droppedTargets.length > 0) {
+        console.warn(`[payload-plugin-translator] auto-translate on "${slug}": ignoring unknown target locale(s) ${filtered.droppedTargets.join(", ")} (configured locales: ${known}).`);
+    }
+    if (filtered.droppedSourceLocale) {
+        console.warn(`[payload-plugin-translator] auto-translate on "${slug}": unknown sourceLocale "${filtered.droppedSourceLocale}" ignored, falling back to the default locale (configured locales: ${known}).`);
+    }
+}
+/**
+ * Turn the opt-in `withAutoTranslate` config (read from each collection's `custom`) into a
+ * self-contained {@link AutoTranslateModule} — mirrors `configureProvenance`. Builds the per-collection
+ * policy map + resolver once, then returns a `configure(managedSlugs) → ConfigModifier` that injects a
+ * single best-effort `afterChange` hook onto every enabled + managed collection. When no collection
+ * opted in, `configure` is a no-op (no hook, no behaviour change).
+ */ export function configureAutoTranslate(collections, schemaMap, taskRunnerFactory) {
+    const policies = new Map();
+    for (const collection of collections){
+        const config = getAutoTranslateConfig(collection);
+        if (config) policies.set(collection.slug, normalizeAutoTranslateConfig(config));
+    }
+    if (policies.size === 0) return {
+        configure: ()=>NOOP
+    };
+    const enabledSlugs = new Set(policies.keys());
+    const resolvePolicy = makeCollectionPolicyResolver(policies);
+    const hook = makeAutoTranslateHook({
+        resolvePolicy,
+        schemaMap,
+        taskRunnerFactory
+    });
+    return {
+        configure: (managedSlugs)=>(config)=>{
+                // Inject only onto collections that both opted in AND are plugin-managed.
+                const slugs = new Set([
+                    ...enabledSlugs
+                ].filter((slug)=>managedSlugs.has(slug)));
+                // Drop targets / source-locale overrides that are not configured locales, fail-fast with a
+                // warning at init — else a mistyped locale silently burns provider calls and orphans data at
+                // runtime. Filter the shared `policies` map once here (config-time, before any hook fires), so
+                // the hook, the propagated `custom`, and the admin indicator all read the corrected policy.
+                const knownLocales = extractLocaleCodes(config.localization);
+                if (knownLocales) {
+                    for (const slug of slugs){
+                        const policy = policies.get(slug);
+                        if (!policy) continue;
+                        const filtered = filterPolicyToKnownLocales(policy, knownLocales);
+                        warnDroppedLocales(slug, filtered, knownLocales);
+                        policies.set(slug, filtered.policy);
+                    }
+                } else if (slugs.size > 0) {
+                    console.warn("[payload-plugin-translator] auto-translate is configured but localization is disabled; no translations will be enqueued.");
+                }
+                injectAutoTranslateHook(config, slugs, hook);
+                // Mirror the opt-in onto the registered collection's `custom` so the admin UI can read it back.
+                propagateAutoTranslateCustom(config, slugs, policies);
+                return config;
+            }
+    };
+}
+
+//# sourceMappingURL=AutoTranslate.wiring.js.map

package/dist/server/modules/auto-translate/AutoTranslateEnqueue.hook.d.ts

@@ -0,0 +1,39 @@
+import type { CollectionAfterChangeHook } from "payload";
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+import type { TaskRunnerFactory } from "../task-runner";
+import type { AutoTranslatePolicyResolver, NormalizedAutoTranslatePolicy } from "./AutoTranslate.policy";
+import type { AutoTranslateManagedConfig } from "./AutoTranslate.shapes";
+type AutoTranslateHookDeps = {
+    resolvePolicy: AutoTranslatePolicyResolver;
+    schemaMap: CollectionSchemaMap;
+    taskRunnerFactory: TaskRunnerFactory;
+};
+/**
+ * Build the `afterChange` hook that auto-enqueues translations when a document's source-locale content
+ * changes. Thin orchestration only — every decision lives in `AutoTranslate.policy.ts` or the core
+ * drift predicate. Best-effort by contract: any failure is logged and swallowed, never failing the
+ * editor's save.
+ *
+ * Order (cheap guards first): (1) skip the translator's own writes via the `req.context` flag;
+ * (2) resolve the policy — off ⇒ skip; (3) resolve the source locale (per-collection override else
+ * `localization.defaultLocale`) — unresolved ⇒ log + skip; (4) skip non-source-locale writes (the
+ * pipeline's target writes never match); (5) publish-gate (D8); (6) drift-gate (D3); then enqueue one
+ * job per target locale.
+ */
+export declare function makeAutoTranslateHook(deps: AutoTranslateHookDeps): CollectionAfterChangeHook;
+/**
+ * Attach the auto-translate hook to every enabled collection on `config`, appending to any
+ * consumer-supplied `afterChange` array. Idempotent: a collection that already carries the marked hook
+ * is skipped, so a repeated `init()` never stacks duplicates.
+ */
+export declare function injectAutoTranslateHook(config: AutoTranslateManagedConfig, enabledSlugs: Set<string>, hook: CollectionAfterChangeHook): void;
+/**
+ * Propagate each enabled collection's resolved policy onto the REGISTERED collection's `custom` bag, so
+ * the admin UI can read the opt-in back via `getAutoTranslateConfig`. This is required because
+ * `withAutoTranslate` stamps `custom` on the object passed to the plugin's `collections` param, which
+ * can be a DIFFERENT object than the one registered in `buildConfig.collections` (the reader would
+ * otherwise see no config and the indicator would disagree with the behaviour). Idempotent + additive:
+ * re-stamping the same value is a no-op and the behaviour wiring still reads from the plugin param.
+ */
+export declare function propagateAutoTranslateCustom(config: AutoTranslateManagedConfig, enabledSlugs: Set<string>, policies: Map<string, NormalizedAutoTranslatePolicy>): void;
+export {};

package/dist/server/modules/auto-translate/AutoTranslateEnqueue.hook.js

@@ -0,0 +1,94 @@
+import { hasSourceContentChanged } from "../../../core/auto-translate";
+import { AUTO_TRANSLATE_CUSTOM_KEY } from "../../../core/auto-translate-config";
+import { AUTO_TRANSLATE_SKIP_CONTEXT_KEY } from "../../../types/AutoTranslateContext";
+import { buildAutoTranslateTasks, passesPublishGate } from "./AutoTranslate.policy";
+/**
+ * Build the `afterChange` hook that auto-enqueues translations when a document's source-locale content
+ * changes. Thin orchestration only — every decision lives in `AutoTranslate.policy.ts` or the core
+ * drift predicate. Best-effort by contract: any failure is logged and swallowed, never failing the
+ * editor's save.
+ *
+ * Order (cheap guards first): (1) skip the translator's own writes via the `req.context` flag;
+ * (2) resolve the policy — off ⇒ skip; (3) resolve the source locale (per-collection override else
+ * `localization.defaultLocale`) — unresolved ⇒ log + skip; (4) skip non-source-locale writes (the
+ * pipeline's target writes never match); (5) publish-gate (D8); (6) drift-gate (D3); then enqueue one
+ * job per target locale.
+ */ export function makeAutoTranslateHook(deps) {
+    const { resolvePolicy, schemaMap, taskRunnerFactory } = deps;
+    const hook = async ({ doc, previousDoc, req, collection })=>{
+        try {
+            if (req.context?.[AUTO_TRANSLATE_SKIP_CONTEXT_KEY]) return doc;
+            const policy = resolvePolicy(collection.slug, doc);
+            if (!policy) return doc;
+            const localization = req.payload.config.localization;
+            const sourceLocale = policy.sourceLocale ?? (localization ? localization.defaultLocale : undefined);
+            if (!sourceLocale) {
+                req.payload.logger.warn({
+                    collection: collection.slug,
+                    documentId: String(doc.id),
+                    msg: "translator: auto-translate skipped — no source locale resolvable (set localization.defaultLocale or a per-collection sourceLocale)"
+                });
+                return doc;
+            }
+            if (req.locale !== sourceLocale) return doc;
+            const hasDrafts = Boolean(collection.versions && collection.versions.drafts);
+            if (!passesPublishGate(doc, hasDrafts)) return doc;
+            const schema = schemaMap.get(collection.slug);
+            if (schema && !hasSourceContentChanged(previousDoc, doc, schema)) return doc;
+            const tasks = buildAutoTranslateTasks({
+                policy,
+                collectionSlug: collection.slug,
+                documentId: String(doc.id),
+                sourceLocale,
+                doc,
+                hasDrafts,
+                now: Date.now()
+            });
+            if (tasks.length === 0) return doc;
+            await taskRunnerFactory.create(req.payload).enqueue(tasks);
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                collection: collection.slug,
+                documentId: String(doc.id),
+                msg: "translator: auto-translate hook failed"
+            });
+        }
+        return doc;
+    };
+    hook.__translatorAutoTranslate = true;
+    return hook;
+}
+/**
+ * Attach the auto-translate hook to every enabled collection on `config`, appending to any
+ * consumer-supplied `afterChange` array. Idempotent: a collection that already carries the marked hook
+ * is skipped, so a repeated `init()` never stacks duplicates.
+ */ export function injectAutoTranslateHook(config, enabledSlugs, hook) {
+    for (const collection of config.collections ?? []){
+        if (!enabledSlugs.has(collection.slug)) continue;
+        collection.hooks ??= {};
+        collection.hooks.afterChange ??= [];
+        const alreadyInjected = collection.hooks.afterChange.some((existing)=>existing.__translatorAutoTranslate === true);
+        if (!alreadyInjected) collection.hooks.afterChange.push(hook);
+    }
+}
+/**
+ * Propagate each enabled collection's resolved policy onto the REGISTERED collection's `custom` bag, so
+ * the admin UI can read the opt-in back via `getAutoTranslateConfig`. This is required because
+ * `withAutoTranslate` stamps `custom` on the object passed to the plugin's `collections` param, which
+ * can be a DIFFERENT object than the one registered in `buildConfig.collections` (the reader would
+ * otherwise see no config and the indicator would disagree with the behaviour). Idempotent + additive:
+ * re-stamping the same value is a no-op and the behaviour wiring still reads from the plugin param.
+ */ export function propagateAutoTranslateCustom(config, enabledSlugs, policies) {
+    for (const collection of config.collections ?? []){
+        if (!enabledSlugs.has(collection.slug)) continue;
+        const policy = policies.get(collection.slug);
+        if (!policy) continue;
+        collection.custom = {
+            ...collection.custom ?? {},
+            [AUTO_TRANSLATE_CUSTOM_KEY]: policy
+        };
+    }
+}
+
+//# sourceMappingURL=AutoTranslateEnqueue.hook.js.map

package/dist/server/modules/auto-translate/index.d.ts

@@ -0,0 +1,4 @@
+export { configureAutoTranslate } from "./AutoTranslate.wiring";
+export type { AutoTranslateModule } from "./AutoTranslate.wiring";
+export { makeAutoTranslateHook, injectAutoTranslateHook } from "./AutoTranslateEnqueue.hook";
+export type { AutoTranslatePolicyResolver, NormalizedAutoTranslatePolicy, } from "./AutoTranslate.policy";

package/dist/server/modules/auto-translate/index.js

@@ -0,0 +1,7 @@
+// Auto-translate adapter (Payload-backed). The payload-free drift predicate + config reader live in
+// the core (src/core/auto-translate*, src/core/content-projection); this module is the config-time
+// wiring + the afterChange hook that enqueues translations on a source-locale change (#51).
+export { configureAutoTranslate } from "./AutoTranslate.wiring";
+export { makeAutoTranslateHook, injectAutoTranslateHook } from "./AutoTranslateEnqueue.hook";
+
+//# sourceMappingURL=index.js.map

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

@@ -31,6 +31,10 @@ const documentLocaleKey = (collectionId, targetLng)=>`${String(collectionId)}:${
         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,

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

@@ -23,6 +23,13 @@ export type TaskInput = {
     targetLng: string;
     strategy: "overwrite" | "skip_existing";
     publishOnTranslation: boolean;
+    /**
+     * Optional scheduled-run time (debounce). When set, the job runs no earlier than this instant;
+     * omitted/`undefined` = run as soon as the runner picks it up (every existing caller). Honored by
+     * the Payload Jobs runner via `payload.jobs.queue({ waitUntil })`; the sync (dev) runner ignores it
+     * and runs immediately.
+     */
+    waitUntil?: Date;
 };
 /**
  * Normalized task representation

package/dist/types/AutoTranslateContext.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The `req.context` flag the translator sets on its OWN document writes so the auto-translate
+ * `afterChange` hook skips them — the loop guard's second barrier (#51 D5). A single exported constant
+ * shared by the setter (`TranslateDocumentHandler.saveTranslatedDocument`) and the reader (the
+ * auto-translate hook), so the set-side and honor-side keys can never diverge.
+ *
+ * Lives in `types/` (a leaf contract) so both `server/features/translate-document` and
+ * `server/modules/auto-translate` import it without creating a cross-module edge.
+ */
+export declare const AUTO_TRANSLATE_SKIP_CONTEXT_KEY = "translatorSkipAutoTranslate";

package/dist/types/AutoTranslateContext.js

@@ -0,0 +1,11 @@
+/**
+ * The `req.context` flag the translator sets on its OWN document writes so the auto-translate
+ * `afterChange` hook skips them — the loop guard's second barrier (#51 D5). A single exported constant
+ * shared by the setter (`TranslateDocumentHandler.saveTranslatedDocument`) and the reader (the
+ * auto-translate hook), so the set-side and honor-side keys can never diverge.
+ *
+ * Lives in `types/` (a leaf contract) so both `server/features/translate-document` and
+ * `server/modules/auto-translate` import it without creating a cross-module edge.
+ */ export const AUTO_TRANSLATE_SKIP_CONTEXT_KEY = "translatorSkipAutoTranslate";
+
+//# sourceMappingURL=AutoTranslateContext.js.map

package/package.json

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