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

package/README.md

@@ -1,33 +1,44 @@
 # @focus-reactive/payload-plugin-translator
 
-Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.
+[![npm version](https://img.shields.io/npm/v/@focus-reactive/payload-plugin-translator)](https://www.npmjs.com/package/@focus-reactive/payload-plugin-translator)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/focusreactive/payload-plugins/blob/main/LICENSE)
+
+Translate localized content in **Payload CMS 3** with any provider — a whole document, a whole collection, or a single field — straight from the admin UI.
+
+## About
+
+Payload localizes your content, but it doesn't translate it — you still copy text between locales by hand. This plugin closes that gap: it walks every localized field (including deeply nested groups, arrays, blocks, tabs, and Lexical rich text), sends the text to a translation provider, and writes the result back to the target locale.
+
+It works at three levels — translate the **document** you're editing, **bulk-translate** a collection from its list view, or translate a **single field** in place. Providers are pluggable (OpenAI is built in), and translation runs through a configurable runner (async Payload Jobs by default, or synchronously).
 
 ## Features
 
-- **Deep translation** — translates all localized fields at any nesting level (groups, arrays, blocks, tabs)
-- **Rich text support** — full Lexical rich text translation preserving formatting and structure
-- **Bulk translation** — translate multiple documents at once from collection list view
-- **Progress tracking** — real-time translation status indicators in admin UI
-- **Async processing** — queue-based background jobs (Payload Jobs) or synchronous mode
-- **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)_
+- **Deep translation** — every localized leaf field at any nesting level (groups, arrays, blocks, tabs).
+- **Rich text** — full Lexical translation, preserving formatting and structure.
+- **Three surfaces** — a per-document popup, a bulk-collection dashboard, and a per-field control, toggled via `levels`.
+- **Async or sync** — queue-based background jobs (Payload Jobs) by default, or run inline.
+- **Pluggable providers** — OpenAI built in, or implement your own.
+- **Strategies** — overwrite everything or skip locales that already have content.
+- **Field control** — add a per-field Translate button, or exclude a field from translation.
 
-## Installation
+## Requirements
 
-```bash
-# npm
-npm install @focus-reactive/payload-plugin-translator
+| Peer dependency                | Version        |
+| ------------------------------ | -------------- |
+| `payload`                      | `^3.76.0`      |
+| `@payloadcms/ui`               | `^3.76.0`      |
+| `@payloadcms/richtext-lexical` | `^3.76.0`      |
+| `react`                        | `^18` or `^19` |
 
-# bun
-bun add @focus-reactive/payload-plugin-translator
+Your Payload config must have [localization](https://payloadcms.com/docs/configuration/localization) enabled.
 
-# pnpm
-pnpm add @focus-reactive/payload-plugin-translator
+## Installation
 
-# yarn
-yarn add @focus-reactive/payload-plugin-translator
+```bash
+npm install @focus-reactive/payload-plugin-translator
+# pnpm add @focus-reactive/payload-plugin-translator
+# bun add  @focus-reactive/payload-plugin-translator
+# yarn add @focus-reactive/payload-plugin-translator
 ```
 
 ## Quick Start
@@ -40,390 +51,283 @@ import { Pages } from "./collections/Pages";
 
 export default buildConfig({
   collections: [Posts, Pages],
+  localization: {
+    locales: ["en", "de", "fr"],
+    defaultLocale: "en",
+  },
   plugins: [
     translatorPlugin({
-      collections: [Posts, Pages],
-      translationProvider: createOpenAIProvider({
-        apiKey: process.env.OPENAI_API_KEY,
-      }),
+      collections: [Posts, Pages], // the same config objects you pass to buildConfig
+      translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
       runner: createPayloadJobsRunner(),
     }),
   ],
-  localization: {
-    locales: ["en", "de", "fr"],
-    defaultLocale: "en",
-  },
 });
 ```
 
-## Configuration
-
-### TranslatorPluginConfig
-
-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 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)                                 |
+Open a localized document in the admin — a **Translate** control appears, and the collection list view gains a **bulk** dashboard.
 
