@focus-reactive/payload-plugin-translator 0.10.4 → 0.11.1

package/README.md

@@ -205,6 +205,45 @@ translatorPlugin({
 });
 ```
 
+### Drafts and publishing
+
+Applies to every way a translation is triggered — the admin controls, `POST /translate/enqueue`, and
+auto-translate. It matters most if your collections have `versions.drafts` enabled.
+
+**Without publish-on-translation**, the translation is written as a **draft version**. The document's
+published state is left alone: a live page stays live, an unpublished one stays unpublished, and the
+translated locale does not appear on the public site until someone publishes it.
+
+**With publish-on-translation**, the translation is written as a draft and the target locale is then
+published — a separate step, so it happens whether or not any field actually needed translating.
+Only the locale that was translated is published; other locales keep whatever state they were in.
+Translating a document that is not currently published does make the document live, with just that
+locale's content in it.
+
+A translation is taken from **the source locale's own current content** — the newer draft when one
+exists, else the published row, never a value Payload substitutes from another locale. Translating
+*from* a locale you have not filled in therefore translates nothing.
+
+Two consequences worth knowing before you rely on them:
+
+- **Publishing publishes the current draft, whatever is in it.** A translation is based on the
+  version the editor sees, and publishing puts that live — including pending edits nobody made for
+  the translation's sake, and including non-localized fields, which Payload stores once per document
+  and so cannot scope to a locale. That is what the flag asks for, but it is worth remembering
+  before running "translate and publish" over a long list of documents: every unpublished draft
+  among them goes live.
+- **`skip_existing` counts anything non-empty as translated.** A translation waiting unpublished in
+  a draft counts, so a reviewer's corrected text is published as it stands rather than
+  re-translated. It has no notion of *reviewed*, and it does not consult stale-detection — a locale
+  the admin marks out of date is still skipped
+  ([#118](https://github.com/focusreactive/payload-plugins/issues/118)).
+
+> **Changed in 0.11.1.** Before this, translating one locale as a draft unpublished the document in
+> every locale, and translating one locale with publishing pushed every other locale's unpublished
+> draft live ([#102](https://github.com/focusreactive/payload-plugins/issues/102)). The source was
+> also read from the published row with fallbacks, so translating from an empty locale translated
+> the default locale's text.
+
 ### Stale-translation detection
 
 _Since v0.8.0._
@@ -221,6 +260,10 @@ 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.
 
+> **Upgrading to 0.11.1.** Records written earlier fingerprinted the source differently, so a locale
+> can read out of date once after upgrading with nothing actually needing re-translation. Dismissing
+> the marker or re-translating settles it.
+
 ### Auto-translate on source change
 
 _Since v0.9.0._
@@ -249,9 +292,12 @@ translatorPlugin({
 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
+with the source document's status, scoped to **only the translated locale**; never re-triggers on its
 own translation writes; and never fails the editor's save (best-effort — failures are logged).
 
+> See [Drafts and publishing](#drafts-and-publishing) for what a translation does to a document's
+> published state.
+
 > **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
@@ -288,21 +334,86 @@ translatorPlugin({
 
 #### OpenAI (built in) — `createOpenAIProvider(config)`
 
-| Property       | Type                      | Required | Default              | Description                                                                                                     |
-| -------------- | ------------------------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `apiKey`       | `string`                  | Yes      | —                    | OpenAI API key.                                                                                                 |
-| `model`        | `string \| ChatModel`     | No       | `'gpt-4o'`           | Model used for translation.                                                                                     |
-| `systemPrompt` | `SystemPromptBuilder`     | No       | Built-in prompt      | Custom system-prompt builder.                                                                                   |
-| `dryRun`       | `boolean \| DryRunConfig` | No       | `false`              | Simulate translations without API calls.                                                                        |
-| `timeout`      | `number`                  | No       | SDK default (10 min) | Per-request timeout (ms). A job blocks on this call, so the 10-min default is usually too long. _Since v0.6.0._ |
-| `maxRetries`   | `number`                  | No       | SDK default (2)      | Max automatic retries on transient errors (429/5xx/network). `0` disables. _Since v0.6.0._                      |
+Pass **either** an `apiKey` **or** a ready-made `client` — never both; the types enforce it.
+
+| Property       | Type                      | Required           | Default              | Description                                                                                                     |
+| -------------- | ------------------------- | ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `apiKey`       | `string`                  | Unless `client`    | —                    | OpenAI API key. The `openai` package is loaded on first translation, not at config load. _Since v0.11.0: optional when `client` is given._ |
+| `client`       | `OpenAIClientShape`       | Unless `apiKey`    | —                    | Your own client — Azure OpenAI, a corporate proxy, OpenRouter, anything with a matching `chat.completions.create`. On this path the `openai` package is never loaded. _Since v0.11.0._ |
+| `model`        | `string`                  | No                 | `'gpt-4o'`           | Model used for translation. **The default may change in a minor release** — pin it if you need reproducible output and cost. |
+| `systemPrompt` | `SystemPromptBuilder`     | No                 | Built-in prompt      | Custom system-prompt builder.                                                                                   |
+| `dryRun`       | `boolean \| DryRunConfig` | No                 | `false`              | **Deprecated** — see the note below. Simulates translations without API calls, but still writes, publishes and records provenance. |
+| `sampling`     | `OpenAISamplingParams`    | No                 | not sent             | `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`. Omitted entirely unless set — several models reject them. **Before v0.11.0 this package always sent `temperature: 0, top_p: 1, frequency_penalty: 0, presence_penalty: 0`**, so translations were deterministic; they now follow the model's defaults. Set `{ temperature: 0 }` to restore that. _Since v0.11.0._ |
+| `structuredOutput` | `"json_schema" \| "json_object"` | No | `"json_schema"` | Which structured-output envelope to send. See the note below — the two carry different risks. _Since v0.11.0._ |
+| `timeout`      | `number`                  | No                 | `60000`              | Per-request timeout (ms) for the client this package builds. Ignored when you pass your own `client`. _Since v0.6.0; the default dropped from the SDK's 10 minutes to 60 s in v0.11.0._ |
+| `maxRetries`   | `number`                  | No                 | SDK default (2)      | Max automatic retries on transient errors (429/5xx/network) for the client this package builds. `0` disables. Ignored when you pass your own `client`. _Since v0.6.0._ |
+
+> **`createOpenAIProvider` is deprecated and goes away in the next major.** What it adds over
+> `openAIComplete` is building the SDK client for you — and carrying `openai` as an optional
+> dependency of ours to do it, which is where the cost is: a lazy import shaped around deployment
+> file-tracers, and a classifier telling "not installed" from "installed but broken" across four
+> runtimes. Construct the client yourself instead and keep everything else:
+>
+> ```typescript
+> import OpenAI from "openai";
+> import {
+>   createTranslationProvider,
+>   openAIComplete,
+> } from "@focus-reactive/payload-plugin-translator";
+>
+> // The SDK's own default timeout is ten minutes — far too long for a live edit.
+> const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, timeout: 60_000 });
+>
+> const translationProvider = createTranslationProvider({
+>   complete: openAIComplete({ client, model: "gpt-4o" }),
+> });
+> ```
+>
+> `openAIComplete` stays: the request body, the `structuredOutput` choice below, and the message
+> naming that option when a gateway rejects a strict schema are all still ours. What becomes yours
+> is the SDK version and the client's own settings, the timeout most of all.
+> See [docs/DEPRECATIONS.md](docs/DEPRECATIONS.md#openai-client-construction).
+
+#### Choosing a structured-output envelope
+
+`json_schema` (the default) sends the request with a schema the reply must satisfy, so a compliant
+model **cannot** drop a requested field. That is what closed the silent half-translation defect. It
+costs two things:
+
+- Older models, and some gateways (OpenRouter with certain upstream models, older Azure
+  deployments, self-hosted proxies), reject it with a 400. You do not need to know which: the error
+  names this option as the fix.
+- The schema has a size limit, so **one request carries a limited number of pieces of text**, and a
+  document past that ceiling fails as a whole. The schema names one property per translatable piece,
+  and rich text is split one piece per text node — a sentence with two emphasised spans is already
+  four pieces — so the count grows faster than "one per field" suggests, and a document is never
+  split across requests. The ceiling differs by model and moves over time; measure it against your
+  largest documents rather than assuming headroom.
+
+`json_object` asks only for valid JSON. There is no schema, so no ceiling — but key preservation
+falls back to this package's key-set check, which **detects** a dropped key instead of preventing
+it. A reply missing one key out of two hundred still writes the other 199, the gap is reported to
+the server log, and only a reply matching nothing at all fails. Your editors never see that log, so
+a dropped field looks translated in the admin UI.
+
+Pick by which risk you would rather carry: a hard failure on very large documents, or a quiet gap on
+any document.
 
 ```typescript
