@focus-reactive/payload-plugin-translator 0.5.0 → 0.6.0

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

@@ -0,0 +1,85 @@
+import { getByPath, ServerResponse } from "../../shared";
+import { translateContent } from "../../modules/translation-pipeline";
+import { FieldTranslationInputSchema, MAX_FIELD_VALUE_BYTES } from "./model";
+import { resolveFieldSubtree } from "./resolveFieldSubtree";
+const byteLength = (value)=>new TextEncoder().encode(JSON.stringify(value) ?? "").length;
+const noop = (value, level, message)=>({
+        status: "noop",
+        value,
+        notice: {
+            level,
+            message
+        }
+    });
+/**
+ * Synchronous single-field translation: read the field's value from the saved document in the
+ * chosen source locale, resolve the declared field path to its schema subtree, run
+ * `translateContent`, and return the translated value. No persistence — the result is written to
+ * form state by the caller.
+ *
+ * From-locale only: `source_lng` + `doc_id` are required (validated by the schema), so there is
+ * always exactly one DB read. Reserves HTTP errors for genuine errors — "nothing to translate"
+ * and "couldn't resolve the block" come back as a 200 `noop` with a notice.
+ */ export class TranslateFieldHandler {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async handle(req) {
+        const parsed = FieldTranslationInputSchema.safeParse(await req.json?.());
+        if (parsed.error) return ServerResponse.validationError(parsed.error.issues);
+        const { collection_slug, field_path, target_lng, source_lng, doc_id } = parsed.data;
+        const fields = this.config.schemaMap.get(collection_slug);
+        if (!fields) return ServerResponse.badRequest(`Collection "${collection_slug}" is not available for translation`);
+        // Read the source value from the saved document in `source_lng` (fallbackLocale: false so an
+        // empty source reads as empty → noop, not a fallback). The doc also lets the resolver
+        // disambiguate `blocks` — their `blockType` lives in the data.
+        const sourceDoc = await req.payload.findByID({
+            collection: collection_slug,
+            id: doc_id,
+            locale: source_lng,
+            fallbackLocale: false,
+            depth: 0
+        });
+        const sourceValue = getByPath(sourceDoc, field_path);
+        // Guard the *translated* payload (held synchronously through the provider call), not the
+        // request body, which now carries no field value.
+        if (byteLength(sourceValue) > MAX_FIELD_VALUE_BYTES) {
+            return ServerResponse.custom(`Field value exceeds the ${MAX_FIELD_VALUE_BYTES}-byte limit`, 413);
+        }
+        const resolution = resolveFieldSubtree(fields, field_path, sourceValue, sourceDoc);
+        if (resolution.status === "not-found") {
+            return ServerResponse.badRequest(`Field path "${field_path}" was not found in collection "${collection_slug}"`);
+        }
+        if (resolution.status === "inside-blocks") {
+            return ServerResponse.success(noop(sourceValue, "info", "Couldn't resolve the block for this field in the source document"));
+        }
+        if (resolution.status === "localized-list-ancestor") {
+            // Inside a localized blocks/array: its order/content is independent per locale, so the path
+            // index can't be matched to the source locale. Translate the whole document instead.
+            return ServerResponse.success(noop(sourceValue, "warning", "This field is inside a localized block — translate the whole document instead, so blocks stay aligned across locales"));
+        }
+        if (resolution.status === "not-translatable") {
+            return ServerResponse.success(noop(sourceValue, "info", "Nothing to translate in this field"));
+        }
+        // No `strategy`/`targetData`: a per-field translate is an explicit "translate this field now",
+        // so `translateContent` always overwrites (its default). skip_existing has no meaning here.
+        const translated = await translateContent({
+            schema: resolution.schema,
+            sourceData: resolution.sourceData,
+            sourceLng: source_lng,
+            targetLng: target_lng,
+            translationProvider: this.config.translationProvider
+        });
+        if (!translated) {
+            return ServerResponse.success(noop(sourceValue, "info", "Nothing to translate in this field"));
+        }
+        const result = {
+            status: "translated",
+            value: translated[resolution.fieldName]
+        };
+        return ServerResponse.success(result);
+    }
+}
+
+//# sourceMappingURL=handler.js.map

package/dist/server/features/translate-field/index.d.ts