-```typescript
-translatorPlugin({
-  collections: [Posts, Pages],
-  translationProvider: createOpenAIProvider({
-    apiKey: process.env.OPENAI_API_KEY,
-  }),
-  runner: createPayloadJobsRunner(),
-  access: { check: ({ req }) => req.user?.role === "admin" },
-  basePath: "/translate",
-});
-```
-
-### Translation Levels
+## Translation surfaces (`levels`)
 
 _Since v0.5.0._
 
-The `levels` option controls which translation surfaces the plugin exposes. Each entry is a factory you import and list:
+`levels` 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).
+| Level               | Surface                                                                                                         | Runs                   |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `documentLevel()`   | A **Translate** popup on the document edit view (one document).                                                 | via `runner`           |
+| `collectionLevel()` | A **bulk dashboard** on the collection list view (many at once).                                                | via `runner`           |
+| `fieldLevel()`      | A per-field **Translate** control + a synchronous `POST {basePath}/field` endpoint (one field). _Since v0.6.0._ | synchronous, no runner |
 
-Both run through the configured `runner` (async Payload Jobs by default, or synchronous via `createSyncRunner()`) and share the same translation REST API.
+Omit `levels` for the default `[documentLevel(), collectionLevel()]` — adopting the option is non-breaking.
 
 ```typescript
-import { translatorPlugin, documentLevel, collectionLevel, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
+import { translatorPlugin, collectionLevel, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
 
 translatorPlugin({
   collections: [Posts],
-  translationProvider: createOpenAIProvider({
-    apiKey: process.env.OPENAI_API_KEY,
-  }),
+  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
+The document and collection levels show a real-time **progress indicator** while jobs run.
 
-Configuration for `createOpenAIProvider()`.
+### Field-level translation
 
-| Property       | Type                      | Required | Default         | Description                                |
-| -------------- | ------------------------- | -------- | --------------- | ------------------------------------------ |
-| `apiKey`       | `string`                  | Yes      | —               | OpenAI API key                             |
-| `model`        | `string \| ChatModel`     | No       | `'gpt-4o'`      | OpenAI model to use for translation        |
-| `systemPrompt` | `SystemPromptBuilder`     | No       | Built-in prompt | Custom function to build the system prompt |
-| `dryRun`       | `boolean \| DryRunConfig` | No       | `false`         | Simulate translations without API calls    |
+_Since v0.6.0._
 
-```typescript
-createOpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY,
-  model: "gpt-4o-mini",
-  systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) => `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
-  dryRun: false,
-});
-```
+`fieldLevel()` adds a per-field **Translate** control. Two steps:
 
-#### SystemPromptBuilder
-
-Function signature for custom system prompt:
+1. Add `fieldLevel()` to `levels` (registers the endpoint).
+2. Wrap the fields that should get a control with `withFieldTranslation(field)`.
 
 ```typescript
-type SystemPromptBuilder = (context: SystemPromptContext) => string;
+import { translatorPlugin, documentLevel, fieldLevel, withFieldTranslation, createOpenAIProvider, createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
 
-type SystemPromptContext = {
-  sourceLang: string;
-  targetLang: string;
-  defaultPrompt: string;
+// In a collection:
+const Posts = {
+  slug: "posts",
+  fields: [withFieldTranslation({ name: "title", type: "text", localized: true })],
 };
+
+// In the plugin:
+translatorPlugin({
+  collections: [Posts],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+  levels: [documentLevel(), fieldLevel()],
+});
 ```
 
