@justanarthur/payload-plugin-translator 1.3.21 → 3.0.3

package/README.md

@@ -0,0 +1,132 @@
+# @justanarthur/payload-plugin-translator
+
+[Payload CMS](https://payloadcms.com) plugin that keeps localized docs in sync. On every save of a
+listed collection or global, it schedules background jobs that translate each field from the source
+locale into every other declared locale, using a configurable resolver (Google Translate, OpenAI,
+LibreTranslate, or your own).
+
+Editor UX: the publish and save buttons in the affected collections/globals are swapped for a
+custom variant that surfaces the job status. Locales without translations stay empty until the job
+finishes — the plugin never blocks the editor's save.
+
+## Install
+
+```bash
+pnpm add @justanarthur/payload-plugin-translator
+```
+
+Requires `payload@^3.85.0` and `react@^19`. The plugin reads your `config.localization.locales` —
+it short-circuits (returns the config unchanged) when there's only one locale or no localization.
+
+## Quick start
+
+```ts
+// payload.config.ts
+import { buildConfig } from 'payload'
+import { translator, openAIResolver } from '@justanarthur/payload-plugin-translator'
+
+export default buildConfig({
+  plugins: [
+    translator({
+      collections: ['pages', 'posts'],
+      globals: ['header', 'footer'],
+      resolvers: [
+        openAIResolver({ apiKey: process.env.OPENAI_API_KEY! })
+      ]
+    })
+  ]
+})
+```
+
+That's the whole integration. The first save of a Page doc schedules one translate job per non-source
+locale; the job runs against your resolver and writes each translated field back into the
+collection's `_locales` row.
+
+## Built-in resolvers
+
+| Resolver           | Import                                          | Env / config                    | Notes                                                            |
+|--------------------|-------------------------------------------------|---------------------------------|------------------------------------------------------------------|
+| `googleResolver`   | `@justanarthur/payload-plugin-translator/resolvers/google` | `apiKey` (Google Cloud Translation API) | Cheap, good for bulk text. Locale codes are remapped where useful (e.g. `ua` → `uk`). |
+| `openAIResolver`   | `@justanarthur/payload-plugin-translator/resolvers/openAI` | `apiKey`, optional `model`/`baseUrl`/`prompt`/`chunkLength` | Best fidelity. Default model `gpt-4o-mini`. gpt-5.x uses `max_completion_tokens` + `reasoning_effort: 'low'` automatically. Slugs get a transliteration rule baked into the prompt. |
+| `libreResolver`    | `@justanarthur/payload-plugin-translator/resolvers/libreTranslate` | `apiKey`, optional `url`/`chunkLength` | Self-host friendly. Same locale remap as Google.               |
+| `copyResolver`     | `@justanarthur/payload-plugin-translator/resolvers/copy`     | none                            | Returns the source text verbatim. Useful as a fallback or for testing. |
+
+You can supply multiple resolvers — they run in the order declared, and the first one to return
+`success: true` wins for the chunk.
+
+## Writing your own resolver
+
+```ts
+import type { TranslateResolver } from '@justanarthur/payload-plugin-translator/resolvers/types'
+
+export const myResolver: TranslateResolver = {
+  key: 'my-translator',
+  resolve: async ({ localeFrom, localeTo, texts, req }) => {
+    // call your translator of choice
+    return { success: true, translatedTexts: ['...'] }
+  }
+}
+```
+
+`texts` is the flat string array extracted from the doc; you return the same-length array in
+`translatedTexts`. Returning `{ success: false }` makes the job retry.
+
+## Options reference
+
+| Option        | Type                  | Required | Notes                                                                  |
+|---------------|-----------------------|----------|------------------------------------------------------------------------|
+| `collections` | `CollectionSlug[]`    | yes      | Collections to auto-translate.                                         |
+| `globals`     | `GlobalSlug[]`        | yes      | Globals to auto-translate.                                             |
+| `resolvers`   | `TranslateResolver[]` | yes      | Tried in order; first to succeed wins per chunk.                       |
+| `autoTranslate` | `boolean`           | no       | Default `true`. Set `false` to opt out of the auto-translate afterChange hook — useful when you drive translation manually via the `translateOperation` export. |
+| `disabled`    | `boolean`             | no       | Skip the plugin entirely (no overrides, no jobs). Useful in tests.    |
+| `_options.additionalTraverseRichText` | function | no | Hook to extend rich-text traversal — see below.             |
+
+### Rich-text traversal hook
+
+The plugin walks Lexical richText fields itself, but custom Lexical nodes (e.g. blocks the host
+defines for landing pages) won't be visited. `_options.additionalTraverseRichText` lets you register
+a custom walker:
+
+```ts
+translator({
+  // ...
+  _options: {
+    additionalTraverseRichText: ({ root, onText }) => {
+      // call onText(siblingData, attribute?) for every leaf string you find
+      // siblingData mutates the doc tree in-place
+    }
+  }
+})
+```
+
+The hook receives `onText` which mutates the data tree, plus the root node. It's called for every
+richText field before translation begins.
+
+## How it works under the hood
+
+- On plugin init: registers a `translate` Payload **task** and a `translate` **workflow**, swapped
+  Publish/Save buttons per collection/global, and an admin-only endpoint at `/api/translator/translate`.
+- On `afterChange` (when `autoTranslate: true`): the plugin enqueues one workflow run per non-source
+  locale. The job extracts translatable fields, asks each resolver in turn, writes the result back
+  into the `_locales` row.
+- The plugin de-duplicates via `AUTO_TRANSLATE_MARKER` — re-running it on an already-attached hook
+  is a no-op, so it's safe to wrap multiple plugins around the same collection.
+
+## Manual translation
+
+Two escape hatches when you don't want the auto-hook:
+
+```ts
+// the operation (Payload `operation` you can call from custom endpoints)
+import { translateOperation } from '@justanarthur/payload-plugin-translator'
+
+// the job factories (advanced — you usually don't need these directly)
+import { createTranslateTask, createTranslateWorkflow } from '@justanarthur/payload-plugin-translator/jobs'
+```
+
+For most hosts the auto-hook + resolver list is enough.
+
+## Licence
+
+MIT

package/dist/client.css

@@ -0,0 +1,41 @@
+/* src/client/components/CustomButton/styles.css */
+.translator__custom-save-button {
+  display: inline-flex;
+  align-items:  center;
+  gap: .5rem;
+}
+
+/* src/client/components/TranslatorModal/styles.css */
+.translator__modal {
+  position: relative;
+}
+
+.translator__wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1rem;
+}
+
+.translator__close {
+  position: absolute;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  font-size: 1.25rem;
+  line-height: 1;
+  top: .5rem;
+  right: .5rem;
+}
+
+.translator__content {
+  display: flex;
+  flex-direction: column;
+  gap: .75rem;
+}
+
+.translator__buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: .5rem;
+}

