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

package/README.md

@@ -12,6 +12,7 @@ Translation plugin for Payload CMS 3.x. Automatically translate your localized c
 - **Pluggable providers** — use OpenAI or create custom translation providers
 - **Field exclusion** — exclude specific fields from translation via `withFieldTranslation`
 - **Translation strategies** — choose between overwrite all or skip existing translations
+- **Configurable surfaces** — enable the per-document popup and/or the bulk-collection dashboard via the `levels` option _(since v0.5.0)_
 
 ## Installation
 
@@ -33,11 +34,7 @@ yarn add @focus-reactive/payload-plugin-translator
 
 ```typescript
 import { buildConfig } from "payload";
-import {
-  translatorPlugin,
-  createOpenAIProvider,
-  createPayloadJobsRunner,
-} from "@focus-reactive/payload-plugin-translator";
+import { translatorPlugin, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
 import { Posts } from "./collections/Posts";
 import { Pages } from "./collections/Pages";
 
@@ -65,13 +62,14 @@ export default buildConfig({
 
 Configuration for `translatorPlugin()`.
 
-| Property              | Type                  | Required | Default        | Description                                                                                                         |
-| --------------------- | --------------------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `collections`         | `CollectionConfig[]`  | Yes      | —              | Original collection configs to enable translation for. Must be the same objects passed to `buildConfig`, not slugs. |
-| `translationProvider` | `TranslationProvider` | Yes      | —              | Translation provider instance (e.g., `createOpenAIProvider(...)`)                                                   |
-| `runner`              | `TaskRunnerProvider`  | Yes      | —              | Task runner provider for background processing (e.g., `createPayloadJobsRunner()`)                                  |
-| `access`              | `AccessGuard`         | No       | `undefined`    | Access control function for translation endpoints                                                                   |
-| `basePath`            | `string`              | No       | `'/translate'` | Base path for all API endpoints                                                                                     |
+| Property              | Type                  | Required | Default                                | Description                                                                                                         |
+| --------------------- | --------------------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `collections`         | `CollectionConfig[]`  | Yes      | —                                      | Original collection configs to enable translation for. Must be the same objects passed to `buildConfig`, not slugs. |
+| `translationProvider` | `TranslationProvider` | Yes      | —                                      | Translation provider instance (e.g., `createOpenAIProvider(...)`)                                                   |
+| `runner`              | `TaskRunnerProvider`  | Yes      | —                                      | Task runner provider for background processing (e.g., `createPayloadJobsRunner()`)                                  |
+| `access`              | `AccessGuard`         | No       | `undefined`                            | Access guard (`{ check }`) for the translation endpoints; omit to leave them open                                   |
+| `basePath`            | `string`              | No       | `'/translate'`                         | Base path for all API endpoints                                                                                     |
+| `levels`              | `TranslationLevel[]`  | No       | `[documentLevel(), collectionLevel()]` | Which translation surfaces to enable. See [Translation Levels](#translation-levels)                                 |
 
 ```typescript
 translatorPlugin({
@@ -80,11 +78,37 @@ translatorPlugin({
     apiKey: process.env.OPENAI_API_KEY,
   }),
   runner: createPayloadJobsRunner(),
-  access: async ({ req }) => req.user?.role === "admin",
+  access: { check: ({ req }) => req.user?.role === "admin" },
   basePath: "/translate",
 });
 ```
 
+### Translation Levels
+
+_Since v0.5.0._
+
+The `levels` option controls which translation surfaces the plugin exposes. Each entry is a factory you import and list:
+
+- `documentLevel()` — a **Translate** popup on the document edit view (translate one document).
+- `collectionLevel()` — a **bulk dashboard** on the collection list view (translate many at once).
+
+Both run through the configured `runner` (async Payload Jobs by default, or synchronous via `createSyncRunner()`) and share the same translation REST API.
+
+```typescript
+import { translatorPlugin, documentLevel, collectionLevel, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
+
+translatorPlugin({
+  collections: [Posts],
+  translationProvider: createOpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY,
+  }),
+  runner: createPayloadJobsRunner(),
+  levels: [collectionLevel()], // bulk dashboard only — no per-document popup
+});
+```
+
+Omit `levels` for the default `[documentLevel(), collectionLevel()]`, which is identical to the previous behaviour — so adopting this option is non-breaking. A synchronous `fieldLevel()` (in-place field translation) is planned for a later release.
+
 ### OpenAIProviderConfig
 
 Configuration for `createOpenAIProvider()`.
@@ -100,8 +124,7 @@ Configuration for `createOpenAIProvider()`.
 createOpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY,
   model: "gpt-4o-mini",
-  systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) =>
-    `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
+  systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) => `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
   dryRun: false,
 });
 ```