+// Quick start
 createOpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY,
   model: "gpt-4o-mini",
   systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) => `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
 });
+
+// Your own client — Azure, a proxy, OpenRouter. Since v0.11.0.
+import OpenAI from "openai";
+
+createOpenAIProvider({
+  client: new OpenAI({ apiKey: process.env.AZURE_KEY, baseURL: process.env.AZURE_ENDPOINT }),
+  model: "gpt-4o",
+});
 ```
 
 `systemPrompt` receives `{ sourceLang, targetLang, defaultPrompt }` and returns the prompt string. When `dryRun` is an object it can transform text locally with an optional delay:
@@ -314,6 +425,81 @@ type DryRunConfig = {
 };
 ```
 
+> **`dryRun` is deprecated and will be removed in the next major.** It skips the network call and
+> nothing else: the transformed strings are still written to the target locale, still published when
+> `publishOnTranslation` is set, and still recorded as provenance — after which the locale reads as
+> up to date and no re-translation is prompted. Use your own fake instead, which is explicit about
+> being one:
+>
+> ```typescript
+> import { createTranslationProvider } from "@focus-reactive/payload-plugin-translator";
+>
+> const fakeProvider = createTranslationProvider({
+>   complete: async ({ userContent }) => {
+>     const input = JSON.parse(userContent) as Record<string, string>;
+>     const reversed: Record<string, string> = {};
+>     for (const [key, value] of Object.entries(input)) {
+>       reversed[key] = value.trim() ? [...value].reverse().join("") : value;
+>     }
+>     return JSON.stringify(reversed);
+>   },
+> });
+> ```
+>
+> `complete` returns the reply as raw text, exactly as a service would; parsing and validation stay
+> on our side. See [docs/DEPRECATIONS.md](docs/DEPRECATIONS.md#provider-dry-run).
+
+#### Another service — `createTranslationProvider(config)`
+
+_Since v0.11.0._
+
+Need a different model provider, or full control of the request body? Supply one function — "send this text, give me the reply" — and keep everything else. The prompt, the response schema, reply parsing, key-set validation, dry-run simulation and the failure taxonomy all stay on our side, so you cannot accidentally skip them.
+
+For OpenAI specifically you do not have to write that function: `openAIComplete({ client, model })` is one, built from a client you constructed. _Since v0.11.0._
+
+```typescript
+import { createTranslationProvider } from "@focus-reactive/payload-plugin-translator";
+
+const provider = createTranslationProvider({
+  complete: async ({ systemPrompt, userContent, responseSchema }) => {
+    const reply = await myService.chat({
+      system: systemPrompt,
+      user: userContent,
+      schema: responseSchema, // hand this to whatever structured-output mechanism your service offers
+    });
+    return reply.text; // raw text, not a parsed object — we parse it
+  },
+});
+```
+
+> `signal` is reserved and currently always `undefined` — the port does not carry cancellation yet, so wiring it into your client is harmless but has no effect today. It is in the request shape so that adding cancellation later is a pure addition rather than a breaking change.
+
+| Property       | Type                      | Required | Default         | Description                                        |
+| -------------- | ------------------------- | -------- | --------------- | -------------------------------------------------- |
+| `complete`     | `CompletionFn`            | Yes      | —               | Sends one request, returns the reply as raw text.  |
+| `systemPrompt` | `SystemPromptBuilder`     | No       | Built-in prompt | Custom system-prompt builder.                      |
+| `dryRun`       | `boolean \| DryRunConfig` | No       | `false`         | **Deprecated** — supply your own fake `complete`.  |
+
+Your `complete` owns the timeout, the retry policy and the credentials — this package adds no retry of its own and imposes no timeout on your call.
+
+#### Failure causes
+
+_Since v0.11.0._
+
+Every built-in provider throws a typed error naming what went wrong, instead of returning `null`:
+
+| Error                       | `code`               | Means                                                                  |
+| --------------------------- | -------------------- | ---------------------------------------------------------------------- |
+| `NoContentError`            | `no-content`         | The reply was empty, or the service filtered it.                       |
+| `UnparseableReplyError`     | `unparseable-reply`  | The reply was not JSON, or not an object.                              |
+| `KeySetMismatchError`       | `key-set-mismatch`   | The reply answered none of the requested fields.                       |
+| `TransportError`            | `transport`          | The call failed — network, auth, rate limit, timeout.                  |
+| `ProviderConfigurationError`| `config`             | The provider cannot work as configured (usually a missing optional SDK). |
+
+All extend `TranslationProviderError`, so one `catch` covers them. The original failure is on the standard `cause` property — never copied into `message`, because that text can reach an HTTP response body and a vendor error may carry your API key.
+
+A **partial** reply is not an error: the fields that came back are applied, and the ones that did not are named in a warning. That is deliberate — dropping good translations because one field is missing helps nobody — but it does mean a partial translation still completes.
+
 #### Custom provider
 
 Implement the `TranslationProvider` interface — a single `translate` method:
@@ -341,8 +527,10 @@ class DeepLProvider implements TranslationProvider {
         result[key] = data.translations[i].text;
       });
       return result;
-    } catch {
-      return null; // null aborts the translation for this chunk
+    } catch (cause) {
+      // Throwing is preferred — the cause reaches the log and the editor sees why it failed.
+      // Returning `null` still works and still aborts the whole run, but it says nothing about why.
+      throw new Error("DeepL translation failed", { cause });
     }
   }
 }

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

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

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

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

package/dist/client/widgets/translate-field-control/ui/TranslateFieldControl.js

@@ -47,8 +47,11 @@ import styles from "./styles.module.scss";
     const { mutateAsync, isPending } = useTranslateField();
     // `config.localization` is `false | {…}`, so the truthy check is load-bearing (not just a nil guard).
     const defaultLocale = config.localization ? config.localization.defaultLocale : undefined;
+    // `useLocale()` is typed `Locale` but actually returns `false | {} | Locale` until the admin's
+    // locale provider resolves (see the V4 TODO on the hook in @payloadcms/ui), so `code` can be absent.
+    const targetCode = locale?.code ?? "";
     const [isOpen, popup] = useToggle();
-    const [sourceLng, setSourceLng] = useState(()=>defaultLocale && defaultLocale !== locale.code ? defaultLocale : "");
+    const [sourceLng, setSourceLng] = useState(()=>defaultLocale && defaultLocale !== targetCode ? defaultLocale : "");
     // `null` = no undo available; an object wraps the value so a legitimately `undefined` field value
     // (a real pre-translation state) stays distinguishable from "nothing to undo".
     const [undo, setUndo] = useState(null);
@@ -57,7 +60,7 @@ import styles from "./styles.module.scss";
     // once translating the unsaved value in place is supported.) All hooks above run unconditionally.
     if (id === undefined || id === null) return null;
     // Source options: every locale except the one being edited (it's the fixed target).
-    const sourceLocaleOptions = localeOptions.filter((option)=>option.value !== locale.code);
+    const sourceLocaleOptions = localeOptions.filter((option)=>option.value !== targetCode);
     const canTranslate = sourceLng !== "" && !isPending;
     // One write path for every supported field type: a form UPDATE bumping value AND initialValue.
     // A Lexical (richText) editor re-mounts on the initialValue change so it shows the new content;
@@ -79,7 +82,7 @@ import styles from "./styles.module.scss";
             const { data } = await mutateAsync({
                 collectionSlug,
                 fieldPath: path,
-                targetLng: locale.code,
+                targetLng: targetCode,
                 sourceLng,
                 docId: id
             });
@@ -132,7 +135,7 @@ import styles from "./styles.module.scss";
                 className: styles.row,
                 children: [
                     /*#__PURE__*/ _jsxs("div", {
-                        "aria-label": `Translation direction: from ${sourceLng || "a source locale"} into ${locale.code}`,
+                        "aria-label": `Translation direction: from ${sourceLng || "a source locale"} into ${targetCode}`,
                         className: styles.direction,
                         role: "group",
                         children: [
@@ -161,9 +164,9 @@ import styles from "./styles.module.scss";
                                 children: "→"
                             }),
                             /*#__PURE__*/ _jsx("span", {
-                                "aria-label": `Target locale: ${locale.code} (the locale you're editing)`,
+                                "aria-label": `Target locale: ${targetCode} (the locale you're editing)`,
                                 className: styles.current,
-                                children: locale.code.toLowerCase()
+                                children: targetCode.toLowerCase()
                             })
                         ]
                     }),
