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

package/dist/translation-providers/shared/CompletionProvider.provider.d.ts

@@ -0,0 +1,65 @@
+import type { TranslationProvider } from "../../core/domain/translation-providers";
+import type { JsonSchemaObject } from "./buildResponseSchema";
+import type { SystemPromptBuilder } from "./buildSystemPrompt";
+import type { DryRunConfig } from "./runDryRun";
+/**
+ * Everything a transport needs in order to make one translation request.
+ *
+ * @since 0.11.0
+ */
+export type CompletionRequest = {
+    /** Already includes any `systemPrompt` override — send it verbatim, do not rebuild it. */
+    systemPrompt: string;
+    /** The user message: the input serialized as JSON. */
+    userContent: string;
+    /** A JSON Schema requiring exactly the input's keys. Feed it to the service's structured-output mechanism. */
+    responseSchema: JsonSchemaObject;
+    /** Reserved: the port carries no cancellation yet, so this is always `undefined` today. */
+    signal?: AbortSignal;
+};
+/**
+ * Sends one translation request and returns the service's reply as **raw text**.
+ *
+ * Returning text rather than a parsed object is deliberate: parsing and key-set validation stay on
+ * this side of the boundary, so a provider built on this factory cannot accidentally skip them.
+ *
+ * @since 0.11.0
+ */
+export type CompletionFn = (request: CompletionRequest) => Promise<string>;
+/**
+ * Configuration for {@link createTranslationProvider}.
+ *
+ * @since 0.11.0
+ */
+export type TranslationProviderConfig = {
+    complete: CompletionFn;
+    systemPrompt?: SystemPromptBuilder;
+    /**
+     * Simulate translations without calling anything. `true` reverses the text; an object supplies a
+     * transformer and an optional delay.
+     *
+     * @deprecated Supply your own fake `complete` instead. Remove in next major.
+     * See docs/DEPRECATIONS.md#provider-dry-run
+     */
+    dryRun?: boolean | DryRunConfig;
+};
+/**
+ * Builds a complete {@link TranslationProvider} from a single request function.
+ *
+ * Use it when you need a service this package does not ship an adapter for, or when you need full
+ * control of the request body. For OpenAI, `openAIComplete({ client, model })` is a ready-made
+ * `complete` — construct the client yourself.
+ *
+ * @example
+ * ```ts
+ * const provider = createTranslationProvider({
+ *   complete: async ({ systemPrompt, userContent, responseSchema }) => {
+ *     const reply = await myService.chat({ systemPrompt, userContent, schema: responseSchema })
+ *     return reply.text
+ *   },
+ * })
+ * ```
+ *
+ * @since 0.11.0
+ */
+export declare function createTranslationProvider(config: TranslationProviderConfig): TranslationProvider;

package/dist/translation-providers/shared/CompletionProvider.provider.js

