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

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

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.js

@@ -1,5 +1,5 @@
 import { isEmpty, isObject } from "../../../../shared";
-import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
 const asObject = (value)=>isObject(value) ? value : {};
 /**
  * Reconcile walker: produces the full document shape from source + target, with target
@@ -7,6 +7,9 @@ const asObject = (value)=>isObject(value) ? value : {};
  * no source value is dropped, `id` is stripped from array/block elements (Postgres rejects it
  * on update), `blockType` is preserved, and non-object array items / unknown blocks pass
  * through unchanged.
+ *
+ * Array/block elements are paired with their target counterpart by `id`, not by position (see
+ * {@link matchElementById}); output order always follows `source`.
  */ const reconcileWalker = {
     enterObject (field, cursor) {
         const sourceValue = cursor.source[field.name];
@@ -21,15 +24,17 @@ const asObject = (value)=>isObject(value) ? value : {};
         if (!Array.isArray(sourceValue)) return "skip";
         const targetValue = cursor.target[field.name];
         const targetArr = Array.isArray(targetValue) ? targetValue : [];
+        const isBlocks = field.type === "blocks";
         const children = [];
         sourceValue.forEach((item, index)=>{
             if (!isObject(item)) return; // non-object element → passthrough (rebuilt in combine)
-            const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+            const fields = isBlocks ? resolveBlockFields(field, item) : field.fields;
             if (!fields) return; // unknown blockType → passthrough
+            // Pair by id, not position: target[index] may be a different element under per-locale ordering.
             children.push({
                 cursor: {
                     source: item,
-                    target: asObject(targetArr[index])
+                    target: matchElementById(targetArr, item, isBlocks)
                 },
                 fields,
                 key: index
@@ -45,7 +50,8 @@ const asObject = (value)=>isObject(value) ? value : {};
     },
     combine (container, children, cursor) {
         if (container.kind === "list") {
-            // Rebuild the full array: reconciled objects where present (by index), raw source items otherwise.
+            // Rebuild the full array in source order: reconciled objects keyed by source position, raw
+            // source items (non-object / unknown block) otherwise.
             const sourceArr = cursor.source[container.key] ?? [];
             const byIndex = new Map(children.map((child)=>[
                     child.key,

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

@@ -1,4 +1,4 @@
-import type { PipelineContext, PipelineStage } from '../../types';
+import type { PipelineContext, PipelineStage } from "../../types";
 /**
  * Deep merges source and target data with target priority.
  * Stage 1 of the translation pipeline.

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.stage.js

@@ -1,4 +1,4 @@
-import { DataReconciler } from './DataReconciler';
+import { DataReconciler } from "./DataReconciler";
 /**
  * Deep merges source and target data with target priority.
  * Stage 1 of the translation pipeline.

package/dist/server/modules/translation-pipeline/stages/field-collector/FieldChunkCollector.d.ts

@@ -8,6 +8,11 @@ import type { FieldChunk } from "../../types";
  * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
  * no-op; results accumulate in a closure.
  *
+ * Array/block elements pair their `source` by position (`filteredData` is built in source order)
+ * but their `target` by `id` (see {@link matchElementById}) — the target locale's elements may be
+ * independently ordered, so a positional target would feed `strategy.shouldTranslate` the wrong
+ * element's value and skip/re-translate the wrong leaf.
+ *
  * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
  * schemas preserve `localized: true` on nested fields.
  */

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

@@ -1,5 +1,5 @@
 import { isFieldExcludedFromTranslation, isLocalizedField, isObject, isTranslatableField } from "../../../../shared";
-import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
 const asObject = (value)=>isObject(value) ? value : {};
 /**
  * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
@@ -8,6 +8,11 @@ const asObject = (value)=>isObject(value) ? value : {};
  * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
  * no-op; results accumulate in a closure.
  *
+ * Array/block elements pair their `source` by position (`filteredData` is built in source order)
+ * but their `target` by `id` (see {@link matchElementById}) — the target locale's elements may be
+ * independently ordered, so a positional target would feed `strategy.shouldTranslate` the wrong
+ * element's value and skip/re-translate the wrong leaf.
+ *
  * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
  * schemas preserve `localized: true` on nested fields.
  */ export class FieldChunkCollector {
@@ -47,16 +52,20 @@ const asObject = (value)=>isObject(value) ? value : {};
                 const targetValue = cursor.target[field.name];
                 const sourceArr = Array.isArray(sourceValue) ? sourceValue : [];
                 const targetArr = Array.isArray(targetValue) ? targetValue : [];
+                const isBlocks = field.type === "blocks";
                 const children = [];
                 value.forEach((item, index)=>{
                     if (!isObject(item)) return;
-                    const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+                    const fields = isBlocks ? resolveBlockFields(field, item) : field.fields;
                     if (!fields) return; // unknown blockType → skip element
+                    // source pairs by index (filteredData shares source order); target by the source
+                    // element's id, since the target locale may be reordered independently.
+                    const sourceItem = asObject(sourceArr[index]);
                     children.push({
                         cursor: {
                             data: item,
-                            source: asObject(sourceArr[index]),
-                            target: asObject(targetArr[index]),
+                            source: sourceItem,
+                            target: matchElementById(targetArr, sourceItem, isBlocks),
                             path: [
                                 ...cursor.path,
                                 field.name,

package/dist/server/modules/translation-providers/OpenAITranslation.provider.d.ts

@@ -76,6 +76,23 @@ export type OpenAIProviderConfig = {
      * @default false
      */
     dryRun?: boolean | DryRunConfig;
+    /**
+     * Per-request timeout in milliseconds for the OpenAI client. A translation job blocks on this
+     * call, so the OpenAI SDK default (10 minutes) is usually too long. Omit to keep the SDK default.
+     *
+     * @example
+     * timeout: 60_000 // 60s
+     *
+     * @since 0.6.0
+     */
+    timeout?: number;
+    /**
+     * Maximum automatic retries the OpenAI client performs on transient errors (429, 5xx, network).
+     * Omit to keep the SDK default (2). Set `0` to disable retries.
+     *
+     * @since 0.6.0
+     */
+    maxRetries?: number;
 };
 /** @deprecated Use `createOpenAIProvider` function instead */
 export declare class OpenAITranslationProvider implements TranslationProvider {

package/dist/server/modules/translation-providers/OpenAITranslation.provider.js

@@ -4,8 +4,12 @@ import { isObject } from "../../shared";
     openAiClient;
     config;
     constructor(config){
+        // `timeout`/`maxRetries` are passed through to the OpenAI SDK; `undefined` keeps the SDK
+        // defaults (10 min timeout, 2 retries). A blocking translation job rarely wants the full 10 min.
         this.openAiClient = new OpenAI({
-            apiKey: config.apiKey
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+            maxRetries: config.maxRetries
         });
         this.config = config;
     }
@@ -43,7 +47,9 @@ import { isObject } from "../../shared";
                 type: "json_object"
             }
         });
-        const translatedContent = chatCompletion.choices[0].message.content;
+        // Guard `choices[0]`: an empty `choices` array (e.g. content-filtered response) would otherwise
+        // throw a TypeError instead of the intended graceful `null`.
+        const translatedContent = chatCompletion.choices[0]?.message?.content;
         if (!translatedContent) return null;
         try {
             return JSON.parse(translatedContent);

package/dist/server/shared/field-config/types.js

@@ -17,6 +17,6 @@
  * ```
  */ /**
  * Key used to store TranslateKit configuration in field.custom
- */ export const TRANSLATE_KIT_CUSTOM_KEY = 'translateKit';
+ */ export const TRANSLATE_KIT_CUSTOM_KEY = "translateKit";
 
 //# sourceMappingURL=types.js.map

package/dist/server/shared/field-traversal/findFieldByPath.d.ts

@@ -4,10 +4,15 @@ import type { LeafField } from "./types";
  * Outcome of navigating a field schema by a path of segment names (see {@link findFieldByPath}).
  *
  * - `leaf` — the path lands on a data-affecting leaf field (carries it).
- * - `container` — the path lands on a `group`/`array`/`blocks` field or a named tab (a container,
- *   not a leaf).
- * - `inside-blocks` — the path descends THROUGH a `blocks` field, which can't be resolved from the
- *   schema alone (the block's `blockType` lives in the data, not the schema).
+ * - `container` — the path lands on a `group`/`array`/`blocks` field, a single block element, or a
+ *   named tab (a container, not a leaf).
+ * - `inside-blocks` — the path descends THROUGH a `blocks` field that can't be resolved: no
+ *   document data was supplied (so the element's `blockType` is unknown), the data is missing at
+ *   that index, or the `blockType` matches no defined block.
+ * - `localized-list-ancestor` — the path descends THROUGH a `localized` `blocks`/`array` field.
+ *   Such fields are stored independently per locale (different order/content), so an element index
+ *   is not a stable cross-locale identity; a caller translating *by path across locales* should
+ *   refuse rather than resolve positionally. (See the "cross-locale block identity" design.)
  * - `not-found` — no field matches a segment, or the path continues past a leaf.
  *
  * @public
@@ -19,6 +24,8 @@ export type FieldPathResult = {
     status: "container";
 } | {
     status: "inside-blocks";
+} | {
+    status: "localized-list-ancestor";
 } | {
     status: "not-found";
 };
@@ -26,15 +33,23 @@ export type FieldPathResult = {
  * Navigate a field schema by a path of segment NAMES, descending one matching branch at a time
  * with early-exit (targeted navigation, not an exhaustive walk). Presentational containers
  * (`row`/`collapsible`/unnamed `group`) and unnamed tabs are transparent — searched in the same
- * path scope. Built on {@link classifyField} / {@link tabScopes} so the structural dispatch lives
- * in one place.
+ * path scope. Built on {@link classifyField} / {@link tabScopes} / {@link resolveBlockFields} so
+ * the structural dispatch lives in one place.
  *
- * The caller supplies already-prepared name segments (split, trimmed, with array indices dropped —
- * a field's config is shared across array items, so indices never appear in the schema).
+ * **Array indices and `blocks`.** Array element configs are shared, so a numeric segment after an
+ * array name selects the data item but not the schema (the schema continues into `array.fields`).
+ * A `blocks` field is polymorphic — which block (and thus which fields) sits at an index lives in
+ * the *data*, not the schema. So to descend through `blocks` the caller must pass the document
+ * `data` and keep the element index in the path: this function reads `data[name][index].blockType`
+ * and resolves the matching block via {@link resolveBlockFields}. Without `data` (or with a
+ * non-indexed path), descending through `blocks` returns `inside-blocks`.
  *
  * @param fields - The schema level to search.
- * @param segments - Remaining path segments (names) to match, head-first.
+ * @param segments - Remaining path segments to match, head-first. Keep array/block element indices
+ *   in the path when navigating with `data`.
+ * @param data - The document (sub)tree aligned with `fields`, used only to disambiguate `blocks`.
+ *   Omit for schema-only navigation.
  * @returns A {@link FieldPathResult}.
  * @public
  */
-export declare function findFieldByPath(fields: Field[], segments: string[]): FieldPathResult;
+export declare function findFieldByPath(fields: Field[], segments: string[], data?: unknown): FieldPathResult;