@@ -0,0 +1,6 @@
+export { createFieldRoute } from "./route";
+export type { CreateFieldRouteArgs } from "./route";
+export { TranslateFieldHandler } from "./handler";
+export { resolveFieldSubtree } from "./resolveFieldSubtree";
+export type { FieldSubtreeResolution } from "./resolveFieldSubtree";
+export type { FieldTranslationConfig, FieldTranslationInput, FieldTranslationNotice, FieldTranslationResult } from "./model";

package/dist/server/features/translate-field/index.js

@@ -0,0 +1,5 @@
+export { createFieldRoute } from "./route";
+export { TranslateFieldHandler } from "./handler";
+export { resolveFieldSubtree } from "./resolveFieldSubtree";
+
+//# sourceMappingURL=index.js.map

package/dist/server/features/translate-field/model.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { CollectionSchemaMap } from "../translate-document";
+import type { TranslationProvider } from "../../modules/translation-providers";
+/**
+ * Max serialized size of the value the endpoint will translate — the value read from the
+ * source-locale document (the request body no longer carries one; this is from-locale only). The
+ * field endpoint is synchronous — it holds the request for the whole translation — so an unbounded
+ * payload is a DoS surface. 256 KiB comfortably covers a long `richText` document; still a guard,
+ * not yet configurable.
+ */
+export declare const MAX_FIELD_VALUE_BYTES: number;
+/**
+ * Request body for `POST {basePath}/field`. Snake_case to match the other translator routes.
+ *
+ * Single mode — **from locale**: the server reads the saved document (`doc_id`) in `source_lng`,
+ * takes its value at `field_path`, and translates it into `target_lng`. Both `source_lng` and
+ * `doc_id` are therefore required (a saved document). `doc_id` reuses {@link JobIdSchema} — the
+ * canonical id guard, ID-format-agnostic (string UUID/ObjectId or numeric autoincrement),
+ * normalized to a string.
+ */
+export declare const FieldTranslationInputSchema: z.ZodObject<{
+    collection_slug: z.ZodString;
+    field_path: z.ZodString;
+    target_lng: z.ZodString;
+    source_lng: z.ZodString;
+    doc_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
+}, "strip", z.ZodTypeAny, {
+    collection_slug: string;
+    source_lng: string;
+    target_lng: string;
+    field_path: string;
+    doc_id: string;
+}, {
+    collection_slug: string;
+    source_lng: string;
+    target_lng: string;
+    field_path: string;
+    doc_id: string | number;
+}>;
+export type FieldTranslationInput = z.infer<typeof FieldTranslationInputSchema>;
+/** Handler dependencies — the schema source of truth + the translation backend. */
+export type FieldTranslationConfig = {
+    schemaMap: CollectionSchemaMap;
+    translationProvider: TranslationProvider;
+};
+export type FieldTranslationNotice = {
+    level: "info" | "warning";
+    message: string;
+};
+/**
+ * Successful response. Never an error for "couldn't translate": a field with no
+ * localized content (or a path our resolver can't handle yet) is a `noop` with a
+ * calm notice, not an HTTP error.
+ */
+export type FieldTranslationResult = {
+    status: "translated";
+    value: unknown;
+} | {
+    status: "noop";
+    value: unknown;
+    notice: FieldTranslationNotice;
+};

package/dist/server/features/translate-field/model.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
+/**
+ * Max serialized size of the value the endpoint will translate — the value read from the
+ * source-locale document (the request body no longer carries one; this is from-locale only). The
+ * field endpoint is synchronous — it holds the request for the whole translation — so an unbounded
+ * payload is a DoS surface. 256 KiB comfortably covers a long `richText` document; still a guard,
+ * not yet configurable.
+ */ export const MAX_FIELD_VALUE_BYTES = 256 * 1024;
+/**
+ * Request body for `POST {basePath}/field`. Snake_case to match the other translator routes.
+ *
+ * Single mode — **from locale**: the server reads the saved document (`doc_id`) in `source_lng`,
+ * takes its value at `field_path`, and translates it into `target_lng`. Both `source_lng` and
+ * `doc_id` are therefore required (a saved document). `doc_id` reuses {@link JobIdSchema} — the
+ * canonical id guard, ID-format-agnostic (string UUID/ObjectId or numeric autoincrement),
+ * normalized to a string.
+ */ export const FieldTranslationInputSchema = z.object({
+    collection_slug: z.string().nonempty(),
+    field_path: z.string().nonempty(),
+    target_lng: z.string().nonempty(),
+    source_lng: z.string().nonempty(),
+    doc_id: JobIdSchema
+});
+
+//# sourceMappingURL=model.js.map

