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

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, 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();
@@ -27,15 +27,15 @@ const TranslateDocument = ({ hasDrafts })=>{
     ]);
     // The panel trigger shows one aggregate marker; the popup shows the full per-locale list.
     const panelStatus = useMemo(()=>derivePanelStatus({
-            runStatus: data?.status,
+            runStatus: deriveDocumentRunStatus(data),
             staleLocales
         }), [
-        data?.status,
+        data,
         staleLocales
     ]);
     const statusRows = useMemo(()=>buildTranslationStatusRows({
             staleness,
-            run: data
+            runs: data
         }), [
         staleness,
         data
@@ -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/get-document-status/handler.js

@@ -1,6 +1,6 @@
 import { ServerResponse } from "../../shared";
 import { isCollectionAvailable } from "../_lib/collection-utils";
-import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from "./model";
+import { GetDocumentStatusInputSchema, latestTaskPerTargetLocale, taskToJobStatusOutput } from "./model";
 /**
  * Gets the translation status for a specific document
  */ export class GetDocumentStatusHandler {
@@ -20,7 +20,9 @@ import { GetDocumentStatusInputSchema, taskToJobStatusOutput } from "./model";
         const tasks = await runner.findByCollection(collectionSlug, [
             collection_id
         ]);
-        return ServerResponse.success(tasks[0] ? taskToJobStatusOutput(tasks[0]) : null);
+        // One job per target locale (latest), not a single job for the whole document — re-translate
+        // queues an independent job per locale, and the status panel renders a row per locale.
+        return ServerResponse.success(latestTaskPerTargetLocale(tasks).map(taskToJobStatusOutput));
     }
 }
 

package/dist/server/features/get-document-status/model.d.ts

@@ -56,6 +56,16 @@ export type JobStatusOutput = {
 export type GetDocumentStatusConfig = {
     availableCollections: Set<CollectionSlug>;
 };
+/**
+ * Reduce a document's jobs to the latest one per target locale.
+ *
+ * `findByCollection` returns every job for the document across all target locales (plus any superseded
+ * jobs not yet cancelled). The status panel shows one row per target locale, so we keep — per
+ * `targetLng` — the most recently created job (tie-break: most recently updated). Without this the
+ * caller sees a single arbitrary job and every other in-flight locale looks idle, which is the
+ * concurrent re-translate bug (a second re-translate appearing to overwrite the first's status).
+ */
+export declare function latestTaskPerTargetLocale(tasks: Task[]): Task[];
 /**
  * Transforms a Task to API output format (snake_case for client compatibility)
  */

package/dist/server/features/get-document-status/model.js

@@ -10,6 +10,27 @@ import { JobIdSchema, toClientErrorMessage } from "../../shared";
     collection_id: JobIdSchema,
     collection_slug: z.string().nonempty()
 });
+// A job is "newer" by creation time, tie-broken by last update — both ISO-8601, so a lexicographic
+// string compare is a correct chronological compare (no Date parsing needed).
+const isNewerTask = (candidate, current)=>candidate.createdAt !== current.createdAt ? candidate.createdAt > current.createdAt : candidate.updatedAt > current.updatedAt;
+/**
+ * Reduce a document's jobs to the latest one per target locale.
+ *
+ * `findByCollection` returns every job for the document across all target locales (plus any superseded
+ * jobs not yet cancelled). The status panel shows one row per target locale, so we keep — per
+ * `targetLng` — the most recently created job (tie-break: most recently updated). Without this the
+ * caller sees a single arbitrary job and every other in-flight locale looks idle, which is the
+ * concurrent re-translate bug (a second re-translate appearing to overwrite the first's status).
+ */ export function latestTaskPerTargetLocale(tasks) {
+    const byLocale = new Map();
+    for (const task of tasks){
+        const current = byLocale.get(task.input.targetLng);
+        if (!current || isNewerTask(task, current)) byLocale.set(task.input.targetLng, task);
+    }
+    return [
+        ...byLocale.values()
+    ];
+}
 /**
  * Transforms a Task to API output format (snake_case for client compatibility)
  */ export function taskToJobStatusOutput(task) {

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[];