@@ -176,7 +179,7 @@ import styles from "./styles.module.scss";
                             $isIconButton: true,
                             $isLoading: isPending,
                             disabled: !canTranslate,
-                            "aria-label": `Translate from ${sourceLng || "the selected locale"} into ${locale.code}`,
+                            "aria-label": `Translate from ${sourceLng || "the selected locale"} into ${targetCode}`,
                             onClick: handleTranslate,
                             children: /*#__PURE__*/ _jsx(SendIcon, {})
                         })

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

@@ -30,9 +30,6 @@ const asObject = (value)=>isObject(value) ? value : {};
         this.strategy = strategy;
     }
     /** Collects translatable field chunks that need translation. */ collect() {
-        // The read walk SELECTS translatable leaves (via the shared selection core) and records, per
-        // selected leaf, the source value to translate plus its write target. The mutation is applied
-        // in a separate explicit pass below — read and write are no longer fused inside the walk.
         const selected = [];
         const chunks = [];
         const { strategy } = this;
@@ -119,8 +116,6 @@ const asObject = (value)=>isObject(value) ? value : {};
             target: this.targetData,
             path: []
         }, walker);
-        // Apply pass: write each selected leaf's source value into filteredData — this is what gets
-        // translated. Kept separate from the read walk above so selection stays read-only.
         for (const { dataRef, key, sourceValue } of selected){
             dataRef[key] = sourceValue;
         }