package/dist/server/features/translate-field/resolveFieldSubtree.d.ts

@@ -0,0 +1,39 @@
+import type { Field } from "payload";
+/**
+ * Outcome of mapping a declared field path to a translatable subtree.
+ *
+ * - `resolved` — the path lands on a translatable leaf; `schema` + `sourceData`
+ *   are ready for `translateContent`, and `fieldName` is the key to unwrap the result.
+ * - `not-found` — the path resolves to no field at all (a typo) → caller returns 400.
+ * - `not-translatable` — resolves to a field that isn't a text-like leaf → caller no-ops.
+ * - `inside-blocks` — the path descends through a polymorphic `blocks` field that couldn't be
+ *   resolved: no `doc` was supplied to read the element's `blockType` from → caller no-ops.
+ * - `localized-list-ancestor` — the path descends through a `localized` `blocks`/`array` field,
+ *   whose per-locale order/content is independent, so a positional path can't be matched across
+ *   locales → caller no-ops (translate the whole document instead).
+ */
+export type FieldSubtreeResolution = {
+    status: "resolved";
+    schema: Field[];
+    sourceData: Record<string, unknown>;
+    fieldName: string;
+} | {
+    status: "not-found";
+} | {
+    status: "not-translatable";
+} | {
+    status: "inside-blocks";
+} | {
+    status: "localized-list-ancestor";
+};
+/**
+ * Map a declared `fieldPath` to the `{ schema, sourceData }` pair `translateContent` expects.
+ * Walks the schema via the shared {@link findFieldByPath}. Descends transparently through
+ * presentational containers (row, collapsible, unnamed tabs) and through named group/array/tab
+ * containers; array element indices select the data item but not the schema (shared across items).
+ *
+ * Pass `doc` (the document the path belongs to) to descend through polymorphic `blocks` fields:
+ * the element's `blockType` in `doc` picks the block schema. Without `doc`, a path through a
+ * `blocks` field returns `inside-blocks`.
+ */
+export declare function resolveFieldSubtree(rootFields: Field[], fieldPath: string, value: unknown, doc?: unknown): FieldSubtreeResolution;

package/dist/server/features/translate-field/resolveFieldSubtree.js

@@ -0,0 +1,51 @@
+import { isTranslatableField } from "../../shared";
+import { findFieldByPath } from "../../shared/field-traversal";
+/**
+ * Map a declared `fieldPath` to the `{ schema, sourceData }` pair `translateContent` expects.
+ * Walks the schema via the shared {@link findFieldByPath}. Descends transparently through
+ * presentational containers (row, collapsible, unnamed tabs) and through named group/array/tab
+ * containers; array element indices select the data item but not the schema (shared across items).
+ *
+ * Pass `doc` (the document the path belongs to) to descend through polymorphic `blocks` fields:
+ * the element's `blockType` in `doc` picks the block schema. Without `doc`, a path through a
+ * `blocks` field returns `inside-blocks`.
+ */ export function resolveFieldSubtree(rootFields, fieldPath, value, doc) {
+    const segments = fieldPath.split(".").map((segment)=>segment.trim()).filter((segment)=>segment.length > 0);
+    if (segments.length === 0) return {
+        status: "not-found"
+    };
+    const result = findFieldByPath(rootFields, segments, doc);
+    switch(result.status){
+        case "leaf":
+            return isTranslatableField(result.field) ? {
+                status: "resolved",
+                schema: [
+                    result.field
+                ],
+                sourceData: {
+                    [result.field.name]: value
+                },
+                fieldName: result.field.name
+            } : {
+                status: "not-translatable"
+            };
+        case "container":
+            return {
+                status: "not-translatable"
+            };
+        case "inside-blocks":
+            return {
+                status: "inside-blocks"
+            };
+        case "localized-list-ancestor":
+            return {
+                status: "localized-list-ancestor"
+            };
+        case "not-found":
+            return {
+                status: "not-found"
+            };
+    }
+}
+
+//# sourceMappingURL=resolveFieldSubtree.js.map