-#### DryRunConfig
+The control is an icon button (just above the input) that opens a compact popup with the translation **direction**: a source-locale `Select`, an arrow, then the **current locale** (the fixed target) — `en → fr`. You pick the **source**; the **target is always the locale you're editing**. The server reads the source locale's _saved_ value and translates it into the current locale, so the control needs a **saved document** (it's hidden while creating one). The result is written straight to form state — no save, no queue — and an **Undo** restores the previous value.
 
-When `dryRun` is an object, it allows custom transformation with optional delay:
+Allowed on **`text`, `textarea`, and `richText`** fields (a compile error on other types — pass `{ exclude: true }` for those). For `richText` the Lexical editor re-mounts with the translated content. Fields **inside blocks** are supported: the server reads the source document's `blockType` to resolve the right block schema.
 
-```typescript
-type DryRunTransformer = (text: string) => string | Promise<string>;
+> **Localized `blocks`/`array` containers.** Per-field translation works when the **container is not localized** — the structure is then shared across locales and only the leaf values differ, so wrap the leaves, not the container. If a `blocks`/`array` field is itself `localized`, each locale has an independent structure (different order/content), so a field inside it can't be matched to the source locale by position — the control no-ops with a notice to translate the whole document instead (whole-document translation handles this by matching elements by `id`).
 
-type DryRunConfig = {
-  transform: DryRunTransformer; // Custom transformer function
-  timeout?: number; // Delay in ms (simulates API latency)
-};
-```
+> This direction is intentionally the reverse of the document/collection level (which translates _from_ the current locale _to_ chosen targets): the field control pulls content _into_ the locale you're standing in.
 
-### PayloadJobsRunnerOptions
+## Configuration
 
-Configuration for `createPayloadJobsRunner()`.
+### `translatorPlugin(config)`
 
-| Property    | Type                       | Required | Default                            | Description                                             |
-| ----------- | -------------------------- | -------- | ---------------------------------- | ------------------------------------------------------- |
-| `taskName`  | `string`                   | No       | `'translate_document'`             | Task name in Payload jobs collection                    |
-| `queueName` | `string`                   | No       | `'translations'`                   | Queue name for grouping jobs                            |
-| `autoRun`   | `false \| { cron, limit }` | No       | `{ cron: '* * * * *', limit: 50 }` | Auto-run config, or `false` to disable (for serverless) |
+| Property              | Type                  | Required | Default                                | Description                                                                                                    |
+| --------------------- | --------------------- | -------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `collections`         | `CollectionConfig[]`  | Yes      | —                                      | Collection configs to enable translation for. Must be the **same objects** passed to `buildConfig`, not slugs. |
+| `translationProvider` | `TranslationProvider` | Yes      | —                                      | Provider instance (e.g. `createOpenAIProvider(...)`).                                                          |
+| `runner`              | `TaskRunnerProvider`  | Yes      | —                                      | Runner 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 the plugin's API endpoints.                                                                      |
+| `levels`              | `TranslationLevel[]`  | No       | `[documentLevel(), collectionLevel()]` | Which surfaces to enable — see [Translation surfaces](#translation-surfaces-levels).                           |
 
 ```typescript
-createPayloadJobsRunner({
-  taskName: "translate_document",
-  queueName: "translations",
-  autoRun: {
-    cron: "* * * * *",
-    limit: 50,
-  },
+translatorPlugin({
+  collections: [Posts, Pages],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+  access: { check: ({ req }) => req.user?.role === "admin" },
 });
 ```
 
-### FieldTranslationConfig
+### Providers
 
-Configuration for `withFieldTranslation()` helper or `field.custom.translateKit`.
+#### OpenAI (built in) — `createOpenAIProvider(config)`
 
-| Property  | Type      | Required | Default | Description                         |
-| --------- | --------- | -------- | ------- | ----------------------------------- |
-| `exclude` | `boolean` | No       | `false` | Exclude this field from translation |
+| Property       | Type                      | Required | Default              | Description                                                                                                     |
+| -------------- | ------------------------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `apiKey`       | `string`                  | Yes      | —                    | OpenAI API key.                                                                                                 |
+| `model`        | `string \| ChatModel`     | No       | `'gpt-4o'`           | Model used for translation.                                                                                     |
+| `systemPrompt` | `SystemPromptBuilder`     | No       | Built-in prompt      | Custom system-prompt builder.                                                                                   |
+| `dryRun`       | `boolean \| DryRunConfig` | No       | `false`              | Simulate translations without API calls.                                                                        |
+| `timeout`      | `number`                  | No       | SDK default (10 min) | Per-request timeout (ms). A job blocks on this call, so the 10-min default is usually too long. _Since v0.6.0._ |
+| `maxRetries`   | `number`                  | No       | SDK default (2)      | Max automatic retries on transient errors (429/5xx/network). `0` disables. _Since v0.6.0._                      |
 
 ```typescript
-import { withFieldTranslation } from "@focus-reactive/payload-plugin-translator";
-
-withFieldTranslation({ name: "sku", type: "text", localized: true }, { exclude: true });
+createOpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: "gpt-4o-mini",
+  systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) => `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
+});
 ```
 
-## Translation Strategies
+`systemPrompt` receives `{ sourceLang, targetLang, defaultPrompt }` and returns the prompt string. When `dryRun` is an object it can transform text locally with an optional delay:
 
-When translating, you can choose how to handle existing translations:
+```typescript
+type DryRunConfig = {
+  transform: (text: string) => string | Promise<string>;
+  timeout?: number; // ms, simulates API latency
+};
+```
 
-| Strategy          | Description                                                              |
-| ----------------- | ------------------------------------------------------------------------ |
-| `'overwrite'`     | (Default) Replaces all existing translated content with new translations |
-| `'skip_existing'` | Only translates fields that are empty in the target locale               |
+#### Custom provider
 
-## Important Notes
+Implement the `TranslationProvider` interface — a single `translate` method:
 
-### Explicit `localized: true` for nested fields
+```typescript
+import type { TranslationProvider, TranslationInput, TranslationOutput } from "@focus-reactive/payload-plugin-translator";
 