@@ -165,10 +188,7 @@ Configuration for `withFieldTranslation()` helper or `field.custom.translateKit`
 ```typescript
 import { withFieldTranslation } from "@focus-reactive/payload-plugin-translator";
 
-withFieldTranslation(
-  { name: "sku", type: "text", localized: true },
-  { exclude: true },
-);
+withFieldTranslation({ name: "sku", type: "text", localized: true }, { exclude: true });
 ```
 
 ## Translation Strategies
@@ -310,20 +330,12 @@ type TranslationOutput = Record<TranslationIndex, string>;
 #### Example Implementation
 
 ```typescript
-import type {
-  TranslationProvider,
-  TranslationInput,
-  TranslationOutput,
-} from "@focus-reactive/payload-plugin-translator";
+import type { TranslationProvider, TranslationInput, TranslationOutput } from "@focus-reactive/payload-plugin-translator";
 
 class DeepLProvider implements TranslationProvider {
   constructor(private apiKey: string) {}
 
-  async translate(
-    content: TranslationInput,
-    sourceLng: string,
-    targetLng: string,
-  ): Promise<TranslationOutput | null> {
+  async translate(content: TranslationInput, sourceLng: string, targetLng: string): Promise<TranslationOutput | null> {
     try {
       // content example: { "0": "Hello", "1": "World" }
       const texts = Object.values(content);
@@ -401,6 +413,9 @@ import type {
 
   // Field config
   FieldTranslationConfig,
+
+  // Translation levels
+  TranslationLevel,
 } from "@focus-reactive/payload-plugin-translator";
 ```
 

package/dist/client/shared/ui/Button/Button.d.ts