package/dist/server/features/translate-field/route.d.ts

@@ -0,0 +1,12 @@
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { FieldTranslationConfig } from "./model";
+export type CreateFieldRouteArgs = FieldTranslationConfig & {
+    access?: AccessGuard;
+    basePath?: string;
+};
+/**
+ * Creates the synchronous field-translation endpoint: `POST {basePath}/field`.
+ * Wired with the same access + error-envelope plumbing as the document routes.
+ */
+export declare function createFieldRoute({ schemaMap, translationProvider, access, basePath }: CreateFieldRouteArgs): Endpoint;

package/dist/server/features/translate-field/route.js

@@ -0,0 +1,18 @@
+import { withAccessCheck, withErrorHandler } from "../../shared";
+import { TranslateFieldHandler } from "./handler";
+/**
+ * Creates the synchronous field-translation endpoint: `POST {basePath}/field`.
+ * Wired with the same access + error-envelope plumbing as the document routes.
+ */ export function createFieldRoute({ schemaMap, translationProvider, access, basePath = "/translate" }) {
+    const handler = new TranslateFieldHandler({
+        schemaMap,
+        translationProvider
+    });
+    return {
+        path: `${basePath}/field`,
+        method: "post",
+        handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
+    };
+}
+
+//# sourceMappingURL=route.js.map

package/dist/server/modules/translation-levels/PluginConfigBuilder.d.ts

@@ -1,6 +1,8 @@
 import type { CollectionConfig, Config, Endpoint } from "payload";
 import type { AccessGuard } from "../../../types/AccessGuard";
 import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { CollectionSchemaMap } from "../../features/translate-document";
+import type { TranslationProvider } from "../translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
 import type { CollectionAdminSlot, LevelContext } from "./types";
 type ConfigModifier = (config: Config) => Config;
@@ -9,6 +11,8 @@ export type PluginConfigBuilderDeps = {
     basePath: string;
     access?: AccessGuard;
     taskRunnerFactory: TaskRunnerFactory;
+    schemaMap: CollectionSchemaMap;
+    translationProvider: TranslationProvider;
 };
 /**
  * The single place that mutates the Payload `config`. Levels (through the narrow
@@ -26,6 +30,8 @@ export declare class PluginConfigBuilder implements LevelContext {
     readonly basePath: string;
     readonly access?: AccessGuard;
     readonly taskRunnerFactory: TaskRunnerFactory;
+    readonly schemaMap: CollectionSchemaMap;
+    readonly translationProvider: TranslationProvider;
     private readonly endpoints;
     private readonly collectionComponents;
     private readonly adminProviders;

package/dist/server/modules/translation-levels/PluginConfigBuilder.js

@@ -32,6 +32,8 @@ function attachToSlot(collection, slot, component) {
     basePath;
     access;
     taskRunnerFactory;
+    schemaMap;
+    translationProvider;
     endpoints = [];
     collectionComponents = [];
     adminProviders = [];
@@ -41,6 +43,8 @@ function attachToSlot(collection, slot, component) {
         this.basePath = deps.basePath;
         this.access = deps.access;
         this.taskRunnerFactory = deps.taskRunnerFactory;
+        this.schemaMap = deps.schemaMap;
+        this.translationProvider = deps.translationProvider;
     }
     addEndpoints(endpoints) {
         this.endpoints.push(...endpoints);

package/dist/server/modules/translation-levels/fieldLevel.d.ts

@@ -0,0 +1,23 @@
+import type { TranslationLevel } from "./types";
+/**
+ * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
+ * a single declared field **from a chosen source locale** — it reads the field's value from the
+ * saved document in that locale and translates it into the active locale. No runner, no queue, no
+ * persistence. Unlike `documentLevel` / `collectionLevel`, it contributes no admin component: the
+ * per-field control UI is wired separately at field-declaration time via `withFieldTranslation(field)`.
+ *
+ * Not part of the default `levels`, so it stays strictly opt-in.
+ *
+ * @returns an opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`
+ * @since 0.6.0
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), fieldLevel()],
+ * });
+ * ```
+ */
+export declare function fieldLevel(): TranslationLevel;

