@justanarthur/payload-plugin-translator 1.3.20 → 3.0.3

package/README.md

@@ -1,215 +1,132 @@
-# Translator plugin for Payload
-
-## Install
-
-`pnpm add @justanarthur/payload-plugin-translator`
-
-## Video
-
-https://github.com/r1tsuu/payload-plugin-translator/assets/64744993/d39aeba4-bafc-4c3b-838e-9abc5cf1d64a
-
-## Features:
-
-1. A flexible structure with [resolvers](https://github.com/r1tsuu/payload-plugin-translator/tree/6d0c8098467f9b5e757bf9fd8cfe63ff5da68d5b/plugin/src/resolvers) that allows you to apply any kind of transformation to your localizated data.
-2. Can be used not only from the admin panel, but within Local API as well. [Example of the hook](#example-of-the-hook-that-uses-local-operation-to-copy-the-doc-data-to-other-locales) that automatically fills the other locales data on create
-3. Out of the box supports 3 resolvers - Copy, Google Translate, OpenAI and your own can be written easily.
-4. Works with any nested document structure and 2 Rich Text editor adapters - Lexical and Slate.
-5. You can omit some fields to translate. [Documentation](#omitting-fields)
-
-## Usage:
-
-```ts
-import { buildConfig } from 'payload/config';
-import {
-  translator,
-  copyResolver,
-  googleResolver,
-  openAIResolver,
-  libreResolver,
-} from '@payload-enchants/translator';
-
-export default buildConfig({
-  plugins: [
-    translator({
-      // collections with the enabled translator in the admin UI
-      collections: ['posts', 'small-posts'],
-      // globals with the enabled translator in the admin UI
-      globals: [],
-      // add resolvers that you want to include, examples on how to write your own in ./plugin/src/resolvers
-      resolvers: [
-        copyResolver(),
-        googleResolver({
-          apiKey: process.env.GOOGLE_API_KEY!,
-        }),
-        openAIResolver({
-          apiKey: process.env.OPENAI_KEY!,
-        }),
-        libreResolver({
-          apiKey: process.env.LIBRE_KEY!,
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-## Resolvers
-
-### OpenAI
-
-#### Config:
-
-```ts
-export type OpenAIResolverConfig = {
-  apiKey: string; // API key
-  chunkLength?: number; // How many texts to include into 1 request, default: 100
-  model?: string; // model, default: 'gpt-3.5-turbo'
-  promt?: OpenAIPrompt; // custom prompt
-};
-```
-
-### Custom prompt:
-
-```ts
-export type OpenAIPrompt = (args: {
-  localeFrom: string;
-  localeTo: string;
-  texts: string[];
-}) => string;
-
-// Default
-const defaultPromt: OpenAIPrompt = ({ localeFrom, localeTo, texts }) => {
-  return `Translate me the following array: ${JSON.stringify(texts)} in locale=${localeFrom} to locale ${localeTo}, respond me with the same array structure`;
-};
-```
-
-### Google
-
-#### Config:
-
-```ts
-export type GoogleResolverConfig = {
-  apiKey: string; // API key
-  chunkLength?: number; / /How many texts to include into 1 request, default: 100
-};
-```
-
-### Writing your own
-
-```ts
-import type { TranslateResolver } from '@payload-enchants/translator/resolvers/types';
-
-const myResolver: TranslateResolver = {
-  key: 'my',
-  resolve: async (args) => {
-    const { localeFrom, localeTo, req, texts } = args;
-    // here you can apply any kind of transformation to incoming texts, could be as well API call to a service.
-    const transformed = texts.map((each) => `${each} translated to ${localeTo}`);
-
-    return {
-      success: true,
-      translatedTexts: transformed,
-    };
-  },
-};
-
-export default buildConfig({
-  plugins: [
-    payloadPluginTranslator({
-      collections: ['posts', 'small-posts'],
-      globals: [],
-      resolvers: [myResolver],
-    }),
-  ],
-  // apply translations that will be used for your resolver in the admin UI
-  i18n: {
-    supportedLanguages: { en },
-    translations: {
-      en: {
-        'plugin-translator': {
-          resolver_my_buttonLabel: 'Google Translate',
-          resolver_my_errorMessage: 'An error occurred when trying to translate the data',
-          resolver_my_modalTitle: 'Choose the locale to translate from',
-          resolver_my_submitButtonLabelEmpty: 'Translate only empty fields',
-          resolver_my_submitButtonLabelFull: 'Translate all',
-          resolver_my_successMessage: 'Successfully translated. Press "Save" to apply the changes.',
-        },
-      },
-    },
-  },
-});
-```
-
-## Using the Local API
-
-```ts
-import { translateOperation } from '@payload-enchants/translator';
-
-const translateResult = await translateOperation({
-  collectionSlug: 'posts', // or globalSlug if globals,
-  emptyOnly: false, // optional, should translate all the fields values or only fields that are empty, by default false.
-  id: postDefaultLocale.id, // pass the doc id if it's a collection
-  locale: 'de', // locale to translate to
-  localeFrom: 'en', // locale to translate from
-  payload, // payload instance, you can get it with getPayload or req.payload in hooks
-  req, // PayloadRequest, can be used instead of payload, more appreciable than payload if you have it
-  overrideAccess: false, //
-  resolver: 'copy', // pass resolver key
-  update: true, // optional, should update immediately or just return the translated result, default false
-  data: {}, // Optional, if you want to translate from your data passed here instead of the current doc, should be in "localeFrom" locale, for example { title: "Hello" }
-});
-```
-
-### Example of the hook that uses local operation to copy the doc data to other locales
-
-```ts
-import type { CollectionAfterChangeHook } from 'payload/types';
-import { translateOperation } from '@payload-enchants/translator';
-
-export const copyOtherLocales: CollectionAfterChangeHook = async ({
-  collection,
-  doc,
-  operation,
-  req,
-}) => {
-  if (operation !== 'create') return;
-
-  const locale = req.locale;
-
-  if (!locale || !req.payload.config.localization) return;
-
-  const otherLocales = req.payload.config.localization.locales.filter(
-    (each) => each.code !== locale,
-  );
-
-  const { id } = doc;
-
-  for (const { code } of otherLocales) {
-    await translateOperation({
-      collectionSlug: collection.slug,
-      data: doc,
-      id,
-      locale: code,
-      localeFrom: locale,
-      req,
-      resolver: 'copy',
-      update: true,
-    });
-  }
-};
-```
-
-### Omitting fields
-
-To omit a specific field for translation, simply add `custom.translatorSkip = true` to the field's config.
-
-```ts
-const field = {
-  custom: {
-    translatorSkip: true,
-  },
-  localized: true,
-  name: 'skip',
-  type: 'text',
-};
-```
+# @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.d.ts

@@ -0,0 +1,6 @@
+import { JSX as JSX_1kxb } from "react/jsx-runtime";
+type Element_12xgc = JSX_1kxb["Element"];
+declare const CustomButtonWithTranslator: ({ type }: {
+	type: "publish" | "save";
+}) => Element_12xgc;
+export { CustomButtonWithTranslator as default, CustomButtonWithTranslator };