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

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/domain/auto-translate";
+export type { AutoTranslateConfig };
+export type { AutoTranslateStrategy } from "./core/domain/auto-translate";
+/**
+ * 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/domain/auto-translate";
+/**
+ * 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/domain/auto-translate";
+/**
+ * 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/domain/auto-translate/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/domain/auto-translate/getAutoTranslateConfig.js

@@ -0,0 +1,29 @@
+import { isObject } from "../../kernel/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/domain/auto-translate/hasSourceContentChanged.d.ts

@@ -0,0 +1,21 @@
+import type { FieldLike } from "../../kernel/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/domain/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/domain/auto-translate/index.d.ts

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

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

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

package/dist/core/domain/auto-translate/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/domain/auto-translate/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/core/{content-projection → domain/content-projection}/computeSourceFingerprint.d.ts

@@ -1,4 +1,4 @@
-import type { FieldLike } from "../field-traversal";
+import type { FieldLike } from "../../kernel/field-traversal";
 /**
  * The staleness baseline: a stable hash of a document's translatable content.
  * `CURRENT = computeSourceFingerprint(sourceDoc, schema)` — the value provenance stores at translation