package/dist/client.js

@@ -54,7 +54,7 @@ var useTranslator = () => {
 };
 
 // src/client/providers/Translator/TranslatorProvider.tsx
-import { jsxDEV } from "react/jsx-dev-runtime";
+import { jsx } from "react/jsx-runtime";
 var modalSlug = "translator-modal";
 var TranslatorProvider = ({ children }) => {
   const [resolver, setResolver] = useState(null);
@@ -141,7 +141,7 @@ var TranslatorProvider = ({ children }) => {
     }
     closeTranslator();
   };
-  return /* @__PURE__ */ jsxDEV(TranslatorContext.Provider, {
+  return /* @__PURE__ */ jsx(TranslatorContext.Provider, {
     value: {
       closeTranslator,
       localeToTranslateFrom,
@@ -157,22 +157,22 @@ var TranslatorProvider = ({ children }) => {
       submit
     },
     children
-  }, undefined, false, undefined, this);
+  });
 };
 
 // src/client/components/ResolverButton/ResolverButton.tsx
 import { Button, useTranslation as useTranslation2 } from "@payloadcms/ui";
-import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+import { jsx as jsx2 } from "react/jsx-runtime";
 var ResolverButton = ({
   resolver: { key: resolverKey }
 }) => {
   const { openTranslator } = useTranslator();
   const { t } = useTranslation2();
   const handleClick = () => openTranslator({ resolverKey });
-  return /* @__PURE__ */ jsxDEV2(Button, {
+  return /* @__PURE__ */ jsx2(Button, {
     onClick: handleClick,
     children: t(`plugin-translator:resolver_${resolverKey}_buttonLabel`)
-  }, undefined, false, undefined, this);
+  });
 };
 // src/client/components/TranslatorModal/TranslatorModal.tsx
 import { Modal } from "@payloadcms/ui";
