@focus-reactive/payload-plugin-translator 0.5.1 → 0.6.1

package/dist/client/widgets/translate-field-control/ui/styles.module.scss

@@ -0,0 +1,48 @@
+.popup {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+}
+
+/* The from → to direction group; lays the source select, arrow and target chip out inline. */
+.direction {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+}
+
+.arrow {
+  display: flex;
+  align-items: center;
+  color: var(--theme-elevation-400);
+}
+
+/* The fixed target locale — framed like the source Select (same border/radius/height/font) for
+   a consistent two-box "source → target" look, but with a muted bg to read as read-only. */
+.current {
+  display: inline-flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 24px;
+  padding-inline: 0.5rem;
+  border: 1px solid var(--theme-elevation-150);
+  border-radius: var(--style-radius-s);
+  background: var(--theme-elevation-50);
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--theme-elevation-800);
+}
+
+.trigger {
+  /* inline-flex so the wrapper hugs the icon button — a block/flex div stretches full width,
+     which drags the popover anchor across the field. */
+  display: inline-flex;
+  width: fit-content;
+  margin-bottom: 0.25rem;
+}

package/dist/field-actions.d.ts

@@ -0,0 +1,25 @@
+import type { Field } from "payload";
+import type { RawPayloadComponentExport } from "./client/shared/types/PayloadComponentExport";
+/**
+ * Strategy for placing a per-field control into a field's admin config — the seam
+ * between *what* to render (a control component) and *where* it goes (positioning).
+ *
+ * Today the only implementation is {@link beforeInputPositioner}, built on Payload's
+ * native `admin.components.beforeInput` slot. A future field-slots plugin can supply its
+ * own positioner (e.g. placing the trigger in the field label, next to the locale) by
+ * implementing this same interface — the control component and the wiring in
+ * `withFieldTranslation` stay untouched. This is the connector we expose later; for now
+ * it lives internal, with the default below as the built-in fallback.
+ *
+ * @template T - The concrete field type, preserved through positioning.
+ * @param field - The field to attach the control to.
+ * @param control - Import-map reference to the control component.
+ * @returns The field with the control positioned.
+ */
+export type FieldControlPositioner = <T extends Field>(field: T, control: RawPayloadComponentExport) => T;
+/**
+ * Default positioner: append the control to the field's `admin.components.beforeInput`,
+ * rendering it just above the input. `beforeInput` is an array slot, so we append —
+ * preserving any components already declared on the field.
+ */
+export declare const beforeInputPositioner: FieldControlPositioner;

package/dist/field-actions.js

@@ -0,0 +1,23 @@
+/**
+ * Default positioner: append the control to the field's `admin.components.beforeInput`,
+ * rendering it just above the input. `beforeInput` is an array slot, so we append —
+ * preserving any components already declared on the field.
+ */ export const beforeInputPositioner = (field, control)=>{
+    const withAdmin = field;
+    const existing = withAdmin.admin?.components?.beforeInput ?? [];
+    return {
+        ...field,
+        admin: {
+            ...withAdmin.admin,
+            components: {
+                ...withAdmin.admin?.components,
+                beforeInput: [
+                    ...existing,
+                    control
+                ]
+            }
+        }
+    };
+};
+
+//# sourceMappingURL=field-actions.js.map

package/dist/field-config.d.ts

@@ -1,46 +1,46 @@
-import type { Field } from 'payload';
-import type { FieldTranslationConfig } from './server/shared/field-config';
+import type { Field, RichTextField, TextareaField, TextField } from "payload";
+import type { FieldTranslationConfig } from "./server/shared/field-config";
 export type { FieldTranslationConfig };
