@focus-reactive/payload-plugin-translator 0.10.3 → 0.11.0

package/README.md

@@ -288,21 +288,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 +379,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 +481,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/core/domain/locales/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Namespace re-export: callers `import { Locales }` and use `Locales.dedupe(...)`,
+ * `Locales.resolveTargets(...)`, etc. Grouped this way (rather than loose named exports) so the domain
+ * reads at the call site; `export * as` keeps each member individually tree-shakeable.
+ */
+export * as Locales from "./resolveLocales";

package/dist/core/domain/locales/index.js

@@ -0,0 +1,7 @@
+/**
+ * Namespace re-export: callers `import { Locales }` and use `Locales.dedupe(...)`,
+ * `Locales.resolveTargets(...)`, etc. Grouped this way (rather than loose named exports) so the domain
+ * reads at the call site; `export * as` keeps each member individually tree-shakeable.
+ */ export * as Locales from "./resolveLocales";
+
+//# sourceMappingURL=index.js.map

package/dist/core/domain/locales/resolveLocales.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The single, canonical home for the locale-set invariants shared by every enqueue path: dedup,
+ * unknown-locale dropping, and source-locale exclusion. Previously each was hand-written in 2–3 places
+ * (the manual `/enqueue` resolver, the auto-translate config-time filter, and the auto-translate runtime
+ * task builder), which risked silent drift if one copy changed. These are the primitives; each path
+ * composes the ones it needs at whatever phase it runs (manual: one shot at request time; auto: dedup +
+ * unknown-drop at config time, source-exclusion per-document at runtime).
+ *
+ * Consumed as a namespace — the barrel re-exports this module as `Locales`, so call sites read
+ * `Locales.dedupe(...)` / `Locales.resolveTargets(...)`. Members are named for that dotted form (no
+ * `Locales` suffix), since the namespace carries the domain.
+ *
+ * Payload-free (plain `string[]` / `Set<string>`), so it stays a pure kernel usable from both the
+ * server features and the auto-translate module without pulling framework types in. Not part of the
+ * plugin's public API — an implementation detail of the enqueue paths.
+ *
+ * @internal
+ */
+/** Whether a single locale code is one of the configured locales. The atomic "is this known?" check
+ * that {@link dropUnknown} is built on — shared so "unknown locale" means one thing everywhere. */
+export declare function isKnown(locale: string, known: Set<string>): boolean;
+/** Remove duplicate locale codes, preserving first-seen order. */
+export declare function dedupe(locales: string[]): string[];
+/** Split a locale list into those that are configured (`kept`) and those that are not (`dropped`),
+ * preserving order within each. */
+export declare function dropUnknown(locales: string[], known: Set<string>): {
+    kept: string[];
+    dropped: string[];
+};
+/** Remove the source locale from a target list; report whether it was present (so the caller can note
+ * it was excluded). */
+export declare function excludeSource(targets: string[], source: string): {
+    kept: string[];
+    wasPresent: boolean;
+};
+/**
+ * Resolved target locales for a manual enqueue, plus what was dropped so the handler can log precisely.
+ */
+export type ResolvedTargets = {
+    /** The concrete locales to fan out to — de-duplicated, source excluded, unknown removed. */
+    targets: string[];
+    /** Requested locales that are not configured (dropped). */
+    droppedUnknown: string[];
+    /** Whether the source locale was requested as a target and excluded. */
+    droppedSource: boolean;
+};
+/**
+ * One-shot resolution for the manual enqueue path: coerce scalar→array, then dedup → exclude source →
+ * drop unknown, in that order. A pure composition of the primitives above.
+ *
+ * @param knownLocales - the configured locale codes. Never null: the caller must reject a
+ *   localization-less config before reaching here (translating without localization has no valid target
+ *   and would corrupt data), so "no localization" is not representable as an input.
+ */
+export declare function resolveTargets(args: {
+    target_lng: string | string[];
+    source_lng: string;
+    knownLocales: Set<string>;
+}): ResolvedTargets;

package/dist/core/domain/locales/resolveLocales.js