@@ -1,9 +1,9 @@
-import type { ComponentPropsWithRef, ReactNode } from 'react';
-type ButtonProps = ComponentPropsWithRef<'button'> & {
+import type { ComponentPropsWithRef, ReactNode } from "react";
+type ButtonProps = ComponentPropsWithRef<"button"> & {
     $fullWidth?: boolean;
-    $variant?: 'outlined' | 'filled' | 'unstyled' | 'transparent' | 'light';
+    $variant?: "outlined" | "filled" | "unstyled" | "transparent" | "light";
     $startContent?: ReactNode;
-    $size?: 'sm' | 'md' | 'lg';
+    $size?: "sm" | "md" | "lg";
     $isLoading?: boolean;
     $isIconButton?: boolean;
 };

package/dist/client/shared/ui/Button/Button.js

@@ -1,31 +1,31 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import classNames from 'classnames';
-import { forwardRef } from 'react';
-import Loading from '../Loading';
-import styles from './styles.module.scss';
+import classNames from "classnames";
+import { forwardRef } from "react";
+import Loading from "../Loading";
+import styles from "./styles.module.scss";
 const sizes = {
     sm: {
-        height: '24px',
-        paddingInline: '0.25rem'
+        height: "24px",
+        paddingInline: "0.25rem"
     },
     md: {
-        height: '32px',
-        paddingInline: '0.5rem'
+        height: "32px",
+        paddingInline: "0.5rem"
     },
     lg: {
-        height: '40px',
-        paddingInline: '0.75rem'
+        height: "40px",
+        paddingInline: "0.75rem"
     }
 };
-const Button = /*#__PURE__*/ forwardRef(function Button({ className = '', children, $fullWidth, style, $startContent, $variant, $isLoading, $size = 'md', $isIconButton, ...props }, ref) {
+const Button = /*#__PURE__*/ forwardRef(function Button({ className = "", children, $fullWidth, style, $startContent, $variant, $isLoading, $size = "md", $isIconButton, ...props }, ref) {
     const _style = {
-        '--button-width': $fullWidth ? '100%' : 'auto',
-        '--height': sizes[$size].height,
-        '--padding-inline': $isIconButton ? '0' : sizes[$size].paddingInline,
-        '--width': $isIconButton ? sizes[$size].height : 'auto',
+        "--button-width": $fullWidth ? "100%" : "auto",
+        "--height": sizes[$size].height,
+        "--padding-inline": $isIconButton ? "0" : sizes[$size].paddingInline,
+        "--width": $isIconButton ? sizes[$size].height : "auto",
         ...style
     };
-    const buttonClassName = $variant === 'unstyled' ? classNames(styles['unstyled'], className, $isIconButton && styles['icon-button']) : classNames(styles['button'], className, $variant ? styles[$variant] : undefined, $isIconButton && styles['icon-button']);
+    const buttonClassName = $variant === "unstyled" ? classNames(styles["unstyled"], className, $isIconButton && styles["icon-button"]) : classNames(styles["button"], className, $variant ? styles[$variant] : undefined, $isIconButton && styles["icon-button"]);
     return /*#__PURE__*/ _jsxs("button", {
         ...props,
         style: _style,
@@ -33,11 +33,11 @@ const Button = /*#__PURE__*/ forwardRef(function Button({ className = '', childr
         className: buttonClassName,
         children: [
             $startContent && /*#__PURE__*/ _jsx("div", {
-                className: styles['start-content'],
+                className: styles["start-content"],
                 children: $startContent
             }),
             $isLoading ? /*#__PURE__*/ _jsx(Loading, {
-                size: $isIconButton ? 'small' : 'medium'
+                size: $isIconButton ? "small" : "medium"
             }) : children
         ]
     });

package/dist/client/shared/ui/Button/styles.module.scss

@@ -7,7 +7,7 @@
   justify-content: center;
   align-items: center;
   text-decoration: none;
-  transition: background 0.1sease-in-out, opacity 0.2sease-in-out, border-color 0.2sease-in-out;
+  transition: background 0.1s ease-in-out, opacity 0.2s ease-in-out, border-color 0.2s ease-in-out;
   background: none;
   padding-block: 0.25rem;
   padding-inline: var(--padding-inline);

package/dist/client/shared/ui/Popup/Popup.d.ts

@@ -1,10 +1,16 @@
-import type { PropsWithChildren, ReactElement } from 'react';
+import type { PropsWithChildren, ReactElement } from "react";
 type PopupProps = PropsWithChildren<{
     $trigger: ReactElement;
-    $align?: 'center' | 'end' | 'start';
-    $side?: 'top' | 'right' | 'bottom' | 'left';
+    $align?: "center" | "end" | "start";
+    $side?: "top" | "right" | "bottom" | "left";
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /**
+     * Forwarded to Radix `Popover.Content`. Call `event.preventDefault()` to stop the popover
+     * from auto-focusing its first focusable child on open — useful when that child is a
+     * tooltip trigger (Radix tooltips open on focus, so autofocus would flash the tooltip).
+     */
+    onOpenAutoFocus?: (event: Event) => void;
 }>;
-declare function Popup({ open, children, onOpenChange, $trigger, $align, $side }: PopupProps): import("react/jsx-runtime").JSX.Element;
+declare function Popup({ open, children, onOpenChange, $trigger, $align, $side, onOpenAutoFocus }: PopupProps): import("react/jsx-runtime").JSX.Element;
 export default Popup;

package/dist/client/shared/ui/Popup/Popup.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import * as Popover from '@radix-ui/react-popover';
-import style from './styles.module.scss';
-function Popup({ open, children, onOpenChange, $trigger, $align, $side }) {
+import * as Popover from "@radix-ui/react-popover";
+import style from "./styles.module.scss";
+function Popup({ open, children, onOpenChange, $trigger, $align, $side, onOpenAutoFocus }) {
     return /*#__PURE__*/ _jsxs(Popover.Root, {
         open: open,
         onOpenChange: onOpenChange,
@@ -16,6 +16,7 @@ function Popup({ open, children, onOpenChange, $trigger, $align, $side }) {
                     side: $side,
                     align: $align,
                     className: style.popover,
+                    onOpenAutoFocus: onOpenAutoFocus,
                     children: children
                 })
             })

package/dist/client/shared/ui/Select/Select.d.ts

@@ -1,13 +1,15 @@
-import type { ComponentPropsWithoutRef, ComponentPropsWithRef } from 'react';
-type SelectProps = ComponentPropsWithRef<'select'> & {
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef } from "react";
+type SelectProps = ComponentPropsWithRef<"select"> & {
     emptyOption?: boolean;
     hasError?: boolean;
-    $size?: 'sm' | 'md' | 'lg';
-    'aria-describedby'?: string;
-    'aria-invalid'?: boolean;
+    $size?: "sm" | "md" | "lg";
+    /** Stretch to fill the container (default). Set `false` to size to content — useful inline. */
+    $fullWidth?: boolean;
+    "aria-describedby"?: string;
+    "aria-invalid"?: boolean;
 };
-type SelectOptionProps = ComponentPropsWithoutRef<'option'>;
-type SelectEmptyOptionProps = Omit<SelectOptionProps, 'value' | 'disabled' | 'hidden'>;
+type SelectOptionProps = ComponentPropsWithoutRef<"option">;
+type SelectEmptyOptionProps = Omit<SelectOptionProps, "value" | "disabled" | "hidden">;
 declare const SelectOption: ({ children, ...props }: SelectOptionProps) => import("react/jsx-runtime").JSX.Element;
 declare const SelectEmptyOption: ({ children, ...props }: SelectEmptyOptionProps) => import("react/jsx-runtime").JSX.Element;
 declare const Select: import("react").ForwardRefExoticComponent<Omit<SelectProps, "ref"> & import("react").RefAttributes<HTMLSelectElement>>;

package/dist/client/shared/ui/Select/Select.js

@@ -1,22 +1,22 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import classNames from 'classnames';
-import { forwardRef } from 'react';
-import styles from './styles.module.scss';
+import classNames from "classnames";
+import { forwardRef } from "react";
+import styles from "./styles.module.scss";
 const sizes = {
     sm: {
-        height: '24px',
-        paddingInline: '0.25rem',
-        fontSize: '0.875rem'
+        height: "24px",
+        paddingInline: "0.25rem",
+        fontSize: "0.875rem"
     },
     md: {
-        height: '32px',
-        paddingInline: '0.5rem',
-        fontSize: '1rem'
+        height: "32px",
+        paddingInline: "0.5rem",
+        fontSize: "1rem"
     },
     lg: {
-        height: '40px',
-        paddingInline: '0.75rem',
-        fontSize: '1rem'
+        height: "40px",
+        paddingInline: "0.75rem",
+        fontSize: "1rem"
     }
 };
 const SelectOption = ({ children, ...props })=>/*#__PURE__*/ _jsx("option", {
@@ -28,15 +28,16 @@ const SelectEmptyOption = ({ children, ...props })=>/*#__PURE__*/ _jsx("option",
         ...props,
         children: children
     });
-const Select = /*#__PURE__*/ forwardRef(function Select({ children, className = '', hasError = false, $size = 'lg', style, 'aria-invalid': ariaInvalid, ...props }, ref) {
+const Select = /*#__PURE__*/ forwardRef(function Select({ children, className = "", hasError = false, $size = "lg", $fullWidth = true, style, "aria-invalid": ariaInvalid, ...props }, ref) {
     const _style = {
-        '--height': sizes[$size].height,
-        '--padding-inline': sizes[$size].paddingInline,
-        '--font-size': sizes[$size].fontSize,
+        "--height": sizes[$size].height,
+        "--padding-inline": sizes[$size].paddingInline,
+        "--font-size": sizes[$size].fontSize,
         ...style
     };
     const selectClassName = classNames(styles.select, styles[`size-${$size}`], {
-        [styles.selectError]: hasError
+        [styles.selectError]: hasError,
+        [styles.auto]: !$fullWidth
     }, className);
     return /*#__PURE__*/ _jsx("select", {
         ref: ref,

package/dist/client/shared/ui/Select/styles.module.scss

@@ -31,6 +31,11 @@
   }
 }
 
+/* Opt out of full width (`$fullWidth={false}`) — size to content, e.g. inline in a row. */
+.auto {
+  width: auto;
+}
+
 /* Size-specific styles if needed */
 .size-sm {
   background-size: 12px 12px;

package/dist/index.d.ts

@@ -1,14 +1,16 @@
-export { translatorPlugin } from './plugin';
-export type { TranslatorPluginConfig } from './plugin';
-export type { AccessGuard, AccessGuardRequest } from './types/AccessGuard';
-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 { withFieldTranslation } from './field-config';
-export type { FieldTranslationConfig } from './field-config';
-export { createTranslatePlugin, TranslateCollectionPlugin } from './plugin';
-export type { TranslateCollectionPluginConfig } from './plugin';
-export { OpenAITranslationProvider } from './server/modules/translation-providers';
-export { translateKitField } from './field-config';
-export type { TranslateKitFieldConfig } from './field-config';
+export { translatorPlugin } from "./plugin";
+export type { TranslatorPluginConfig } from "./plugin";
+export type { AccessGuard, AccessGuardRequest } from "./types/AccessGuard";
+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 type { TranslationLevel } from "./server/modules/translation-levels";
+export { withFieldTranslation } from "./field-config";
+export type { FieldTranslationConfig } from "./field-config";
+export { createTranslatePlugin, TranslateCollectionPlugin } from "./plugin";
+export type { TranslateCollectionPluginConfig } from "./plugin";
+export { OpenAITranslationProvider } from "./server/modules/translation-providers";
+export { translateKitField } from "./field-config";
+export type { TranslateKitFieldConfig } from "./field-config";

package/dist/index.js

@@ -1,14 +1,16 @@
 // Main plugin
-export { translatorPlugin } from './plugin';
+export { translatorPlugin } from "./plugin";
 // Translation providers
-export { createOpenAIProvider } from './server/modules/translation-providers';
+export { createOpenAIProvider } from "./server/modules/translation-providers";
 // Task runners
-export { createPayloadJobsRunner, createSyncRunner } from './server/modules/task-runner';
+export { createPayloadJobsRunner, createSyncRunner } from "./server/modules/task-runner";
+// Translation levels
+export { documentLevel, collectionLevel } from "./server/modules/translation-levels";
 // Field config
-export { withFieldTranslation } from './field-config';
+export { withFieldTranslation } from "./field-config";
 // Deprecated exports (for backwards compatibility)
-export { createTranslatePlugin, TranslateCollectionPlugin } from './plugin';
-export { OpenAITranslationProvider } from './server/modules/translation-providers';
-export { translateKitField } from './field-config';
+export { createTranslatePlugin, TranslateCollectionPlugin } from "./plugin";
+export { OpenAITranslationProvider } from "./server/modules/translation-providers";
+export { translateKitField } from "./field-config";
 
 //# sourceMappingURL=index.js.map

package/dist/plugin.d.ts

@@ -1,7 +1,8 @@
-import type { CollectionConfig, Config } from 'payload';
-import type { AccessGuard } from './types/AccessGuard';
-import type { TranslationProvider } from './server/modules/translation-providers';
-import type { TaskRunnerProvider } from './server/modules/task-runner';
+import type { CollectionConfig, Config } from "payload";
+import type { AccessGuard } from "./types/AccessGuard";
+import type { TranslationProvider } from "./server/modules/translation-providers";
+import type { TaskRunnerProvider } from "./server/modules/task-runner";
+import type { TranslationLevel } from "./server/modules/translation-levels";
 export type TranslatorPluginConfig = {
     /**
      * Original collection configs (same objects passed to buildConfig).
@@ -32,6 +33,16 @@ export type TranslatorPluginConfig = {
      * @default '/translate'
      */
     basePath?: string;
+    /**
+     * Which translation surfaces to enable, as level factories — `documentLevel()`,
+     * `collectionLevel()` (and, from a later phase, `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.
+     * @default [documentLevel(), collectionLevel()]
+     * @since 0.5.0
+     */
+    levels?: TranslationLevel[];
 };
 /** @deprecated Use `TranslatorPluginConfig` instead */
 export type TranslateCollectionPluginConfig = TranslatorPluginConfig;

package/dist/plugin.js

@@ -1,14 +1,8 @@
-import { CacheProviderExport } from './client/app/cache/CacheProvider.export';
-import { BulkDocumentTranslationDashboard } from './client/widgets/bulk-translation-dashboard/ui/BulkTranslationDashboard.export';
-import { TranslateDocumentExport } from './client/widgets/translate-document';
-import { TranslateDocumentHandler } from './server/features/translate-document';
-import { createEnqueueRoute } from './server/features/enqueue-translation';
-import { createRunRoute } from './server/features/run-translation';
-import { createCancelRoute } from './server/features/cancel';
-import { createCancelByCollectionRoute } from './server/features/cancel-by-collection';
-import { createGetDocumentStatusRoute } from './server/features/get-document-status';
-import { createGetCollectionStatusRoute } from './server/features/get-collection-status';
-import { normalizePath, pipe } from './server/shared';
+import { CacheProviderExport } from "./client/app/cache/CacheProvider.export";
+import { TranslateDocumentHandler } from "./server/features/translate-document";
+import { documentLevel, collectionLevel } from "./server/modules/translation-levels";
+import { PluginConfigBuilder } from "./server/modules/translation-levels/PluginConfigBuilder";
+import { normalizePath } from "./server/shared";
 /** @deprecated Use `translatorPlugin` function instead */ export class TranslateCollectionPlugin {
     pluginConfig;
     constructor(pluginConfig){
@@ -16,7 +10,7 @@ import { normalizePath, pipe } from './server/shared';
     }
     init() {
         return async (config)=>{
-            const { access, translationProvider, basePath: rawBasePath = '/translate' } = this.pluginConfig;
+            const { access, translationProvider, runner, collections, levels, basePath: rawBasePath = "/translate" } = this.pluginConfig;
             // Build schema map from deep-cloned collections
             // Deep clone is required because Payload mutates the original collection objects,
             // removing `localized: true` from nested fields during sanitization.
@@ -25,14 +19,14 @@ import { normalizePath, pipe } from './server/shared';
             // TODO: Consider introducing a FieldLike interface with only the properties
             // used by the pipeline (name, type, localized, fields, blocks, tabs, custom)
             // to make the contract explicit and avoid reliance on JSON round-trip.
-            const schemaMap = new Map(this.pluginConfig.collections.map((col)=>[
+            const schemaMap = new Map(collections.map((col)=>[
                     col.slug,
                     JSON.parse(JSON.stringify(col.fields))
                 ]));
             const collectionSlugs = new Set(schemaMap.keys());
             const basePath = normalizePath(rawBasePath);
             const translateHandler = new TranslateDocumentHandler(translationProvider, schemaMap);
-            const runnerConfigModifier = this.pluginConfig.runner.configure({
+            const runnerContext = {
                 handler: async (payload, input)=>{
                     await translateHandler.handle(payload, {
                         collection: input.collection,
@@ -44,50 +38,33 @@ import { normalizePath, pipe } from './server/shared';
                     });
                 },
                 collections: Array.from(collectionSlugs)
+            };
+            const runnerConfigModifier = runner.configure(runnerContext);
+            // Bind the context once so routes receive a self-sufficient factory: the
+            // runner needs no mutable per-instance handler state and create() has no
+            // "configure() must run first" ordering coupling (translator plan, 0c).
+            const taskRunnerFactory = {
+                create: (payload)=>runner.create(payload, runnerContext.handler)
+            };
+            const activeLevels = levels ?? [
+                documentLevel(),
+                collectionLevel()
+            ];
+            const builder = new PluginConfigBuilder({
+                collections,
+                basePath,
+                access,
+                taskRunnerFactory
             });
-            return pipe(// 1. Set up UI component provider import
-            (cfg)=>{
-                if (!cfg.admin) cfg.admin = {};
-                if (!cfg.admin.components) cfg.admin.components = {};
-                if (!cfg.admin.components.providers) cfg.admin.components.providers = [];
-                cfg.admin.components.providers.push(new CacheProviderExport(basePath));
-                return cfg;
-            }, // 2. Set up UI component import
-            (cfg)=>{
-                cfg.collections?.forEach((collection)=>{
-                    if (!collectionSlugs.has(collection.slug)) {
-                        return;
-                    }
-                    if (!collection.admin) collection.admin = {};
-                    if (!collection.admin.components) collection.admin.components = {};
-                    if (!collection.admin.components.edit) collection.admin.components.edit = {};
-                    if (!collection.admin.components.edit.beforeDocumentControls) {
-                        collection.admin.components.edit.beforeDocumentControls = [];
-                    }
-                    if (!collection.admin.components.beforeListTable) {
-                        collection.admin.components.beforeListTable = [];
-                    }
-                    collection.admin.components.edit.beforeDocumentControls.push(new TranslateDocumentExport(collection, access));
-                    collection.admin.components.beforeListTable.push(new BulkDocumentTranslationDashboard(access));
-                });
-                return cfg;
-            }, // 3. Runner configures jobs/tasks/autorun
-            runnerConfigModifier, // 4. Add global endpoints
-            (cfg)=>{
-                if (!cfg.endpoints) cfg.endpoints = [];
-                const collectionConfig = {
-                    availableCollections: collectionSlugs
-                };
-                cfg.endpoints.push(...[
-                    createEnqueueRoute(this.pluginConfig.runner, collectionConfig, access, basePath),
-                    createRunRoute(this.pluginConfig.runner, access, basePath),
-                    createCancelRoute(this.pluginConfig.runner, access, basePath),
-                    createCancelByCollectionRoute(collectionConfig, this.pluginConfig.runner, access, basePath),
-                    createGetDocumentStatusRoute(collectionConfig, this.pluginConfig.runner, access, basePath),
-                    createGetCollectionStatusRoute(collectionConfig, this.pluginConfig.runner, access, basePath)
-                ]);
-                return cfg;
-            })(config);
+            for (const level of activeLevels)level.extend(builder);
+            // Plugin-level contributions, routed through the same single config-writer:
+            //  - the runner's jobs/autorun/onInit modifier (the builder applies it first,
+            //    so a modifier returning a fresh config object doesn't drop later writes),
+            //  - the always-on client cache provider.
+            builder.addConfigModifier(runnerConfigModifier);
+            builder.addAdminProvider(new CacheProviderExport(basePath));
+            // The single place the Payload config is mutated.
+            return builder.applyTo(config);
         };
     }
 }

package/dist/server/features/cancel/handler.d.ts

@@ -1,10 +1,10 @@
 import type { PayloadRequest } from "payload";
-import type { TaskRunnerProvider } from "../../modules/task-runner";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
 /**
  * Cancels and deletes translation tasks by IDs
  */
 export declare class CancelHandler {
     private readonly taskRunnerFactory;
-    constructor(taskRunnerFactory: TaskRunnerProvider);
+    constructor(taskRunnerFactory: TaskRunnerFactory);
     handle(req: PayloadRequest): Promise<Response>;
 }

package/dist/server/features/cancel/handler.js

@@ -9,7 +9,9 @@ import { CancelInputSchema } from "./model";
     }
     async handle(req) {
         const validationResult = CancelInputSchema.safeParse(await req.json?.());
-        if (validationResult.error) return ServerResponse.validationError(validationResult.error.issues);
+        if (validationResult.error) {
+            return ServerResponse.validationError(validationResult.error.issues);
+        }
         const { ids } = validationResult.data;
         const runner = this.taskRunnerFactory.create(req.payload);
         await runner.cancel(ids);

package/dist/server/features/cancel/route.d.ts

@@ -1,7 +1,7 @@
-import type { Endpoint } from 'payload';
-import type { AccessGuard } from '../../shared';
-import type { TaskRunnerProvider } from '../../modules/task-runner';
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { TaskRunnerFactory } from "../../modules/task-runner";
 /**
  * Creates the batch cancel endpoint
  */
-export declare function createCancelRoute(taskRunnerFactory: TaskRunnerProvider, access?: AccessGuard, basePath?: string): Endpoint;
+export declare function createCancelRoute(taskRunnerFactory: TaskRunnerFactory, access?: AccessGuard, basePath?: string): Endpoint;