package/dist/index.d.ts

@@ -5,8 +5,12 @@ export type { TranslationTask, TranslationLifecycleCallbacks } from "./server/mo
 export type { TranslationProvenanceRecord } from "./core";
 export type { AccessGuard, AccessGuardRequest } from "./types/AccessGuard";
 export type { TranslationProvider, TranslationInput, TranslationOutput } from "./core";
-export { createOpenAIProvider } from "./translation-providers";
-export type { OpenAIProviderConfig, DryRunConfig } from "./translation-providers";
+export { openAIComplete } from "./translation-providers";
+export type { OpenAIClientShape, OpenAISamplingParams, OpenAIStructuredOutput, DryRunConfig, } from "./translation-providers";
+export { createTranslationProvider } from "./translation-providers";
+export type { CompletionFn, CompletionRequest, TranslationProviderConfig, JsonSchemaObject, SystemPromptBuilder, SystemPromptContext, } from "./translation-providers";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError, } from "./translation-providers";
+export type { TranslationFailureCode } from "./translation-providers";
 export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task-runner";
 export type { TaskRunnerProvider, PayloadJobsRunnerOptions } from "./server/modules/task-runner";
 export { documentLevel, collectionLevel, fieldLevel } from "./composition/levels";
@@ -17,6 +21,7 @@ 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";
+export { createOpenAIProvider, OpenAITranslationProvider } from "./translation-providers";
+export type { OpenAIProviderConfig } from "./translation-providers";
 export { translateKitField } from "./field-config";
 export type { TranslateKitFieldConfig } from "./field-config";