@@ -0,0 +1,68 @@
+/**
+ * The single, canonical home for the locale-set invariants shared by every enqueue path: dedup,
+ * unknown-locale dropping, and source-locale exclusion. Previously each was hand-written in 2–3 places
+ * (the manual `/enqueue` resolver, the auto-translate config-time filter, and the auto-translate runtime
+ * task builder), which risked silent drift if one copy changed. These are the primitives; each path
+ * composes the ones it needs at whatever phase it runs (manual: one shot at request time; auto: dedup +
+ * unknown-drop at config time, source-exclusion per-document at runtime).
+ *
+ * Consumed as a namespace — the barrel re-exports this module as `Locales`, so call sites read
+ * `Locales.dedupe(...)` / `Locales.resolveTargets(...)`. Members are named for that dotted form (no
+ * `Locales` suffix), since the namespace carries the domain.
+ *
+ * Payload-free (plain `string[]` / `Set<string>`), so it stays a pure kernel usable from both the
+ * server features and the auto-translate module without pulling framework types in. Not part of the
+ * plugin's public API — an implementation detail of the enqueue paths.
+ *
+ * @internal
+ */ /** Whether a single locale code is one of the configured locales. The atomic "is this known?" check
+ * that {@link dropUnknown} is built on — shared so "unknown locale" means one thing everywhere. */ export function isKnown(locale, known) {
+    return known.has(locale);
+}
+/** Remove duplicate locale codes, preserving first-seen order. */ export function dedupe(locales) {
+    return [
+        ...new Set(locales)
+    ];
+}
+/** Split a locale list into those that are configured (`kept`) and those that are not (`dropped`),
+ * preserving order within each. */ export function dropUnknown(locales, known) {
+    const kept = [];
+    const dropped = [];
+    for (const locale of locales){
+        (isKnown(locale, known) ? kept : dropped).push(locale);
+    }
+    return {
+        kept,
+        dropped
+    };
+}
+/** Remove the source locale from a target list; report whether it was present (so the caller can note
+ * it was excluded). */ export function excludeSource(targets, source) {
+    const kept = targets.filter((target)=>target !== source);
+    return {
+        kept,
+        wasPresent: kept.length !== targets.length
+    };
+}
+/**
+ * One-shot resolution for the manual enqueue path: coerce scalar→array, then dedup → exclude source →
+ * drop unknown, in that order. A pure composition of the primitives above.
+ *
+ * @param knownLocales - the configured locale codes. Never null: the caller must reject a
+ *   localization-less config before reaching here (translating without localization has no valid target
+ *   and would corrupt data), so "no localization" is not representable as an input.
+ */ export function resolveTargets(args) {
+    const { target_lng, source_lng, knownLocales } = args;
+    const requested = Array.isArray(target_lng) ? target_lng : [
+        target_lng
+    ];
+    const { kept: withoutSource, wasPresent: droppedSource } = excludeSource(dedupe(requested), source_lng);
+    const { kept: targets, dropped: droppedUnknown } = dropUnknown(withoutSource, knownLocales);
+    return {
+        targets,
+        droppedUnknown,
+        droppedSource
+    };
+}
+
+//# sourceMappingURL=resolveLocales.js.map

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/enqueue-translation/handler.js

@@ -1,8 +1,8 @@
 import { ServerResponse } from "../../shared";
 import { extractLocaleCodes } from "../../modules/auto-translate";
 import { isCollectionAvailable, getAllCollectionIds } from "../_lib/collection-utils";
+import { Locales } from "../../../core/domain/locales";
 import { EnqueueInputSchema } from "./model";