@@ -0,0 +1,93 @@
+import { buildResponseSchema } from "./buildResponseSchema";
+import { buildSystemPrompt } from "./buildSystemPrompt";
+import { NoContentError, ProviderConfigurationError, wrapTransportError } from "./errors";
+import { parseAndValidateReply } from "./parseAndValidateReply";
+import { runDryRun } from "./runDryRun";
+const MAX_LOGGED_REPLY_KEYS = 10;
+/** Keys are model output: quoting them stops a newline inside a key from forging log entries. */ function describeReplyKeys(keys) {
+    const shown = keys.slice(0, MAX_LOGGED_REPLY_KEYS).map((key)=>JSON.stringify(key));
+    const rest = keys.length - shown.length;
+    return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
+}
+function warnAboutPartialReply(missingInputKeys, unrequestedReplyKeys) {
+    const lead = missingInputKeys.length > 0 ? `The provider's reply did not cover every field. Untranslated indices: ${missingInputKeys.join(", ")}.` : "The provider's reply carried keys that were not requested.";
+    const extra = unrequestedReplyKeys.length > 0 ? ` Unexpected keys ignored: ${describeReplyKeys(unrequestedReplyKeys)}.` : "";
+    console.warn(`[payload-plugin-translator] ${lead}${extra}`);
+}
+async function asConfigurationFailure(what, run) {
+    try {
+        return await run();
+    } catch (cause) {
+        throw new ProviderConfigurationError(`The ${what} threw. See this error's \`cause\`.`, {
+            cause
+        });
+    }
+}
+/** Only the consumer's transform is wrapped — our own loop must not report its bugs as configuration failures. */ function guardTransformer(dryRun) {
+    if (typeof dryRun !== "object" || !dryRun.transform) return dryRun;
+    const { transform } = dryRun;
+    return {
+        ...dryRun,
+        transform: (text)=>asConfigurationFailure("dry-run transformer", ()=>transform(text))
+    };
+}
+/**
+ * Builds a complete {@link TranslationProvider} from a single request function.
+ *
+ * Use it when you need a service this package does not ship an adapter for, or when you need full
+ * control of the request body. For OpenAI, `openAIComplete({ client, model })` is a ready-made
+ * `complete` — construct the client yourself.
+ *
+ * @example
+ * ```ts
+ * const provider = createTranslationProvider({
+ *   complete: async ({ systemPrompt, userContent, responseSchema }) => {
+ *     const reply = await myService.chat({ systemPrompt, userContent, schema: responseSchema })
+ *     return reply.text
+ *   },
+ * })
+ * ```
+ *
+ * @since 0.11.0
+ */ export function createTranslationProvider(config) {
+    const { complete, systemPrompt, dryRun } = config;
+    if (dryRun) {
+        const guarded = guardTransformer(dryRun);
+        return {
+            translate: (input)=>runDryRun(input, guarded)
+        };
+    }
+    return {
+        async translate (input, sourceLng, targetLng) {
+            // A strict response schema with no properties is rejected by the service, so an empty
+            // document must not reach the transport at all.
+            if (Object.keys(input).length === 0) return {};
+            const systemPromptText = await asConfigurationFailure("systemPrompt builder", ()=>buildSystemPrompt({
+                    sourceLng,
+                    targetLng,
+                    override: systemPrompt
+                }));
+            const request = await asConfigurationFailure("serialization of the input", ()=>({
+                    systemPrompt: systemPromptText,
+                    userContent: JSON.stringify(input),
+                    responseSchema: buildResponseSchema(input)
+                }));
+            let raw;
+            try {
+                raw = await complete(request);
+            } catch (cause) {
+                throw wrapTransportError(cause);
+            }
+            if (!raw) {
+                throw new NoContentError("The provider returned an empty reply.");
+            }
+            const { translations, missingInputKeys, unrequestedReplyKeys } = parseAndValidateReply(input, raw);
+            if (missingInputKeys.length > 0 || unrequestedReplyKeys.length > 0) {
+                warnAboutPartialReply(missingInputKeys, unrequestedReplyKeys);
+            }
+            return translations;
+        }
+    };
+}
+
+//# sourceMappingURL=CompletionProvider.provider.js.map

package/dist/translation-providers/shared/buildResponseSchema.d.ts

@@ -0,0 +1,13 @@
+import type { TranslationInput } from "../../core/domain/translation-providers";
+/**
+ * A JSON Schema document, as a plain object — deliberately untyped beyond that, so it can be dropped
+ * into any vendor's response-format envelope.
+ *
+ * @since 0.11.0
+ */
+export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * Builds the response schema for a translation request: exactly the input's keys, all required, no
+ * extras.
+ */
+export declare function buildResponseSchema(input: TranslationInput): JsonSchemaObject;

package/dist/translation-providers/shared/buildResponseSchema.js

@@ -0,0 +1,22 @@
+/**
+ * Builds the response schema for a translation request: exactly the input's keys, all required, no
+ * extras.
+ */ export function buildResponseSchema(input) {
+    const keys = Object.keys(input);
+    const properties = {};
+    for (const key of keys){
+        properties[key] = {
+            type: "string"
+        };
+    }
+    // Strict structured-output modes reject a schema unless every property is listed in `required`
+    // and extras are forbidden.
+    return {
+        type: "object",
+        properties,
+        required: keys,
+        additionalProperties: false
+    };
+}
+
+//# sourceMappingURL=buildResponseSchema.js.map