package/dist/index.js

@@ -1,7 +1,8 @@
 // Main plugin
 export { translatorPlugin } from "./plugin";
-// Built-in OpenAI provider (opt-in; pulls `openai`) — lives in the plugin's src/providers, outside core
-export { createOpenAIProvider } from "./translation-providers";
+export { openAIComplete } from "./translation-providers";
+export { createTranslationProvider } from "./translation-providers";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError } from "./translation-providers";
 // Task runners
 export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task-runner";
 // Translation levels
@@ -14,7 +15,7 @@ export { withFieldTranslation } from "./field-config";
 export { withAutoTranslate } from "./auto-translate-config";
 // Deprecated exports (for backwards compatibility)
 export { createTranslatePlugin, TranslateCollectionPlugin } from "./plugin";
-export { OpenAITranslationProvider } from "./translation-providers";
+export { createOpenAIProvider, OpenAITranslationProvider } from "./translation-providers";
 export { translateKitField } from "./field-config";
 
 //# sourceMappingURL=index.js.map

package/dist/server/features/translate-document/handler.d.ts

@@ -16,4 +16,5 @@ export declare class TranslateDocumentHandler implements Handler<TranslateDocume
     constructor(translationProvider: TranslationProvider, schemaMap: CollectionSchemaMap, provenanceServiceFactory?: ProvenanceServiceFactory);
     handle(payload: Payload, input: TranslateDocumentInput): Promise<TranslateDocumentOutput>;
     private saveTranslatedDocument;