-Payload CMS allows wrapper fields (group, array, blocks, tabs) to be marked as `localized`, which makes nested fields inherit localization without explicit declaration. However, the plugin only translates **leaf fields** (primitive data fields like text, textarea, richText).
+// TranslationInput / TranslationOutput are Record<number, string> — a map of
+// numeric indices to text. The indices map to positions in the document; the
+// provider MUST return the same keys with translated values.
+class DeepLProvider implements TranslationProvider {
+  constructor(private apiKey: string) {}
 
-For correct plugin operation, you must explicitly set `localized: true` on each nested field you want to translate:
+  async translate(content: TranslationInput, sourceLng: string, targetLng: string): Promise<TranslationOutput | null> {
+    try {
+      const response = await fetch("https://api.deepl.com/v2/translate", {
+        method: "POST",
+        headers: { Authorization: `DeepL-Auth-Key ${this.apiKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ text: Object.values(content), source_lang: sourceLng.toUpperCase(), target_lang: targetLng.toUpperCase() }),
+      });
+      const data = await response.json();
 
-```typescript
-// ❌ Won't work — nested title is not explicitly localized
-{
-  name: 'meta',
-  type: 'group',
-  localized: true,
-  fields: [
-    { name: 'title', type: 'text' }
-  ]
+      const result: TranslationOutput = {};
+      Object.keys(content).forEach((key, i) => {
+        result[key] = data.translations[i].text;
+      });
+      return result;
+    } catch {
+      return null; // null aborts the translation for this chunk
+    }
+  }
 }
 
-// ✅ Correct — title is explicitly localized
-{
-  name: 'meta',
-  type: 'group',
-  localized: true,
-  fields: [
-    { name: 'title', type: 'text', localized: true }
-  ]
-}
+translatorPlugin({
+  collections: [Posts],
+  translationProvider: new DeepLProvider(process.env.DEEPL_API_KEY),
+  runner: createPayloadJobsRunner(),
+});
 ```
 
-### Excluded fields behavior
-
-Using `withFieldTranslation({ ... }, { exclude: true })` does not mean the field will be completely untouched during translation. If the excluded field is empty in the target locale, it will be populated with data from the source locale.
-
-This prevents validation errors when saving translation results (e.g., required fields that should not be translated but must have a value).
+### Runners
 
-### Field exclusion priority over strategy
+Document- and collection-level translation run through a **runner**.
 
-`withFieldTranslation` exclusion takes priority over the `overwrite` strategy. Even when using `overwrite` strategy, excluded fields will:
+#### `createPayloadJobsRunner(options)` (recommended)
 
-- Keep their target value if it exists
-- Copy source value only if target is empty
-- Never be sent to the translation provider
+Background processing via Payload's job queue.
 
-### Preserving completed job status
-
-By default, Payload deletes jobs immediately after completion. This means the "Completed" status won't be visible in the UI. To preserve completed jobs and show their status, add this to your Payload config:
+| Property    | Type                       | Required | Default                            | Description                                                                                           |
+| ----------- | -------------------------- | -------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `taskName`  | `string`                   | No       | `'translate_document'`             | Task name in the Payload jobs collection.                                                             |
+| `queueName` | `string`                   | No       | `'translations'`                   | Queue name for grouping jobs.                                                                         |
+| `autoRun`   | `false \| { cron, limit }` | No       | `{ cron: '* * * * *', limit: 50 }` | Auto-run schedule, or `false` to disable (e.g. for serverless, where you trigger the queue yourself). |
 
 ```typescript
-export default buildConfig({
-  // ... other config
-  jobs: {
-    deleteJobOnComplete: false,
-  },
-});
+createPayloadJobsRunner({ taskName: "translate_document", queueName: "translations", autoRun: { cron: "* * * * *", limit: 50 } });
 ```
 
-## Task Runners
+> By default Payload deletes a job as soon as it completes, so the "Completed" status never shows in the UI. Set `jobs: { deleteJobOnComplete: false }` in your Payload config to keep it.
 
-### PayloadJobsRunner (Recommended)
+#### `createSyncRunner()`
 
-Uses Payload's built-in job queue for background processing:
-
-```typescript
-import { createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
-
-const runner = createPayloadJobsRunner({
-  taskName: "translate_document",
-  queueName: "translations",
-  autoRun: {
-    cron: "* * * * *",
-    limit: 50,
-  },
-});
-```
-
-### SyncRunner
-
-Executes translations synchronously (useful for development or small datasets):
+Runs translations inline (no queue) — handy for development or small datasets.
 
 ```typescript
 import { createSyncRunner } from "@focus-reactive/payload-plugin-translator";
 
-const runner = createSyncRunner();
+translatorPlugin({ collections: [Posts], translationProvider, runner: createSyncRunner() });
 ```
 
-## Translation Providers
+### Field config — `withFieldTranslation(field, config?)`
 
-### OpenAI Provider
+A plain wrap on a `text` / `textarea` / `richText` field adds the per-field Translate control (requires `fieldLevel()`); `{ exclude: true }` opts a field out of translation entirely.
 
-Built-in provider using OpenAI's API:
+| Property  | Type      | Required | Default | Description                          |
+| --------- | --------- | -------- | ------- | ------------------------------------ |
+| `exclude` | `boolean` | No       | `false` | Exclude this field from translation. |
 
 ```typescript
-import { createOpenAIProvider } from "@focus-reactive/payload-plugin-translator";
+import { withFieldTranslation } from "@focus-reactive/payload-plugin-translator";
 
-const provider = createOpenAIProvider({
-  apiKey: process.env.OPENAI_API_KEY,
-  model: "gpt-4o-mini",
-  systemPrompt: ({ defaultPrompt }) => `${defaultPrompt}\nUse formal language.`,
-});
+withFieldTranslation({ name: "title", type: "text", localized: true }); // adds the control
+withFieldTranslation({ name: "sku", type: "text", localized: true }, { exclude: true }); // never translated
 ```
 
-### Custom Provider
+### Strategies
 
-Create your own translation provider by implementing the `TranslationProvider` interface:
+How existing target-locale content is treated when translating:
 
-#### TranslationProvider Interface
+| Strategy          | Behavior                                                   |
+| ----------------- | ---------------------------------------------------------- |
+| `'overwrite'`     | _(Default)_ Replace all existing translated content.       |
+| `'skip_existing'` | Only translate fields that are empty in the target locale. |
 
-| Method      | Signature                                                                                                 | Description                                       |
-| ----------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `translate` | `(content: TranslationInput, sourceLng: string, targetLng: string) => Promise<TranslationOutput \| null>` | Translates content from source to target language |
+## Notes & gotchas
 
-**Important:** The numeric indices in `TranslationInput` must be preserved exactly in `TranslationOutput`. Each index maps to a specific field in the document structure, so the provider must return the same keys with translated values.
+### Mark nested fields `localized: true` explicitly
 
-#### Types
+Payload lets a wrapper field (group, array, blocks, tabs) be `localized`, which makes nested fields inherit localization. The plugin, however, only translates **leaf** fields (text, textarea, richText), so each one you want translated must carry `localized: true` itself:
 
 ```typescript
-// Numeric index representing position in document structure
-type TranslationIndex = number;
-
-// Input: Map of numeric indices to text strings
-type TranslationInput = Record<TranslationIndex, string>;
+// ❌ nested title is not explicitly localized — skipped
+{ name: "meta", type: "group", localized: true, fields: [{ name: "title", type: "text" }] }
 
-// Output: Same indices with translated values
-type TranslationOutput = Record<TranslationIndex, string>;
+// ✅ title is explicitly localized — translated
+{ name: "meta", type: "group", localized: true, fields: [{ name: "title", type: "text", localized: true }] }
 ```
 
-#### Example Implementation
+### Excluded fields are still backfilled
 
-```typescript
-import type { TranslationProvider, TranslationInput, TranslationOutput } from "@focus-reactive/payload-plugin-translator";
+`{ exclude: true }` means "never send this field to the provider" — not "leave it untouched." If an excluded field is empty in the target locale, it's filled from the source locale (so required fields don't fail validation on save). Exclusion takes priority over the `overwrite` strategy: an excluded field keeps its target value if present, copies the source value only when target is empty, and is never sent to the provider.
 
-class DeepLProvider implements TranslationProvider {
-  constructor(private apiKey: string) {}
+### Keeping completed-job status
 
-  async translate(content: TranslationInput, sourceLng: string, targetLng: string): Promise<TranslationOutput | null> {
-    try {
-      // content example: { "0": "Hello", "1": "World" }
-      const texts = Object.values(content);
-
-      const response = await fetch("https://api.deepl.com/v2/translate", {
-        method: "POST",
-        headers: {
-          Authorization: `DeepL-Auth-Key ${this.apiKey}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          text: texts,
-          source_lang: sourceLng.toUpperCase(),
-          target_lang: targetLng.toUpperCase(),
-        }),
-      });
-
-      const data = await response.json();
-
-      // Reconstruct the result with same keys
-      const result: TranslationOutput = {};
-      Object.keys(content).forEach((key, index) => {
-        result[key] = data.translations[index].text;
-      });
-
-      return result;
-    } catch {
-      return null;
-    }
-  }
-}
-
-// Usage
-translatorPlugin({
-  collections: [Posts],
-  translationProvider: new DeepLProvider(process.env.DEEPL_API_KEY),
-  runner: createPayloadJobsRunner(),
-});
-```
-
-## UI Components
-
-The plugin automatically adds:
-
-1. **Document Translation Panel** — Available in the document edit view sidebar
-2. **Bulk Translation Dashboard** — Accessible from collection list view
-3. **Translation Progress Indicator** — Shows real-time translation status
+See the `deleteJobOnComplete: false` note under [Runners](#createpayloadjobsrunneroptions-recommended).
 
 ## TypeScript
 
-All types are exported for TypeScript users:
+The package ships its types. Besides the factories, the following are exported for typing your own code:
 
 ```typescript
 import type {
-  // Plugin config
   TranslatorPluginConfig,
-
-  // Provider types
   TranslationProvider,
   TranslationInput,
   TranslationOutput,
   OpenAIProviderConfig,
   DryRunConfig,
-
-  // Runner types
   TaskRunnerProvider,
   PayloadJobsRunnerOptions,
-
-  // Strategy types
-  TranslationStrategy,
-
-  // Access control
+  TranslationLevel,
+  FieldTranslationConfig,
   AccessGuard,
   AccessGuardRequest,
-
-  // Field config
-  FieldTranslationConfig,
-
-  // Translation levels
-  TranslationLevel,
 } from "@focus-reactive/payload-plugin-translator";
 ```
 
+## Versioning
+
+Every public API is annotated with `@since x.y.z` in its JSDoc, and features carry a `Since vX.Y.Z` note here — so you can tell at a glance whether your installed version has a given capability without cross-referencing the changelog. Releases follow semver.
+
 ## Roadmap
 
-Planned features for future releases:
+- **Global translation dashboard** — translate across all collections from one place, with project-wide progress.
+- **Vercel Cron runner** — a built-in runner for serverless deploys without manual API-route wiring.
+- **Auto-translate on source change** — trigger translation automatically when default-locale content changes.
+
+## License
 
-- **Field-level translation** — Granular translation control allowing users to translate individual fields rather than entire documents
-- **Global translation dashboard** — Translate all collections at once from a single interface, with progress tracking across the entire CMS
-- **Vercel Cron Jobs runner** — Built-in runner for seamless Vercel/serverless deployments without manual API route configuration
-- Auto-translate on source change — Automatically trigger translation when the default locale content is updated
+[MIT](https://github.com/focusreactive/payload-plugins/blob/main/LICENSE) © Focus Reactive.