package/dist/server/modules/translation-levels/fieldLevel.js

@@ -0,0 +1,37 @@
+import { createFieldRoute } from "../../features/translate-field";
+/**
+ * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
+ * a single declared field **from a chosen source locale** — it reads the field's value from the
+ * saved document in that locale and translates it into the active locale. No runner, no queue, no
+ * persistence. Unlike `documentLevel` / `collectionLevel`, it contributes no admin component: the
+ * per-field control UI is wired separately at field-declaration time via `withFieldTranslation(field)`.
+ *
+ * Not part of the default `levels`, so it stays strictly opt-in.
+ *
+ * @returns an opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`
+ * @since 0.6.0
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), fieldLevel()],
+ * });
+ * ```
+ */ export function fieldLevel() {
+    return {
+        extend (ctx) {
+            ctx.addEndpoints([
+                createFieldRoute({
+                    schemaMap: ctx.schemaMap,
+                    translationProvider: ctx.translationProvider,
+                    access: ctx.access,
+                    basePath: ctx.basePath
+                })
+            ]);
+        }
+    };
+}
+
+//# sourceMappingURL=fieldLevel.js.map

package/dist/server/modules/translation-levels/index.d.ts

@@ -1,3 +1,4 @@
 export type { TranslationLevel } from "./types";
 export { documentLevel } from "./documentLevel";
 export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";

package/dist/server/modules/translation-levels/index.js

@@ -1,4 +1,5 @@
 export { documentLevel } from "./documentLevel";
 export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";
 
 //# sourceMappingURL=index.js.map

package/dist/server/modules/translation-levels/types.d.ts

@@ -1,6 +1,8 @@
 import type { CollectionConfig, Endpoint } from "payload";
 import type { AccessGuard } from "../../../types/AccessGuard";
 import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { CollectionSchemaMap } from "../../features/translate-document";
+import type { TranslationProvider } from "../translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
 export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";
 /**
@@ -27,7 +29,6 @@ export interface TranslationLevel {
  *
  * A level contributes via these generic primitives; it never mutates the raw
  * Payload config. The plugin deduplicates endpoints by method + path on apply.
- * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
  * @internal
  */
 export interface LevelContext {
@@ -35,6 +36,10 @@ export interface LevelContext {
     readonly basePath: string;
     readonly access?: AccessGuard;
     readonly taskRunnerFactory: TaskRunnerFactory;
+    /** Deep-cloned localized field schema per managed collection slug. */
+    readonly schemaMap: CollectionSchemaMap;
+    /** The configured translation backend (used by the synchronous field level). */
+    readonly translationProvider: TranslationProvider;
     /** Register endpoints. Deduplicated by method + path when applied. */
     addEndpoints(endpoints: Endpoint[]): void;
     /** Attach an admin component to a slot on every managed collection. */

package/dist/server/modules/translation-levels/types.js

@@ -3,7 +3,6 @@
  *
  * A level contributes via these generic primitives; it never mutates the raw
  * Payload config. The plugin deduplicates endpoints by method + path on apply.
- * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
  * @internal
  */ export { };
 

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.d.ts

@@ -1,11 +1,7 @@
-import type { Field } from 'payload';
+import type { Field } from "payload";
 /**
- * Deep merges source and target data with target priority.
- * Creates full document shape needed for Payload validation.
- *
- * Logic:
- * - If targetValue exists and is not empty → use targetValue
- * - Otherwise → use sourceValue
+ * Deep-merges source and target data with target priority, producing the full document shape
+ * Payload validation needs. Built on the shared {@link walkFields} engine.
  *
  * Stage 1 of the translation pipeline.
  */
@@ -14,12 +10,10 @@ export declare class DataReconciler {
     constructor(schema: Field[]);
     /**
      * Reconciles source and target data into a complete document shape.
-     * The result contains all fields needed for Payload validation.
      *
      * @param sourceData - Source locale document data
      * @param targetData - Target locale document data (may be empty/partial)
      * @returns Complete document shape with reconciled field values
      */
     reconcile(sourceData: Record<string, unknown>, targetData: Record<string, unknown>): Record<string, unknown>;
-    private reconcileFields;
 }