+    private publishTargetLocale;
 }

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

@@ -2,6 +2,10 @@ 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";
+import { resolveTargetLayer } from "./targetLayer";
+/** Loop guard: the auto-translate afterChange hook (#51) skips writes carrying this key. */ const translatorWriteContext = ()=>({
+        [AUTO_TRANSLATE_SKIP_CONTEXT_KEY]: true
+    });
 /**
  * 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
@@ -17,71 +21,76 @@ import { AUTO_TRANSLATE_SKIP_CONTEXT_KEY } from "../../../types/AutoTranslateCon
     }
     async handle(payload, input) {
         const { collection, collectionId, sourceLng, targetLng, strategy, publishOnTranslation } = input;
-        // Get original schema (preserves localized: true on nested fields)
         const schema = this.schemaMap.get(collection);
         if (!schema) throw new APIError(`Collection "${collection}" not found in schemaMap`, 400);
-        const sourceData = await fetchSourceDocument(payload, collection, collectionId, sourceLng);
-        // Capture the staleness baseline from the PRISTINE source NOW, before the pipeline runs — it
-        // translates in place and shares object-valued source leaves (e.g. richText nodes) by reference,
-        // so fingerprinting after `translateContent` would hash the target translation and make every
-        // fresh translation look instantly stale. The service is best-effort (a failure returns null).
+        const layer = resolveTargetLayer({
+            versions: payload.collections[collection].config.versions,
+            targetLng
+        });
+        // `draft: true` is unconditional: on a collection without drafts Payload has no version to
+        // substitute, so it returns the only row. The WRITE cannot be so relaxed — the `no-drafts`
+        // layer omits `draft` entirely, because that is the argument shape `main` sent.
+        const [sourceData, currentTargetVersion] = await Promise.all([
+            fetchSourceDocument(payload, collection, collectionId, sourceLng),
+            payload.findByID({
+                collection,
+                id: collectionId,
+                locale: targetLng,
+                fallbackLocale: false,
+                depth: 0,
+                draft: true
+            })
+        ]);
         const provenance = this.provenanceServiceFactory?.(payload);
         const sourceFingerprint = provenance?.captureFingerprint(collection, sourceData) ?? null;
-        const targetData = await payload.findByID({
-            collection,
-            id: collectionId,
-            locale: targetLng,
-            fallbackLocale: false,
-            depth: 0
-        });
         const translatedData = await translateContent({
             schema,
             sourceData,
-            targetData,
+            targetData: currentTargetVersion,
             sourceLng,
             targetLng,
             translationProvider: this.translationProvider,
             strategy
         });
-        if (!translatedData) return {
-            success: true
-        };
-        const collectionConfig = payload.collections[collection].config;
-        await this.saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
-        if (provenance && sourceFingerprint !== null) {
-            await provenance.record({
-                collectionSlug: collection,
-                documentId: String(collectionId),
-                targetLocale: targetLng,
-                sourceLocale: sourceLng
-            }, sourceFingerprint);
+        if (translatedData) {
+            await this.saveTranslatedDocument(payload, input, translatedData, layer.write);
+            if (provenance && sourceFingerprint !== null) {
+                await provenance.record({
+                    collectionSlug: collection,
+                    documentId: String(collectionId),
+                    targetLocale: targetLng,
+                    sourceLocale: sourceLng
+                }, sourceFingerprint);
+            }
+        }
+        if (publishOnTranslation && layer.kind === "drafts") {
+            await this.publishTargetLocale(payload, input, layer.publish);
         }
         return {
             success: true
         };
     }
-    async saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation) {
-        let isAutosaveEnabled = false;
-        const versions = collectionConfig.versions;
-        if (versions && versions.drafts) {
-            translatedData["_status"] = publishOnTranslation ? "published" : "draft";
-            const drafts = versions.drafts;
-            if (!publishOnTranslation && drafts.autosave) isAutosaveEnabled = true;
-        }
+    async saveTranslatedDocument(payload, input, translatedData, write) {
         await payload.update({
-            collection: collection,
-            id: collectionId,
+            collection: input.collection,
+            id: input.collectionId,
             data: translatedData,
-            autosave: isAutosaveEnabled,
-            locale: targetLng,
-            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
-            }
+            ...write,
+            locale: input.targetLng,
+            fallbackLocale: input.sourceLng,
+            context: translatorWriteContext()
+        });
+    }
+    async publishTargetLocale(payload, input, publish) {
+        await payload.update({
+            collection: input.collection,
+            id: input.collectionId,
+            data: {
+                _status: publish.status
+            },
+            publishSpecificLocale: publish.publishSpecificLocale,
+            locale: publish.publishSpecificLocale,
+            context: translatorWriteContext()
         });
     }
 }

package/dist/server/features/translate-document/targetLayer.d.ts

@@ -0,0 +1,37 @@
+import type { CollectionConfig } from "payload";
+export type VersionsSlice = CollectionConfig["versions"];
+/** The arguments that publish one locale, once a collection is known to have a draft layer. */
+export type PublishScope = {
+    publishSpecificLocale: string;
+    /**
+     * Merged into the published write's data. Looks redundant beside `publishSpecificLocale`
+     * and is not: without it, any other locale holding a pending draft drags the whole
+     * document back to `draft` (#102).
+     */
+    status: "published";
+};
+/**
+ * Where a translation is written, and — separately — how the locale is published afterwards.
+ *
+ * A union, not one shape with optional fields: `publishSpecificLocale` on a collection with
+ * versions but no drafts drops every other locale from the live row (Payload 3.84.1, silent).
+ * `publish` exists only on the `drafts` variant, so that pair is unbuildable — see
+ * `targetLayer.contract.test.ts`.
+ */
+export type TargetLayer = {
+    kind: "no-drafts";
+    write: {
+        autosave: false;
+    };
+} | {
+    kind: "drafts";
+    write: {
+        draft: true;
+        autosave: boolean;
+    };
+    publish: PublishScope;
+};
+export declare function resolveTargetLayer(args: {
+    versions: VersionsSlice;
+    targetLng: string;
+}): TargetLayer;

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

@@ -0,0 +1,26 @@
+import { hasAutosaveEnabled, hasDraftsEnabled } from "payload/shared";
+export function resolveTargetLayer(args) {
+    const { versions, targetLng } = args;
+    const config = {
+        versions
+    };
+    if (!hasDraftsEnabled(config)) return {
+        kind: "no-drafts",
+        write: {
+            autosave: false
+        }
+    };
+    return {
+        kind: "drafts",
+        write: {
+            draft: true,
+            autosave: hasAutosaveEnabled(config)
+        },
+        publish: {
+            publishSpecificLocale: targetLng,
+            status: "published"
+        }
+    };
+}
+
+//# sourceMappingURL=targetLayer.js.map