-import { resolveTargetLocales } from "./resolveTargetLocales";
 /**
  * Enqueues translation tasks for documents
  */ export class EnqueueTranslationHandler {
@@ -26,7 +26,7 @@ import { resolveTargetLocales } from "./resolveTargetLocales";
         if (!knownLocales) return ServerResponse.badRequest("Localization is not enabled in this Payload config; there are no target locales to translate into");
         // Normalize the scalar-or-array target into the concrete locales to fan out to: de-dup, exclude the
         // source, and drop locales that are not configured.
-        const { targets, droppedUnknown } = resolveTargetLocales({
+        const { targets, droppedUnknown } = Locales.resolveTargets({
             target_lng,
             source_lng,
             knownLocales

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

@@ -1,10 +1,9 @@
+import { Locales } from "../../../core/domain/locales";
 /** Apply defaults to a raw config: strategy → "overwrite", debounce → 0. Duplicate target locales are
  * de-duplicated so a misconfigured `targets: ["de","de"]` never enqueues two racing jobs for the same
  * (document, locale) in one batch (the runner's supersession only dedupes against already-stored jobs). */ export function normalizeAutoTranslateConfig(config) {
     return {
-        targets: [
-            ...new Set(config.targets)
-        ],
+        targets: Locales.dedupe(config.targets),
         strategy: config.strategy ?? "overwrite",
         debounceMs: config.debounceMs ?? 0,
         sourceLocale: config.sourceLocale
@@ -20,15 +19,15 @@
  * either error at the DB (Postgres locale enum) or write orphaned, invisible data (Mongo/SQLite). Pure:
  * returns a new policy and reports the drops; the caller (config-time wiring) emits the warning.
  */ export function filterPolicyToKnownLocales(policy, knownLocales) {
-    const droppedTargets = policy.targets.filter((target)=>!knownLocales.has(target));
-    const sourceUnknown = policy.sourceLocale !== undefined && !knownLocales.has(policy.sourceLocale);
+    const { kept, dropped } = Locales.dropUnknown(policy.targets, knownLocales);
+    const sourceUnknown = policy.sourceLocale !== undefined && !Locales.isKnown(policy.sourceLocale, knownLocales);
     return {
         policy: {
             ...policy,
-            targets: policy.targets.filter((target)=>knownLocales.has(target)),
+            targets: kept,
             sourceLocale: sourceUnknown ? undefined : policy.sourceLocale
         },
-        droppedTargets,
+        droppedTargets: dropped,
         droppedSourceLocale: sourceUnknown ? policy.sourceLocale ?? null : null
     };
 }
@@ -63,7 +62,7 @@
     const { policy, collectionSlug, documentId, sourceLocale, doc, hasDrafts, now } = args;
     const publishOnTranslation = resolvePublishOnTranslation(doc, hasDrafts);
     const waitUntil = policy.debounceMs > 0 ? new Date(now + policy.debounceMs) : undefined;
-    return policy.targets.filter((target)=>target !== sourceLocale).map((target)=>({
+    return Locales.excludeSource(policy.targets, sourceLocale).kept.map((target)=>({
             collectionSlug,
             collectionId: documentId,
             sourceLng: sourceLocale,

package/dist/translation-providers/index.d.ts

@@ -1,2 +1,3 @@
 export type { TranslationProvider, TranslationInput, TranslationOutput, } from "../core/domain/translation-providers";
+export * from "./shared";
 export * from "./openai";

package/dist/translation-providers/index.js

@@ -1,10 +1,4 @@
-// Translation-provider implementations (adapters), one directory per vendor. Payload-free and
-// opt-in — each vendor pulls its own deps (e.g. `openai`). Kept OUT of the framework-agnostic core
-// so the core stays dependency-free; the PORT they implement lives in the core and is re-exported
-// here for convenience. Naming is explicit ("translation-providers") to leave room for other kinds
-// of providers later without a collision.
-// The port (contract) — source of truth is the core.
-// Vendor implementations.
+export * from "./shared";
 export * from "./openai";
 
 //# sourceMappingURL=index.js.map

package/dist/translation-providers/openai/OpenAI.shapes.d.ts

@@ -0,0 +1,52 @@
+export type OpenAIChatMessage = {
+    role: "system" | "user";
+    content: string;
+};
+/**
+ * `schema` is `Record<string, unknown>`, not `unknown`: a widened field is not assignable to the
+ * SDK's closed union and OpenAI.shapes.test.ts stops compiling.
+ */
+export type OpenAIResponseFormat = {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        strict?: boolean;
+        schema: Record<string, unknown>;
+    };
+};
+export type OpenAIChatParams = {
+    model: string;
+    messages: OpenAIChatMessage[];
+    response_format?: OpenAIResponseFormat;
+    temperature?: number;
+    top_p?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+};
+export type OpenAIChatResult = {
+    choices: Array<{
+        message?: {
+            content?: string | null;
+        };
+    }>;
+};
+export type OpenAIRequestOptions = {
+    signal?: AbortSignal;
+};
+/**
+ * Any client with a `chat.completions.create` of this shape.
+ *
+ * Method syntax, not a property with a function type: property syntax is checked contravariantly
+ * under strictFunctionTypes and the real SDK's overloaded `create` stops being assignable.
+ *
+ * @since 0.11.0
+ */
+export type OpenAIClientShape = {
+    chat: {
+        completions: {
+            create(params: OpenAIChatParams, options?: OpenAIRequestOptions): Promise<OpenAIChatResult>;
+        };
+    };
+};

package/dist/translation-providers/openai/OpenAI.shapes.js

@@ -0,0 +1,13 @@
+// Never import from `openai` here, in any position: an SDK type would enter this package's emitted
+// declarations and force every consumer to install the SDK to type-check. Chat Completions rather
+// than the Responses API — that is what Azure, OpenRouter and LiteLLM gateways implement.
+/**
+ * Any client with a `chat.completions.create` of this shape.
+ *
+ * Method syntax, not a property with a function type: property syntax is checked contravariantly
+ * under strictFunctionTypes and the real SDK's overloaded `create` stops being assignable.
+ *
+ * @since 0.11.0
+ */ export { };
+
+//# sourceMappingURL=OpenAI.shapes.js.map