@@ -184,32 +184,32 @@ import { Button as Button2, Popup, PopupList, useTranslation as useTranslation4
 // src/client/components/LocaleLabel/LocaleLabel.tsx
 import { getTranslation } from "@payloadcms/translations";
 import { ChevronIcon, useTranslation as useTranslation3 } from "@payloadcms/ui";
-import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
 var baseClass = "localizer-button";
 var LocaleLabel = ({ locale }) => {
   const { i18n, t } = useTranslation3();
-  return /* @__PURE__ */ jsxDEV3("div", {
+  return /* @__PURE__ */ jsxs("div", {
     "aria-label": t("general:locale"),
     className: baseClass,
     children: [
-      /* @__PURE__ */ jsxDEV3("div", {
+      /* @__PURE__ */ jsx3("div", {
         className: `${baseClass}__label`,
         children: `${t("general:locale")}:`
-      }, undefined, false, undefined, this),
+      }),
       "  ",
-      /* @__PURE__ */ jsxDEV3("span", {
+      /* @__PURE__ */ jsx3("span", {
         className: `${baseClass}__current-label`,
         children: `${getTranslation(locale.label, i18n)}`
-      }, undefined, false, undefined, this),
+      }),
       " ",
-      /* @__PURE__ */ jsxDEV3(ChevronIcon, {
+      /* @__PURE__ */ jsx3(ChevronIcon, {
         className: `${baseClass}__chevron`
-      }, undefined, false, undefined, this)
+      })
     ]
-  }, undefined, true, undefined, this);
+  });
 };
 // src/client/components/TranslatorModal/Content.tsx
-import { jsxDEV as jsxDEV4 } from "react/jsx-dev-runtime";
+import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
 var Content = () => {
   const {
     localeToTranslateFrom: localeCodeToTranslateFrom,
@@ -220,21 +220,21 @@ var Content = () => {
   } = useTranslator();
   const { i18n } = useTranslation4();
   const localeToTranslateFrom = localesOptions.find((each) => each.code === localeCodeToTranslateFrom);
-  return /* @__PURE__ */ jsxDEV4("div", {
+  return /* @__PURE__ */ jsxs2("div", {
     className: "translator__content",
     children: [
-      /* @__PURE__ */ jsxDEV4("h2", {
+      /* @__PURE__ */ jsx4("h2", {
         children: resolverT("modalTitle")
-      }, undefined, false, undefined, this),
-      localeToTranslateFrom && /* @__PURE__ */ jsxDEV4(Popup, {
-        button: /* @__PURE__ */ jsxDEV4(LocaleLabel, {
+      }),
+      localeToTranslateFrom && /* @__PURE__ */ jsx4(Popup, {
+        button: /* @__PURE__ */ jsx4(LocaleLabel, {
           locale: localeToTranslateFrom
-        }, undefined, false, undefined, this),
+        }),
         horizontalAlign: "center",
-        render: ({ close }) => /* @__PURE__ */ jsxDEV4(PopupList.ButtonGroup, {
+        render: ({ close }) => /* @__PURE__ */ jsx4(PopupList.ButtonGroup, {
           children: localesOptions.map((option) => {
             const label = getTranslation2(option.label, i18n);
-            return /* @__PURE__ */ jsxDEV4(PopupList.Button, {
+            return /* @__PURE__ */ jsxs2(PopupList.Button, {
               active: option.code === localeCodeToTranslateFrom,
               onClick: () => {
                 setLocaleToTranslateFrom(option.code);
@@ -244,52 +244,52 @@ var Content = () => {
                 label,
                 label !== option.code && ` (${option.code})`
               ]
-            }, option.code, true, undefined, this);
+            }, option.code);
           })
-        }, undefined, false, undefined, this),
+        }),
         verticalAlign: "bottom"
-      }, undefined, false, undefined, this),
-      /* @__PURE__ */ jsxDEV4("div", {
+      }),
+      /* @__PURE__ */ jsxs2("div", {
         className: "translator__buttons",
         children: [
-          /* @__PURE__ */ jsxDEV4(Button2, {
+          /* @__PURE__ */ jsx4(Button2, {
             onClick: () => submit({ emptyOnly: false }),
             children: resolverT("submitButtonLabelFull")
-          }, undefined, false, undefined, this),
-          /* @__PURE__ */ jsxDEV4(Button2, {
+          }),
+          /* @__PURE__ */ jsx4(Button2, {
             onClick: () => submit({ emptyOnly: true }),
             children: resolverT("submitButtonLabelEmpty")
-          }, undefined, false, undefined, this)
+          })
         ]
-      }, undefined, true, undefined, this)
+      })
     ]
-  }, undefined, true, undefined, this);
+  });
 };
 
 // src/client/components/TranslatorModal/TranslatorModal.tsx
-import { jsxDEV as jsxDEV5 } from "react/jsx-dev-runtime";
+import { jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 var TranslatorModal = () => {
   const { closeTranslator, modalSlug: modalSlug2, resolver } = useTranslator();
   if (!resolver)
     return;
-  return /* @__PURE__ */ jsxDEV5(Modal, {
+  return /* @__PURE__ */ jsx5(Modal, {
     className: "translator__modal",
     slug: modalSlug2,
-    children: /* @__PURE__ */ jsxDEV5("div", {
+    children: /* @__PURE__ */ jsxs3("div", {
       className: "translator__wrapper",
       children: [
-        /* @__PURE__ */ jsxDEV5("button", {
+        /* @__PURE__ */ jsx5("button", {
           "aria-label": "Close",
           className: "translator__close",
           onClick: closeTranslator
-        }, undefined, false, undefined, this),
-        /* @__PURE__ */ jsxDEV5(Content, {}, undefined, false, undefined, this)
+        }),
+        /* @__PURE__ */ jsx5(Content, {})
       ]
-    }, undefined, true, undefined, this)
-  }, undefined, false, undefined, this);
+    })
+  });
 };
 // src/client/components/CustomButton/CustomButtonWithTranslator.tsx
-import { jsxDEV as jsxDEV6 } from "react/jsx-dev-runtime";
+import { jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
 
 var CustomButtonWithTranslator = ({ type }) => {
   const { config } = useConfig2();
@@ -297,19 +297,19 @@ var CustomButtonWithTranslator = ({ type }) => {
   const { globalSlug, id } = useDocumentInfo2();
   const resolvers = config.admin?.custom?.translator?.resolvers ?? [];
   if (!id && !globalSlug)
-    return /* @__PURE__ */ jsxDEV6(DefaultButton, {}, undefined, false, undefined, this);
-  return /* @__PURE__ */ jsxDEV6(TranslatorProvider, {
-    children: /* @__PURE__ */ jsxDEV6("div", {
+    return /* @__PURE__ */ jsx6(DefaultButton, {});
+  return /* @__PURE__ */ jsx6(TranslatorProvider, {
+    children: /* @__PURE__ */ jsxs4("div", {
       className: "translator__custom-save-button",
       children: [
-        /* @__PURE__ */ jsxDEV6(TranslatorModal, {}, undefined, false, undefined, this),
-        resolvers.map((resolver) => /* @__PURE__ */ jsxDEV6(ResolverButton, {
+        /* @__PURE__ */ jsx6(TranslatorModal, {}),
+        resolvers.map((resolver) => /* @__PURE__ */ jsx6(ResolverButton, {
           resolver
-        }, resolver.key, false, undefined, this)),
-        /* @__PURE__ */ jsxDEV6(DefaultButton, {}, undefined, false, undefined, this)
+        }, resolver.key)),
+        /* @__PURE__ */ jsx6(DefaultButton, {})
       ]
-    }, undefined, true, undefined, this)
-  }, undefined, false, undefined, this);
+    })
+  });
 };
 
 // src/exports/client.ts

package/dist/index.d.ts

@@ -7,7 +7,6 @@ type TranslateArgs = {
 	emptyOnly?: boolean;
 	globalSlug?: string;
 	id?: number | string;
-	/** active locale */
 	locale: string;
 	localeFrom: string;
 	overrideAccess?: boolean;
@@ -31,9 +30,7 @@ import { Plugin } from "payload";
 import { CollectionSlug, GlobalSlug } from "payload";
 import { PayloadRequest as PayloadRequest3 } from "payload";
 type TranslateResolverArgs = {
-	/** Locale to translate from */
 	localeFrom: string;
-	/** Locale to translate to */
 	localeTo: string;
 	req: PayloadRequest3;
 	texts: string[];
@@ -49,48 +46,12 @@ type TranslateResolver = {
 	resolve: (args: TranslateResolverArgs) => Promise<TranslateResolverResponse> | TranslateResolverResponse;
 };
 type TranslatorConfig = {
-	/**
-	* Collections with the enabled translator in the admin UI
-	*/
 	collections: CollectionSlug[];
-	/**
-	* Disable the plugin
-	*/
 	disabled?: boolean;
-	/**
-	* Globals with the enabled translator in the admin UI
-	*/
 	globals: GlobalSlug[];
-	/**
-	* Add resolvers that you want to include, examples on how to write your own in ./plugin/src/resolvers
-	*/
 	resolvers: TranslateResolver[];
-	/**
-	* Auto-translate every save in the default locale to the other
-	* configured locales via Payload's job queue.
-	*
-	* When `true`, the plugin:
-	* - registers `createTranslateTask()` and `createTranslateWorkflow()`
-	*   in `config.jobs` (idempotent — skips if a task/workflow with
-	*   the same slug is already registered, so host-customized
-	*   factories survive),
-	* - prepends `createAutoTranslateCollectionHook` /
-	*   `createAutoTranslateGlobalHook` to each collection/global
-	*   listed in `collections` / `globals`.
-	*
-	* Default: `false`. Public factories stay exported for hosts that
-	* need per-entity control.
-	*/
 	autoTranslate?: boolean;
-	/**
-	* Advanced traversal options. Mirrors the options accepted by the
-	* internal field walker — keep in sync if you need the latest shape.
-	*/
 	_options?: {
-		/**
-		* Hook invoked while walking each rich-text node. Lets you append
-		* extra text segments to be translated (e.g. custom lexical nodes).
-		*/
 		additionalTraverseRichText?: (args: {
 			onText: (siblingData: Record<string, unknown>, attribute?: string) => void;
 			root: Record<string, unknown>;