@justanarthur/payload-plugin-translator 1.3.21 → 3.1.0

package/README.md

@@ -0,0 +1,150 @@
+# @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. |
+| `autoTranslateMode` | `'missing' \| 'all'` | no | Default `'missing'`: a publish in the default locale fills empty fields in other locales and keeps existing translations and slugs. `'all'` re-translates everything. |
+| `review`      | `boolean`             | no       | Default `true`. Adds the `/admin/translations` review view, its endpoints and the hidden `translation-status` collection (needs a migration on postgres). |
+| `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 current node as `siblingData`.
+It is called for every node without a `text` property, including `block` and `inlineBlock` nodes.
+
+## 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.
+
+## Reviewing translations
+
+With `review` on, **Translations** appears in the admin nav (`/admin/translations`):
+
+- **Overview**: one row per document (paged, newest first) or global, one column per target locale.
+  Each cell shows the share of translatable fields that have a translation. `404` means the locale
+  has no slug, `↻` means the source changed since the last translation, `✓` means someone reviewed
+  that locale against the current source.
+- **Detail** (click a cell): every translatable field with the source and target text side by side,
+  marked `missing`, `same as source` (likely never translated) or `placeholders differ`, plus the
+  last auto-translate job and its error. Actions: *Translate missing fields*, *Re-translate all*,
+  *Mark reviewed*.
+
+The view only lists collections and globals the signed-in user can read, and the endpoints behind
+the actions require a user.
+
+## 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,225 @@
+/* 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;
+}
+
+/* src/client/components/Review/styles.css */
+.translator-review {
+  padding-bottom: calc(var(--base) * 3);
+}
+
+.translator-review__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--base);
+  margin: calc(var(--base) * 1.5) 0;
+  flex-wrap: wrap;
+}
+
+.translator-review__header h1 {
+  margin: 0;
+}
+
+.translator-review__tabs {
+  display: flex;
+  gap: calc(var(--base) / 2);
+  margin-bottom: var(--base);
+  flex-wrap: wrap;
+}
+
+.translator-review__tab {
+  border: 1px solid var(--theme-elevation-150);
+  color: var(--theme-elevation-800);
+  text-decoration: none;
+  border-radius: 999px;
+  padding: 4px 12px;
+  font-size: 13px;
+}
+
+.translator-review__tab[aria-current="true"] {
+  background: var(--theme-elevation-900);
+  border-color: var(--theme-elevation-900);
+  color: var(--theme-elevation-0);
+}
+
+.translator-review__scroll {
+  overflow-x: auto;
+  border: 1px solid var(--theme-elevation-100);
+  border-radius: var(--style-radius-m);
+}
+
+.translator-review table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 13px;
+}
+
+.translator-review th, .translator-review td {
+  border-bottom: 1px solid var(--theme-elevation-100);
+  text-align: left;
+  vertical-align: top;
+  padding: 8px 10px;
+}
+
+.translator-review th {
+  background: var(--theme-elevation-50);
+  white-space: nowrap;
+  font-weight: 600;
+}
+
+.translator-review tr:last-child td {
+  border-bottom: 0;
+}
+
+.translator-review__doc {
+  min-width: 220px;
+}
+
+.translator-review__doc small {
+  display: block;
+  color: var(--theme-elevation-500);
+}
+
+.translator-review__cell {
+  display: inline-flex;
+  font-variant-numeric: tabular-nums;
+  text-decoration: none;
+  color: var(--theme-elevation-1000);
+  border: 1px solid #0000;
+  border-radius: 999px;
+  align-items:  center;
+  gap: 4px;
+  min-width: 64px;
+  padding: 2px 8px;
+}
+
+.translator-review__cell--ok {
+  background: var(--theme-success-100);
+}
+
+.translator-review__cell--partial {
+  background: var(--theme-warning-100);
+}
+
+.translator-review__cell--missing {
+  background: var(--theme-error-100);
+}
+
+.translator-review__cell--stale {
+  border-color: var(--theme-warning-500);
+}
+
+.translator-review__legend {
+  display: flex;
+  gap: var(--base);
+  color: var(--theme-elevation-600);
+  margin-top: calc(var(--base) / 2);
+  flex-wrap: wrap;
+  font-size: 12px;
+}
+
+.translator-review__pager {
+  display: flex;
+  gap: var(--base);
+  margin-top: var(--base);
+  align-items:  center;
+}
+
+.translator-review__state {
+  white-space: nowrap;
+  border-radius: 999px;
+  padding: 1px 8px;
+  font-size: 12px;
+}
+
+.translator-review__state--ok {
+  background: var(--theme-success-100);
+}
+
+.translator-review__state--missing {
+  background: var(--theme-error-100);
+}
+
+.translator-review__state--identical, .translator-review__state--placeholders {
+  background: var(--theme-warning-100);
+}
+
+.translator-review__text {
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-width: 420px;
+}
+
+.translator-review__text--empty {
+  color: var(--theme-elevation-400);
+  font-style: italic;
+}
+
+.translator-review__path {
+  font-family: var(--font-mono, monospace);
+  color: var(--theme-elevation-600);
+  word-break: break-all;
+  max-width: 240px;
+  font-size: 12px;
+}
+
+.translator-review__meta {
+  display: flex;
+  gap: calc(var(--base) * 1.5);
+  color: var(--theme-elevation-600);
+  margin-bottom: var(--base);
+  flex-wrap: wrap;
+  font-size: 13px;
+}
+
+.translator-review__actions {
+  display: flex;
+  gap: calc(var(--base) / 2);
+  flex-wrap: wrap;
+}
+
+.translator-review__actions .btn {
+  margin: 0;
+}
+
+.translator-review__error {
+  color: var(--theme-error-500);
+}

package/dist/client.d.ts

@@ -1,6 +1,18 @@
-import { JSX as JSX_1kxb } from "react/jsx-runtime";
+import { JSX as JSX_1kxb } from "react";
 type Element_12xgc = JSX_1kxb["Element"];
 declare const CustomButtonWithTranslator: ({ type }: {
 	type: "publish" | "save";
 }) => Element_12xgc;
-export { CustomButtonWithTranslator as default, CustomButtonWithTranslator };
+import { JSX as JSX_1kxb2 } from "react";
+type Element_12xgc2 = JSX_1kxb2["Element"];
+declare const ReviewActions: ({ entity, locale, reviewed }: {
+	entity: string;
+	locale: string;
+	reviewed: boolean;
+}) => Element_12xgc2;
+/** loads the review view styles; the view itself is a server component */
+declare const ReviewStyles: () => null;
+import { JSX as JSX_1kxb3 } from "react";
+type Element_12xgc3 = JSX_1kxb3["Element"];
+declare const TranslationsNavLink: () => Element_12xgc3;
+export { CustomButtonWithTranslator, ReviewActions, ReviewStyles, TranslationsNavLink, CustomButtonWithTranslator as default };