package/dist/translation-providers/shared/buildSystemPrompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Context handed to a {@link SystemPromptBuilder}.
+ *
+ * @since 0.11.0
+ */
+export type SystemPromptContext = {
+    /** Source language code (e.g. 'en', 'de'). Empty when the provider should auto-detect. */
+    sourceLang: string;
+    targetLang: string;
+    defaultPrompt: string;
+};
+/**
+ * Builds a custom system prompt for translation.
+ *
+ * @since 0.11.0
+ */
+export type SystemPromptBuilder = (context: SystemPromptContext) => string;
+/**
+ * Produces the system prompt sent with a translation request.
+ *
+ * The default wording is handed to `systemPrompt` builders as `defaultPrompt`, so consumers extend
+ * this exact string — changing it changes every custom prompt built on it.
+ */
+export declare function buildSystemPrompt(args: {
+    sourceLng: string;
+    targetLng: string;
+    override?: SystemPromptBuilder;
+}): string;

package/dist/translation-providers/shared/buildSystemPrompt.js

@@ -0,0 +1,25 @@
+/**
+ * Context handed to a {@link SystemPromptBuilder}.
+ *
+ * @since 0.11.0
+ */ /**
+ * Produces the system prompt sent with a translation request.
+ *
+ * The default wording is handed to `systemPrompt` builders as `defaultPrompt`, so consumers extend
+ * this exact string — changing it changes every custom prompt built on it.
+ */ export function buildSystemPrompt(args) {
+    const { sourceLng, targetLng, override } = args;
+    const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLng ? ` from ${sourceLng}` : ""} into ${targetLng}. Keep all JSON keys exactly as they are, only translate the values.
+The response should be a valid JSON object with the same structure and keys as the input, but with translated values.
+Maintain any special formatting, placeholders, or variables within the values if they exist.`;
+    if (override) {
+        return override({
+            sourceLang: sourceLng,
+            targetLang: targetLng,
+            defaultPrompt
+        });
+    }
+    return defaultPrompt;
+}
+
+//# sourceMappingURL=buildSystemPrompt.js.map

package/dist/translation-providers/shared/errors/KeySetMismatchError.d.ts

@@ -0,0 +1,15 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Nothing in the reply could be applied — either its keys did not overlap the input's, or they did
+ * and none of the values was a string. A partial gap is not an error; see `parseAndValidateReply`.
+ *
+ * @since 0.11.0
+ */
+export declare class KeySetMismatchError extends TranslationProviderError {
+    readonly code: "key-set-mismatch";
+    /** Input keys left without a usable translation. */
+    readonly missingInputKeys: number[];
+    /** Keys the reply carried but nobody asked for — model output, so untrusted text. */
+    readonly unrequestedReplyKeys: string[];
+    constructor(message: string, missingInputKeys: number[], unrequestedReplyKeys: string[], options?: ErrorOptions);
+}

package/dist/translation-providers/shared/errors/KeySetMismatchError.js

@@ -0,0 +1,26 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Nothing in the reply could be applied — either its keys did not overlap the input's, or they did
+ * and none of the values was a string. A partial gap is not an error; see `parseAndValidateReply`.
+ *
+ * @since 0.11.0
+ */ export class KeySetMismatchError extends TranslationProviderError {
+    code = "key-set-mismatch";
+    /** Input keys left without a usable translation. */ missingInputKeys;
+    /** Keys the reply carried but nobody asked for — model output, so untrusted text. */ unrequestedReplyKeys;
+    constructor(message, missingInputKeys, unrequestedReplyKeys, options){
+        super(message, options);
+        this.missingInputKeys = missingInputKeys;
+        this.unrequestedReplyKeys = unrequestedReplyKeys;
+        // Model-invented strings: enumerable, they would land in `JSON.stringify(error)` and every
+        // structured logger.
+        Object.defineProperty(this, "missingInputKeys", {
+            enumerable: false
+        });
+        Object.defineProperty(this, "unrequestedReplyKeys", {
+            enumerable: false
+        });
+    }
+}
+
+//# sourceMappingURL=KeySetMismatchError.js.map

package/dist/translation-providers/shared/errors/NoContentError.d.ts

@@ -0,0 +1,9 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider produced no usable text — an empty reply, or a response the vendor filtered.
+ *
+ * @since 0.11.0
+ */
+export declare class NoContentError extends TranslationProviderError {
+    readonly code: "no-content";
+}

package/dist/translation-providers/shared/errors/NoContentError.js

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider produced no usable text — an empty reply, or a response the vendor filtered.
+ *
+ * @since 0.11.0
+ */ export class NoContentError extends TranslationProviderError {
+    code = "no-content";
+}
+
+//# sourceMappingURL=NoContentError.js.map

package/dist/translation-providers/shared/errors/ProviderConfigurationError.d.ts

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider is configured in a way that cannot work — most often an optional SDK that is not
+ * installed.
+ *
+ * @since 0.11.0
+ */
+export declare class ProviderConfigurationError extends TranslationProviderError {
+    readonly code: "config";
+}

package/dist/translation-providers/shared/errors/ProviderConfigurationError.js

@@ -0,0 +1,11 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider is configured in a way that cannot work — most often an optional SDK that is not
+ * installed.
+ *
+ * @since 0.11.0
+ */ export class ProviderConfigurationError extends TranslationProviderError {
+    code = "config";
+}
+
+//# sourceMappingURL=ProviderConfigurationError.js.map

package/dist/translation-providers/shared/errors/TranslationProviderError.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Failure causes a translation provider can report.
+ *
+ * @since 0.11.0
+ */
+export type TranslationFailureCode = "no-content" | "unparseable-reply" | "key-set-mismatch" | "transport" | "config";
+/**
+ * Base class for every failure a built-in translation provider reports.
+ *
+ * The original failure travels on `cause` and is never interpolated into `message`: a vendor SDK
+ * error can carry an API key, and `message` reaches an HTTP response body.
+ *
+ * @since 0.11.0
+ */
+export declare abstract class TranslationProviderError extends Error {
+    abstract readonly code: TranslationFailureCode;
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/translation-providers/shared/errors/TranslationProviderError.js

@@ -0,0 +1,21 @@
+/**
+ * Failure causes a translation provider can report.
+ *
+ * @since 0.11.0
+ */ /**
+ * Base class for every failure a built-in translation provider reports.
+ *
+ * The original failure travels on `cause` and is never interpolated into `message`: a vendor SDK
+ * error can carry an API key, and `message` reaches an HTTP response body.
+ *
+ * @since 0.11.0
+ */ export class TranslationProviderError extends Error {
+    constructor(message, options){
+        // Never `this.cause = cause`: an assigned property is enumerable, so JSON.stringify and pino
+        // serialize the vendor error whole — headers and API key with it. `super` installs it non-enumerably.
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+
+//# sourceMappingURL=TranslationProviderError.js.map

package/dist/translation-providers/shared/errors/TransportError.d.ts

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The call to the provider failed — network, auth, rate limit, timeout. The vendor's own error is on
+ * `cause`.
+ *
+ * @since 0.11.0
+ */
+export declare class TransportError extends TranslationProviderError {
+    readonly code: "transport";
+}

package/dist/translation-providers/shared/errors/TransportError.js

@@ -0,0 +1,11 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The call to the provider failed — network, auth, rate limit, timeout. The vendor's own error is on
+ * `cause`.
+ *
+ * @since 0.11.0
+ */ export class TransportError extends TranslationProviderError {
+    code = "transport";
+}
+
+//# sourceMappingURL=TransportError.js.map

package/dist/translation-providers/shared/errors/UnparseableReplyError.d.ts

@@ -0,0 +1,9 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The reply was not JSON, or parsed to something that is not an object — arrays included.
+ *
+ * @since 0.11.0
+ */
+export declare class UnparseableReplyError extends TranslationProviderError {
+    readonly code: "unparseable-reply";
+}

package/dist/translation-providers/shared/errors/UnparseableReplyError.js

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The reply was not JSON, or parsed to something that is not an object — arrays included.
+ *
+ * @since 0.11.0
+ */ export class UnparseableReplyError extends TranslationProviderError {
+    code = "unparseable-reply";
+}
+
+//# sourceMappingURL=UnparseableReplyError.js.map

package/dist/translation-providers/shared/errors/errorMessageLower.d.ts

@@ -0,0 +1 @@
+export declare function errorMessageLower(cause: unknown): string | null;

package/dist/translation-providers/shared/errors/errorMessageLower.js

@@ -0,0 +1,8 @@
+import { isObject } from "../../../core/kernel/utils/isObject";
+export function errorMessageLower(cause) {
+    if (!isObject(cause)) return null;
+    const message = cause.message;
+    return typeof message === "string" ? message.toLowerCase() : null;
+}
+
+//# sourceMappingURL=errorMessageLower.js.map

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

@@ -0,0 +1,9 @@
+export { TranslationProviderError } from "./TranslationProviderError";
+export type { TranslationFailureCode } from "./TranslationProviderError";
+export { NoContentError } from "./NoContentError";
+export { UnparseableReplyError } from "./UnparseableReplyError";
+export { KeySetMismatchError } from "./KeySetMismatchError";
+export { TransportError } from "./TransportError";
+export { ProviderConfigurationError } from "./ProviderConfigurationError";
+export { wrapTransportError } from "./wrapTransportError";
+export { errorMessageLower } from "./errorMessageLower";

package/dist/translation-providers/shared/errors/index.js

@@ -0,0 +1,10 @@
+export { TranslationProviderError } from "./TranslationProviderError";
+export { NoContentError } from "./NoContentError";
+export { UnparseableReplyError } from "./UnparseableReplyError";
+export { KeySetMismatchError } from "./KeySetMismatchError";
+export { TransportError } from "./TransportError";
+export { ProviderConfigurationError } from "./ProviderConfigurationError";
+export { wrapTransportError } from "./wrapTransportError";
+export { errorMessageLower } from "./errorMessageLower";
+
+//# sourceMappingURL=index.js.map

package/dist/translation-providers/shared/errors/wrapTransportError.d.ts

@@ -0,0 +1,7 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Turns anything a transport threw into a {@link TransportError}, keeping the original on `cause`.
+ * A value that is already one of ours passes through: re-wrapping would bury a specific cause under
+ * a generic transport failure.
+ */
+export declare function wrapTransportError(cause: unknown): TranslationProviderError;

package/dist/translation-providers/shared/errors/wrapTransportError.js

@@ -0,0 +1,14 @@
+import { TransportError } from "./TransportError";
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Turns anything a transport threw into a {@link TransportError}, keeping the original on `cause`.
+ * A value that is already one of ours passes through: re-wrapping would bury a specific cause under
+ * a generic transport failure.
+ */ export function wrapTransportError(cause) {
+    if (cause instanceof TranslationProviderError) return cause;
+    return new TransportError("The translation request failed before a reply could be read. The provider's own error is on this error's `cause` property.", {
+        cause
+    });
+}
+
+//# sourceMappingURL=wrapTransportError.js.map

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

@@ -0,0 +1,8 @@
+export { createTranslationProvider } from "./CompletionProvider.provider";
+export type { CompletionFn, CompletionRequest, TranslationProviderConfig, } from "./CompletionProvider.provider";
+export type { JsonSchemaObject } from "./buildResponseSchema";
+export type { SystemPromptBuilder, SystemPromptContext } from "./buildSystemPrompt";
+export type { DryRunConfig, DryRunTransformer } from "./runDryRun";
+export { errorMessageLower } from "./errors";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError, } from "./errors";
+export type { TranslationFailureCode } from "./errors";

package/dist/translation-providers/shared/index.js

@@ -0,0 +1,5 @@
+export { createTranslationProvider } from "./CompletionProvider.provider";
+export { errorMessageLower } from "./errors";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError } from "./errors";
+
+//# sourceMappingURL=index.js.map

package/dist/translation-providers/shared/parseAndValidateReply.d.ts

@@ -0,0 +1,13 @@
+import type { TranslationInput, TranslationOutput } from "../../core/domain/translation-providers";
+export type ParsedReply = {
+    translations: TranslationOutput;
+    missingInputKeys: number[];
+    unrequestedReplyKeys: string[];
+};
+/**
+ * Parses an untrusted reply into a {@link TranslationOutput} and reports the key-set gap.
+ *
+ * A partial answer is applied, not rejected — the gap is returned so the caller can report it. Only
+ * a reply that answers nothing is a failure ({@link KeySetMismatchError}).
+ */
+export declare function parseAndValidateReply(input: TranslationInput, raw: string): ParsedReply;

package/dist/translation-providers/shared/parseAndValidateReply.js

@@ -0,0 +1,46 @@
+import { isObject } from "../../core/kernel/utils/isObject";
+import { KeySetMismatchError, UnparseableReplyError } from "./errors";
+/**
+ * Parses an untrusted reply into a {@link TranslationOutput} and reports the key-set gap.
+ *
+ * A partial answer is applied, not rejected — the gap is returned so the caller can report it. Only
+ * a reply that answers nothing is a failure ({@link KeySetMismatchError}).
+ */ export function parseAndValidateReply(input, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (cause) {
+        throw new UnparseableReplyError("The provider's reply was not valid JSON.", {
+            cause
+        });
+    }
+    // `isObject` admits arrays: `["a"]` has key "0", so a 0-based input would accept it by coincidence.
+    if (!isObject(parsed) || Array.isArray(parsed)) {
+        throw new UnparseableReplyError("The provider's reply was JSON, but not an object.");
+    }
+    const expectedKeys = new Set(Object.keys(input));
+    const translations = {};
+    const missingInputKeys = [];
+    for (const key of expectedKeys){
+        const value = parsed[key];
+        if (typeof value === "string") {
+            translations[Number(key)] = value;
+        } else {
+            missingInputKeys.push(Number(key));
+        }
+    }
+    const unrequestedReplyKeys = Object.keys(parsed).filter((key)=>!expectedKeys.has(key));
+    if (expectedKeys.size > 0 && Object.keys(translations).length === 0) {
+        const answeredAnyKey = [
+            ...expectedKeys
+        ].some((key)=>Object.hasOwn(parsed, key));
+        throw new KeySetMismatchError(answeredAnyKey ? `The provider's reply carried the requested keys, but none of the ${expectedKeys.size} values was a string.` : `The provider's reply answered none of the ${expectedKeys.size} requested keys.`, missingInputKeys, unrequestedReplyKeys);
+    }
+    return {
+        translations,
+        missingInputKeys,
+        unrequestedReplyKeys
+    };
+}
+
+//# sourceMappingURL=parseAndValidateReply.js.map

package/dist/translation-providers/shared/runDryRun.d.ts

@@ -0,0 +1,20 @@
+import type { TranslationInput, TranslationOutput } from "../../core/domain/translation-providers";
+export type DryRunTransformer = (text: string) => string | Promise<string>;
+/**
+ * Dry-run configuration: a transformer, and optionally a delay that imitates network latency.
+ *
+ * @deprecated Supply your own fake `complete` instead. Remove in next major.
+ * See docs/DEPRECATIONS.md#provider-dry-run
+ */
+export type DryRunConfig = {
+    /** Applied to every non-blank value. */
+    transform: DryRunTransformer;
+    /** Milliseconds to wait before returning. */
+    timeout?: number;
+};
+/**
+ * Simulates a translation without calling anything. Blank values pass through untouched.
+ *
+ * Logs the field count and never field content: the log reaches shared infrastructure.
+ */
+export declare function runDryRun(input: TranslationInput, config: boolean | DryRunConfig): Promise<TranslationOutput>;

package/dist/translation-providers/shared/runDryRun.js

@@ -0,0 +1,17 @@
+const reverse = (text)=>text.split("").reverse().join("");
+/**
+ * Simulates a translation without calling anything. Blank values pass through untouched.
+ *
+ * Logs the field count and never field content: the log reaches shared infrastructure.
+ */ export async function runDryRun(input, config) {
+    console.info(`[payload-plugin-translator] Dry run: simulated ${Object.keys(input).length} field(s), no API call made.`);
+    const { transform = reverse, timeout = 0 } = typeof config === "object" ? config : {};
+    if (timeout > 0) await new Promise((resolve)=>setTimeout(resolve, timeout));
+    const output = {};
+    for (const [key, value] of Object.entries(input)){
+        output[Number(key)] = value.trim() ? await transform(value) : value;
+    }
+    return output;
+}
+
+//# sourceMappingURL=runDryRun.js.map

package/package.json

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

package/dist/server/features/enqueue-translation/resolveTargetLocales.d.ts

@@ -1,30 +0,0 @@
-/**
- * Resolved target locales for a manual enqueue, plus what was dropped so the handler can log precisely.
- */
-export type ResolvedTargetLocales = {
-    /** 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;
-};
-/**
- * Normalize the enqueue `target_lng` input (scalar or array) into the concrete list of target locales
- * to translate into. Applies, in order: array-coercion, de-duplication (first-seen order preserved),
- * source-locale exclusion, and dropping unknown (unconfigured) locales.
- *
- * De-dup and unknown-dropping are the manual-enqueue counterparts of the auto-translate policy filter:
- * the runner only supersedes against already-stored jobs, so duplicates within one enqueue must be
- * collapsed here; and an unknown locale must never reach the pipeline — it burns a provider call and
- * either errors on a Postgres locale enum or writes orphaned, invisible data on Mongo/SQLite.
- *
- * @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 resolveTargetLocales(args: {
-    target_lng: string | string[];
-    source_lng: string;
-    knownLocales: Set<string>;
-}): ResolvedTargetLocales;