+/**
+ * Field types eligible for the per-field translate control — the same text-bearing
+ * leaves the server's `TranslatableField` handles. `richText` writes back by re-mounting
+ * the Lexical editor (see the control); `text` / `textarea` write straight to form state.
+ */
+type FieldControlCandidate = TextField | TextareaField | RichTextField;
 /**
  * @deprecated Use `FieldTranslationConfig` instead
  */
 export type { FieldTranslationConfig as TranslateKitFieldConfig };
 /**
- * Apply translation configuration to a Payload field.
+ * Configure a Payload field for translation.
  *
- * Use this helper to configure how fields should be handled during translation.
+ * - **Add a translate control** — wrap a `text` / `textarea` field with no second
+ *   argument. A per-field Translate control is positioned on the field (today, just
+ *   above the input). Requires `fieldLevel()` in the plugin's `levels` to register the
+ *   endpoint. Control-injection behavior is `@since 0.6.0`; field exclusion predates it.
+ * - **Exclude from translation** — pass `{ exclude: true }` (any field type). The field
+ *   value is never sent to the translation provider and no control is added.
  *
  * @param field - The Payload field to configure
- * @param config - Translation configuration options
- * @returns The field with translation configuration applied
+ * @param config - Pass `{ exclude: true }` to exclude; omit to add a control
+ * @returns A new field with the configuration applied (the input is not mutated)
  *
  * @example
  * ```ts
  * import { withFieldTranslation } from '@focus-reactive/payload-plugin-translator'
  *
- * // Exclude a field from translation
- * withFieldTranslation(
- *   { name: 'sku', type: 'text', localized: true },
- *   { exclude: true }
- * )
- * ```
+ * // Add a per-field translate control
+ * withFieldTranslation({ name: 'title', type: 'text', localized: true })
  *
- * @example
- * ```ts
- * // In a collection definition
- * const Products: CollectionConfig = {
- *   slug: 'products',
- *   fields: [
- *     { name: 'title', type: 'text', localized: true },
- *     withFieldTranslation(
- *       { name: 'sku', type: 'text', localized: true },
- *       { exclude: true }
- *     ),
- *   ],
- * }
+ * // Exclude a field from translation
+ * withFieldTranslation({ name: 'sku', type: 'text', localized: true }, { exclude: true })
  * ```
  */
-export declare function withFieldTranslation<T extends Field>(field: T, config: FieldTranslationConfig): T;
+export declare function withFieldTranslation<T extends Field>(field: T, ...rest: T extends FieldControlCandidate ? [config?: {
+    exclude?: boolean;
+}] : [config: {
+    exclude: true;
+}]): T;
 /**
  * @deprecated Use `withFieldTranslation` instead
  */

package/dist/field-config.js

@@ -1,46 +1,23 @@
-import { TRANSLATE_KIT_CUSTOM_KEY } from './server/shared/field-config';
+import { TRANSLATE_KIT_CUSTOM_KEY } from "./server/shared/field-config";
+import { TranslateFieldControlExport } from "./client/widgets/translate-field-control/ui/TranslateFieldControl.export";
+import { beforeInputPositioner } from "./field-actions";
 /**
- * Apply translation configuration to a Payload field.
- *
- * Use this helper to configure how fields should be handled during translation.
- *
- * @param field - The Payload field to configure
- * @param config - Translation configuration options
- * @returns The field with translation configuration applied
- *
- * @example
- * ```ts
- * import { withFieldTranslation } from '@focus-reactive/payload-plugin-translator'
- *
- * // Exclude a field from translation
- * withFieldTranslation(
- *   { name: 'sku', type: 'text', localized: true },
- *   { exclude: true }
- * )
- * ```
- *
- * @example
- * ```ts
- * // In a collection definition
- * const Products: CollectionConfig = {
- *   slug: 'products',
- *   fields: [
- *     { name: 'title', type: 'text', localized: true },
- *     withFieldTranslation(
- *       { name: 'sku', type: 'text', localized: true },
- *       { exclude: true }
- *     ),
- *   ],
- * }
- * ```
- */ export function withFieldTranslation(field, config) {
-    return {
+ * Where the translate control is placed. The single swap point: when a dedicated
+ * field-slots plugin lands, point this at its positioner (or take one as config) and
+ * the control moves — e.g. into the field label — without touching anything else.
+ * @see FieldControlPositioner
+ */ const activeFieldControlPositioner = beforeInputPositioner;
+export function withFieldTranslation(field, config) {
+    const configured = {
         ...field,
         custom: {
             ...field.custom ?? {},
-            [TRANSLATE_KIT_CUSTOM_KEY]: config
+            [TRANSLATE_KIT_CUSTOM_KEY]: config ?? {}
         }
     };
+    // No `exclude` = control intent: position the control via the active positioner.
+    // `exclude: true` = no control (the field is left out of translation entirely).
+    return config?.exclude ? configured : activeFieldControlPositioner(configured, new TranslateFieldControlExport());
 }
 /**
  * @deprecated Use `withFieldTranslation` instead

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { createOpenAIProvider } from "./server/modules/translation-providers";
 export type { TranslationProvider, TranslationInput, TranslationOutput, OpenAIProviderConfig, DryRunConfig } from "./server/modules/translation-providers";
 export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task-runner";
 export type { TaskRunnerProvider, PayloadJobsRunnerOptions } from "./server/modules/task-runner";
-export { documentLevel, collectionLevel } from "./server/modules/translation-levels";
+export { documentLevel, collectionLevel, fieldLevel } from "./server/modules/translation-levels";
 export type { TranslationLevel } from "./server/modules/translation-levels";
 export { withFieldTranslation } from "./field-config";
 export type { FieldTranslationConfig } from "./field-config";

package/dist/index.js

@@ -5,7 +5,7 @@ export { createOpenAIProvider } from "./server/modules/translation-providers";
 // Task runners
 export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task-runner";
 // Translation levels
-export { documentLevel, collectionLevel } from "./server/modules/translation-levels";
+export { documentLevel, collectionLevel, fieldLevel } from "./server/modules/translation-levels";
 // Field config
 export { withFieldTranslation } from "./field-config";
 // Deprecated exports (for backwards compatibility)

package/dist/plugin.d.ts

@@ -35,7 +35,7 @@ export type TranslatorPluginConfig = {
     basePath?: string;
     /**
      * Which translation surfaces to enable, as level factories — `documentLevel()`,
-     * `collectionLevel()` (and, from a later phase, `fieldLevel()`). Omit for the
+     * `collectionLevel()`, `fieldLevel()`. Omit for the
      * default `[documentLevel(), collectionLevel()]`, which is exactly today's behaviour.
      * Each level should appear at most once: endpoints are deduplicated, but admin
      * components are not, so a duplicated level renders a duplicated control.

package/dist/plugin.js

@@ -54,7 +54,9 @@ import { normalizePath } from "./server/shared";
                 collections,
                 basePath,
                 access,
-                taskRunnerFactory
+                taskRunnerFactory,
+                schemaMap,
+                translationProvider
             });
             for (const level of activeLevels)level.extend(builder);
             // Plugin-level contributions, routed through the same single config-writer:

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

@@ -0,0 +1,17 @@
+import type { PayloadRequest } from "payload";
+import type { FieldTranslationConfig } from "./model";
+/**
+ * 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 declare class TranslateFieldHandler {
+    private readonly config;
+    constructor(config: FieldTranslationConfig);
+    handle(req: PayloadRequest): Promise<Response>;
+}

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

@@ -6,8 +6,11 @@ import type { Field } from "payload";
  *   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, which
- *   can't be resolved from the path alone (the blockType lives in the data) → 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";
@@ -20,12 +23,17 @@ export type FieldSubtreeResolution = {
     status: "not-translatable";
 } | {
     status: "inside-blocks";
+} | {
+    status: "localized-list-ancestor";
 };
 /**
  * Map a declared `fieldPath` to the `{ schema, sourceData }` pair `translateContent` expects.
- * Walks the schema by field name (via the shared {@link findFieldByPath}), dropping array indices
- * (a field's config is shared across array items). Descends transparently through presentational
- * containers (row, collapsible, unnamed tabs) and through named group/array/tab containers. A path
- * that descends through a `blocks` field returns `inside-blocks`.
+ * 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): FieldSubtreeResolution;
+export declare function resolveFieldSubtree(rootFields: Field[], fieldPath: string, value: unknown, doc?: unknown): FieldSubtreeResolution;

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

@@ -1,18 +1,20 @@
 import { isTranslatableField } from "../../shared";
 import { findFieldByPath } from "../../shared/field-traversal";
-const isIndexSegment = (segment)=>/^\d+$/u.test(segment);
 /**
  * Map a declared `fieldPath` to the `{ schema, sourceData }` pair `translateContent` expects.
- * Walks the schema by field name (via the shared {@link findFieldByPath}), dropping array indices
- * (a field's config is shared across array items). Descends transparently through presentational
- * containers (row, collapsible, unnamed tabs) and through named group/array/tab containers. A path
- * that descends through a `blocks` field returns `inside-blocks`.
- */ export function resolveFieldSubtree(rootFields, fieldPath, value) {
-    const segments = fieldPath.split(".").map((segment)=>segment.trim()).filter((segment)=>segment.length > 0 && !isIndexSegment(segment));
+ * 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);
+    const result = findFieldByPath(rootFields, segments, doc);
     switch(result.status){
         case "leaf":
             return isTranslatableField(result.field) ? {
@@ -35,6 +37,10 @@ const isIndexSegment = (segment)=>/^\d+$/u.test(segment);
             return {
                 status: "inside-blocks"
             };
+        case "localized-list-ancestor":
+            return {
+                status: "localized-list-ancestor"
+            };
         case "not-found":
             return {
                 status: "not-found"

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);