@captiveorigins/payload-plugin-polyglot 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Captive Origins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# payload-plugin-polyglot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Keeps all your [Payload](https://payloadcms.com) 3 content translated into every language you
+have, a little at a time.
+
+> **Beta (0.x).** Used by Captive Origins. Feedback and issues welcome.
+
+- **Finds your content.** List the fields to translate per collection; they become per-language
+  (Payload localization). Slugs, paths, relationships and images stay shared.
+- **Translates on publish** (in Next.js, after the response, so saving stays fast) and in a
+  **sweep** (`syncAll()`, from a cron or script) that catches anything missed or changed.
+- **Pays only for what changed.** A fingerprint of each document's text skips unchanged
+  documents; a translation memory of every sentence skips known text, so an edit only sends
+  the edited sentences.
+- **Never wastes calls on placeholders.** Lorem ipsum (and friends) is never sent.
+- **Respects people.** Languages marked "Reviewed by a human" are never overwritten; when the
+  source changes they are flagged as stale instead.
+- **Free tiers welcome.** Microsoft Translator (free tier, about 2 million characters a month)
+  built in; Claude built in (with the half-price Batch API for sweeps); bring your own engine.
+  A per-run character cap and clean stops on a used-up quota keep you inside free tiers: the
+  next run continues where the last stopped.
+- **Do-not-translate list** for product names, brands and scientific names.
+- **Engine per language** (`translatorFor`), e.g. one engine for European languages and another
+  for the rest.
+
+## Install
+
+```bash
+npm install @captiveorigins/payload-plugin-polyglot
+```
+
+```ts
+import { microsoftTranslator, polyglotPlugin } from '@captiveorigins/payload-plugin-polyglot'
+
+export default buildConfig({
+  localization: { locales: ['en', 'de', 'fr', 'ja'], defaultLocale: 'en', fallback: true },
+  plugins: [
+    // Last, so it sees collections other plugins add.
+    polyglotPlugin({
+      collections: {
+        pages: ['title', 'layout', 'meta'],
+        posts: ['title', 'content', 'meta'],
+        guides: ['title', 'summary', 'sections.heading', 'sections.body'], // only these parts of each row
+      },
+      translator: microsoftTranslator({ key: process.env.MS_TRANSLATOR_KEY!, region: 'westeurope' }),
+      keep: ['Acme', 'Python regius'],
+      maxCharactersPerRun: 200_000,
+    }),
+  ],
+})
+```
+
+Run the sweep from a cron job or script:
+
+```ts
+import { syncAll } from '@captiveorigins/payload-plugin-polyglot'
+
+const report = await syncAll(payload) // { translated, pending, stopped: 'done' | 'budget' | 'quota', … }
+```
+
+Claude instead of Microsoft:
+
+```ts
+import { claudeTranslator } from '@captiveorigins/payload-plugin-polyglot/claude'
+
+translator: claudeTranslator({ instructions: 'A website for reptile keepers.' }) // ANTHROPIC_API_KEY
+// syncAll(payload, { useBatch: true }) uses the Message Batches API (half price)
+```
+
+Show visitors what they are reading: `languageStatus(payload, collection, doc, locale)` returns
+`source`, `machine`, `reviewed`, `stale` or `pending`.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `collections` | (required) | Fields per collection; dotted paths reach into arrays/groups |
+| `translator` | (required) | `microsoftTranslator()`, `claudeTranslator()` or your own `{ translate, batch? }` |
+| `translatorFor` | | Engine per language |
+| `keep` | `[]` | Terms never translated |
+| `maxCharactersPerRun` | no cap | Stop a sweep after this many characters |
+| `enabled` | always | Whether a request/run may call the engine (keys, environments) |
+| `include` | published docs | Which documents to translate |
+| `skip` | lorem ipsum | Text never sent |
+| `skipKeys` | urls, ids, slugs… | Keys whose strings are never text |
+| `identityFields` | `slug`, `generateSlug`, `path` | Never change when another language is saved |
+| `memorySlug` / `stateSlug` | `polyglot-memory` / `polyglot-state` | Collections it adds |
+| `statusField` | `translations` | Per-document "Reviewed by a human" languages |
+| `writeContext` | | Context for writes (e.g. `{ disableRevalidate: true }` in scripts) |
+| `onPublish` | `true` | Translate after publishing |
+
+## License
+
+MIT

package/dist/claude.d.ts

@@ -0,0 +1,18 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { Item, Translator } from './types.js';
+/** Keeps translations whose key was asked for and whose placeholders match the source. */
+export declare function acceptTranslations(source: Item[], raw: string): Map<string, string>;
+export type ClaudeTranslatorOptions = {
+    /** An Anthropic client; default `new Anthropic()` (reads ANTHROPIC_API_KEY). */
+    client?: Anthropic;
+    /** Default `claude-opus-5-5`. */
+    model?: string;
+    /** What your site is about, tone, terms not to translate… */
+    instructions?: string;
+    /** Name a locale code for the model, e.g. `de` → `German (Deutsch)`. */
+    languageName?: (locale: string) => string;
+    /** Thinking effort. Default `low` (translation rarely needs more). */
+    effort?: 'low' | 'medium' | 'high';
+};
+/** Translation with Claude: structured output, placeholder checks, server-side fallback on refusals, and the Batch API for sweeps. */
+export declare function claudeTranslator(options?: ClaudeTranslatorOptions): Translator;

package/dist/claude.js

@@ -0,0 +1,90 @@
+import Anthropic from '@anthropic-ai/sdk';
+/** Response shape: the same keys, translated (structured output keeps it parseable). */
+const SCHEMA = {
+    type: 'object',
+    properties: {
+        items: {
+            type: 'array',
+            items: { type: 'object', properties: { key: { type: 'string' }, text: { type: 'string' } }, required: ['key', 'text'], additionalProperties: false },
+        },
+    },
+    required: ['items'],
+    additionalProperties: false,
+};
+const RULES = `Rules:
+- Translate every item's "text" into the target language; return every key exactly once, unchanged.
+- Keep placeholders such as {count} or {name} exactly as written, and keep HTML tags and Markdown.
+- Never translate product names, scientific names, codes or URLs.
+- Use the forms of address and punctuation natural for websites in that language.
+- Keep it concise: interface text should fit where the source fits.`;
+const placeholders = (s) => [...s.matchAll(/\{[a-zA-Z0-9_]+\}/g)].map((m) => m[0]).sort().join(',');
+/** Keeps translations whose key was asked for and whose placeholders match the source. */
+export function acceptTranslations(source, raw) {
+    const asked = new Map(source.map((i) => [i.key, i.text]));
+    const accepted = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return accepted;
+    }
+    for (const it of parsed.items ?? []) {
+        const src = asked.get(it.key);
+        if (src !== undefined && typeof it.text === 'string' && it.text.trim() && placeholders(src) === placeholders(it.text))
+            accepted.set(it.key, it.text);
+    }
+    return accepted;
+}
+const textOf = (m) => m.content.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join('');
+/** Translation with Claude: structured output, placeholder checks, server-side fallback on refusals, and the Batch API for sweeps. */
+export function claudeTranslator(options = {}) {
+    const client = () => options.client ?? new Anthropic();
+    const model = options.model ?? 'claude-opus-5-5';
+    const system = [options.instructions?.trim(), RULES].filter(Boolean).join('\n\n');
+    const params = ({ locale, items, context, keep, sourceLocale }) => ({
+        model,
+        max_tokens: 32000,
+        output_config: { effort: options.effort ?? 'low', format: { type: 'json_schema', schema: SCHEMA } },
+        system,
+        messages: [
+            {
+                role: 'user',
+                content: `Source language: ${options.languageName?.(sourceLocale) ?? sourceLocale}. Target language: ${options.languageName?.(locale) ?? locale}.${context ? `\nContext: ${context}` : ''}${keep.length ? `\nNever translate these terms: ${keep.join(', ')}` : ''}\n\nItems (JSON):\n${JSON.stringify({ items })}`,
+            },
+        ],
+    });
+    return {
+        async translate(args) {
+            if (!args.items.length)
+                return new Map();
+            const m = (await client()
+                .beta.messages.stream({ ...params(args), betas: ['server-side-fallback-2026-07-01'], fallbacks: 'default' })
+                .finalMessage());
+            if (m.stop_reason !== 'end_turn')
+                return new Map();
+            return acceptTranslations(args.items, textOf(m));
+        },
+        async batch(requests) {
+            if (!requests.length)
+                return [];
+            const c = client();
+            const created = await c.messages.batches.create({
+                requests: requests.map((r, i) => ({ custom_id: `r${i}`, params: params(r) })),
+            });
+            for (;;) {
+                const b = await c.messages.batches.retrieve(created.id);
+                if (b.processing_status === 'ended')
+                    break;
+                await new Promise((res) => setTimeout(res, 30_000));
+            }
+            const out = requests.map(() => new Map());
+            for await (const result of await c.messages.batches.results(created.id)) {
+                const i = Number(result.custom_id.slice(1));
+                if (result.result.type === 'succeeded' && result.result.message.stop_reason === 'end_turn')
+                    out[i] = acceptTranslations(requests[i].items, textOf(result.result.message));
+            }
+            return out;
+        },
+    };
+}

package/dist/client/PolyglotDashboard.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/** Coverage per collection and language, filtered by collection, with Translate now. */
+export declare function PolyglotDashboard({ apiRoute, collections, labels }: {
+    apiRoute: string;
+    collections: string[];
+    labels: Record<string, string>;
+}): React.JSX.Element;

package/dist/client/PolyglotDashboard.js

@@ -0,0 +1,39 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+/** Coverage per collection and language, filtered by collection, with Translate now. */
+export function PolyglotDashboard({ apiRoute, collections, labels }) {
+    const [filter, setFilter] = useState('');
+    const [data, setData] = useState(null);
+    const [message, setMessage] = useState(null);
+    const load = useCallback(async () => {
+        setData(null);
+        const res = await fetch(`${apiRoute}/polyglot/coverage${filter ? `?collections=${filter}` : ''}`, { credentials: 'include' });
+        if (res.ok)
+            setData(await res.json());
+        else
+            setMessage('Could not load coverage.');
+    }, [apiRoute, filter]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    const run = async (body, what) => {
+        setMessage(`Translating ${what}…`);
+        const res = await fetch(`${apiRoute}/polyglot/sync`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const out = (await res.json().catch(() => null));
+        setMessage(res.ok ? `Started: ${what}. Refresh in a minute to see progress.` : (out?.errors?.[0]?.message ?? 'Could not start.'));
+    };
+    const scope = filter ? [filter] : undefined;
+    const pct = (c, docs) => (docs ? Math.round(((c.translated + c.reviewed) / docs) * 100) : 100);
+    const cell = { padding: '4px 8px', borderBottom: '1px solid var(--theme-elevation-100)', textAlign: 'center' };
+    return (_jsxs("div", { style: { display: 'grid', gap: 'var(--base)' }, children: [_jsxs("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 12, alignItems: 'center' }, children: [_jsxs("label", { children: ["Collection", ' ', _jsxs("select", { value: filter, onChange: (e) => setFilter(e.target.value), style: { padding: '4px 8px' }, children: [_jsx("option", { value: "", children: "All collections" }), collections.map((c) => (_jsx("option", { value: c, children: labels[c] ?? c }, c)))] })] }), _jsx("button", { type: "button", className: "btn btn--style-primary btn--size-small", onClick: () => run({ collections: scope }, filter ? labels[filter] ?? filter : 'everything'), children: "Translate now" }), _jsx("button", { type: "button", className: "btn btn--style-secondary btn--size-small", onClick: () => void load(), children: "Refresh" })] }), message && _jsx("p", { children: message }), !data ? (_jsx("p", { children: "Loading coverage\u2026" })) : (_jsx("div", { style: { overflowX: 'auto' }, children: _jsxs("table", { style: { borderCollapse: 'collapse', fontSize: '0.9em' }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { style: { ...cell, textAlign: 'start' }, children: "Collection" }), data.locales.map((l) => (_jsx("th", { style: cell, children: _jsx("button", { type: "button", title: `Translate ${l} now`, onClick: () => run({ collections: scope, locales: [l] }, l), style: { background: 'none', border: 0, cursor: 'pointer', fontWeight: 600 }, children: l }) }, l)))] }) }), _jsx("tbody", { children: data.rows.map((r) => (_jsxs("tr", { children: [_jsxs("td", { style: { ...cell, textAlign: 'start' }, children: [_jsx("button", { type: "button", title: "Translate this collection now", onClick: () => run({ collections: [r.collection] }, labels[r.collection] ?? r.collection), style: { background: 'none', border: 0, cursor: 'pointer', textAlign: 'start' }, children: labels[r.collection] ?? r.collection }), ' ', _jsxs("span", { style: { color: 'var(--theme-elevation-500)' }, children: ["(", r.documents, ")"] })] }), data.locales.map((l) => {
+                                        const c = r.locales[l];
+                                        const p = pct(c, r.documents);
+                                        return (_jsxs("td", { style: { ...cell, color: p === 100 ? 'var(--theme-success-600)' : undefined }, title: `${c.translated} machine, ${c.reviewed} reviewed, ${c.stale} reviewed but source changed, ${c.pending} pending`, children: [p, "%", c.stale ? ' ⚠' : ''] }, l));
+                                    })] }, r.collection))) })] }) })), _jsx("p", { style: { color: 'var(--theme-elevation-500)', fontSize: '0.85em' }, children: "Percent of documents translated (machine or reviewed). \u26A0 marks reviewed translations whose source has changed. Click a language or collection to translate just that." })] }));
+}

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export { PolyglotDashboard } from './PolyglotDashboard.js';

package/dist/client/index.js

@@ -0,0 +1 @@
+export { PolyglotDashboard } from './PolyglotDashboard.js';

package/dist/endpoints.d.ts

@@ -0,0 +1,5 @@
+import { type Endpoint } from 'payload';
+/** GET /api/polyglot/coverage?collections=pages,posts */
+export declare const coverageEndpoint: Endpoint;
+/** POST /api/polyglot/sync { collections?, locales? }: translate now (after the response in Next.js). */
+export declare const syncEndpoint: Endpoint;

package/dist/endpoints.js

@@ -0,0 +1,42 @@
+import { APIError, addDataAndFileToRequest } from 'payload';
+import { coverage, polyglotOf, syncAll } from './translate.js';
+const allowed = async (req) => {
+    const o = polyglotOf(req.payload);
+    if (!req.user)
+        throw new APIError('Sign in first.', 401, undefined, true);
+    if (!(await (o.canManage ?? (() => true))({ req })))
+        throw new APIError('Not allowed.', 403, undefined, true);
+    return o;
+};
+const list = (v) => (typeof v === 'string' && v ? v.split(',') : Array.isArray(v) ? v.map(String) : undefined);
+/** GET /api/polyglot/coverage?collections=pages,posts */
+export const coverageEndpoint = {
+    path: '/polyglot/coverage',
+    method: 'get',
+    handler: async (req) => {
+        const o = await allowed(req);
+        const rows = await coverage(req.payload, { collections: list(req.searchParams?.get('collections')) });
+        return Response.json({ locales: o.locales, rows });
+    },
+};
+/** POST /api/polyglot/sync { collections?, locales? }: translate now (after the response in Next.js). */
+export const syncEndpoint = {
+    path: '/polyglot/sync',
+    method: 'post',
+    handler: async (req) => {
+        const o = await allowed(req);
+        if (o.enabled && !(await o.enabled({ payload: req.payload, req })))
+            throw new APIError('Translation is turned off here.', 400, undefined, true);
+        await addDataAndFileToRequest(req);
+        const filters = { collections: list(req.data?.collections), locales: list(req.data?.locales) };
+        const run = () => syncAll(req.payload, filters).then((r) => req.payload.logger.info({ ...r, ...filters }, 'Polyglot: translate now'));
+        try {
+            const { after } = await import('next/server.js');
+            after(run);
+            return Response.json({ started: true });
+        }
+        catch {
+            return Response.json({ started: true, report: await run() });
+        }
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { polyglotPlugin, localizeFields } from './plugin.js';
+export { Budget, coverage, included, languageStatus, polyglotOf, syncAll, translateDocument, type CoverageRow, type SyncReport } from './translate.js';
+export { coverageEndpoint, syncEndpoint } from './endpoints.js';
+export { FILLER, SKIP_KEYS, textsOf, visitPaths, visitText, fingerprint, memoryKey } from './text.js';
+export { microsoftTranslator, type MicrosoftTranslatorOptions } from './microsoft.js';
+export { QuotaExceededError, type DocumentResult, type Item, type PolyglotOptions, type ResolvedPolyglot, type TranslateArgs, type Translator } from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { polyglotPlugin, localizeFields } from './plugin.js';
+export { Budget, coverage, included, languageStatus, polyglotOf, syncAll, translateDocument } from './translate.js';
+export { coverageEndpoint, syncEndpoint } from './endpoints.js';
+export { FILLER, SKIP_KEYS, textsOf, visitPaths, visitText, fingerprint, memoryKey } from './text.js';
+export { microsoftTranslator } from './microsoft.js';
+export { QuotaExceededError } from './types.js';

package/dist/microsoft.d.ts

@@ -0,0 +1,17 @@
+import { type Translator } from './types.js';
+export type MicrosoftTranslatorOptions = {
+    /** Azure AI Translator key (the free F0 tier covers about 2 million characters a month). */
+    key: string;
+    /** The resource's region, e.g. `westeurope` (omit for global resources). */
+    region?: string;
+    /** Default `https://api.cognitive.microsofttranslator.com`. */
+    endpoint?: string;
+    /** Map a site locale to Microsoft's code. Defaults handle zh → zh-Hans, zh-TW → zh-Hant. */
+    languageCode?: (locale: string) => string;
+};
+/**
+ * Microsoft Translator (Azure AI Translator, free tier available). Placeholders
+ * like {count} and the `keep` terms are wrapped so they are never translated.
+ * A used-up quota stops the run (QuotaExceededError); rate limits are retried.
+ */
+export declare function microsoftTranslator(options: MicrosoftTranslatorOptions): Translator;

package/dist/microsoft.js

@@ -0,0 +1,67 @@
+import { QuotaExceededError } from './types.js';
+const DEFAULT_CODES = { zh: 'zh-Hans', 'zh-TW': 'zh-Hant', 'zh-CN': 'zh-Hans', nb: 'nb', pt: 'pt' };
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const unescapeHtml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&');
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Microsoft Translator (Azure AI Translator, free tier available). Placeholders
+ * like {count} and the `keep` terms are wrapped so they are never translated.
+ * A used-up quota stops the run (QuotaExceededError); rate limits are retried.
+ */
+export function microsoftTranslator(options) {
+    const endpoint = options.endpoint ?? 'https://api.cognitive.microsofttranslator.com';
+    const code = (l) => options.languageCode?.(l) ?? DEFAULT_CODES[l] ?? l;
+    const protect = (text, keep) => {
+        let html = escapeHtml(text).replace(/\{[a-zA-Z0-9_]+\}/g, (m) => `<span translate="no">${m}</span>`);
+        for (const term of [...keep].sort((a, b) => b.length - a.length))
+            html = html.replace(new RegExp(`(?<![\\w>])${escapeRe(escapeHtml(term))}(?![\\w<])`, 'g'), (m) => `<span translate="no">${m}</span>`);
+        return html;
+    };
+    const unprotect = (html) => unescapeHtml(html.replace(/<span translate="no">([\s\S]*?)<\/span>/g, '$1'));
+    return {
+        async translate({ locale, items, keep, sourceLocale }) {
+            const out = new Map();
+            // Requests are limited to 1,000 items and 50,000 characters.
+            const groups = [[]];
+            let size = 0;
+            for (const it of items) {
+                if (groups.at(-1).length >= 900 || size + it.text.length > 40_000) {
+                    groups.push([]);
+                    size = 0;
+                }
+                groups.at(-1).push(it);
+                size += it.text.length;
+            }
+            for (const group of groups.filter((g) => g.length)) {
+                const url = `${endpoint}/translate?api-version=3.0&from=${encodeURIComponent(code(sourceLocale))}&to=${encodeURIComponent(code(locale))}&textType=html`;
+                for (let attempt = 0;; attempt++) {
+                    const res = await fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Ocp-Apim-Subscription-Key': options.key,
+                            ...(options.region ? { 'Ocp-Apim-Subscription-Region': options.region } : {}),
+                        },
+                        body: JSON.stringify(group.map((it) => ({ Text: protect(it.text, keep) }))),
+                    });
+                    if (res.status === 429 && attempt < 5) {
+                        await new Promise((r) => setTimeout(r, Number(res.headers.get('retry-after') ?? 2 ** attempt * 5) * 1000));
+                        continue;
+                    }
+                    if (res.status === 403)
+                        throw new QuotaExceededError(`Microsoft Translator: ${await res.text()}`);
+                    if (!res.ok)
+                        throw new Error(`Microsoft Translator ${res.status}: ${await res.text()}`);
+                    const body = (await res.json());
+                    group.forEach((it, i) => {
+                        const t = body[i]?.translations[0]?.text;
+                        if (t)
+                            out.set(it.key, unprotect(t));
+                    });
+                    break;
+                }
+            }
+            return out;
+        },
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,19 @@
+import type { Field, Plugin } from 'payload';
+import type { PolyglotOptions } from './types.js';
+/** Marks the listed fields localized (paths ignore tabs/rows; `a.b` reaches into array/group `a`). */
+export declare function localizeFields(fields: Field[], targets: Set<string>, prefix?: string): Field[];
+/**
+ * Polyglot: keeps your content translated into every language of your Payload
+ * localization, a little at a time.
+ *
+ * - The fields you list become per-language (Payload localization).
+ * - Publishing in the default language translates the other languages (in
+ *   Next.js after the response); `syncAll()` sweeps everything (cron/script),
+ *   optionally through the translator's batch API.
+ * - A fingerprint of each document's text skips unchanged documents; a memory of
+ *   every sentence skips known text, so edits only pay for what changed.
+ * - Placeholder copy (lorem ipsum) is never sent; languages marked "Reviewed by a
+ *   human" are never overwritten (they are flagged when the source changes).
+ * - Identity fields (slug, path…) never change when another language is saved.
+ */
+export declare const polyglotPlugin: (options: PolyglotOptions) => Plugin;

package/dist/plugin.js

@@ -0,0 +1,173 @@
+import { FILLER, SKIP_KEYS } from './text.js';
+import { coverageEndpoint, syncEndpoint } from './endpoints.js';
+import { included, translateDocument } from './translate.js';
+/** Marks the listed fields localized (paths ignore tabs/rows; `a.b` reaches into array/group `a`). */
+export function localizeFields(fields, targets, prefix = '') {
+    return fields.map((f) => {
+        if (f.type === 'tabs')
+            return {
+                ...f,
+                tabs: f.tabs.map((t) => 'name' in t && t.name
+                    ? targets.has(`${prefix}${t.name}`)
+                        ? { ...t, localized: true }
+                        : { ...t, fields: localizeFields(t.fields, targets, `${prefix}${t.name}.`) }
+                    : { ...t, fields: localizeFields(t.fields, targets, prefix) }),
+            };
+        if (f.type === 'row' || f.type === 'collapsible')
+            return { ...f, fields: localizeFields(f.fields, targets, prefix) };
+        if (!('name' in f))
+            return f;
+        const path = `${prefix}${f.name}`;
+        if (targets.has(path))
+            return { ...f, localized: true };
+        if ((f.type === 'array' || f.type === 'group') && [...targets].some((t) => t.startsWith(`${path}.`)))
+            return { ...f, fields: localizeFields(f.fields, targets, `${path}.`) };
+        return f;
+    });
+}
+const stateCollection = (slug) => ({
+    slug,
+    labels: { singular: 'Translation status', plural: 'Translation status' },
+    admin: { hidden: true },
+    access: { read: ({ req }) => Boolean(req.user), create: () => false, update: () => false, delete: ({ req }) => Boolean(req.user) },
+    fields: [
+        { name: 'key', type: 'text', required: true, unique: true },
+        { name: 'collection', type: 'text', required: true, index: true },
+        { name: 'doc', type: 'text', required: true, index: true },
+        { name: 'locale', type: 'text', required: true },
+        { name: 'hash', type: 'text', required: true },
+        { name: 'stale', type: 'checkbox', defaultValue: false },
+        { name: 'at', type: 'date' },
+    ],
+    timestamps: false,
+});
+const memoryCollection = (slug) => ({
+    slug,
+    labels: { singular: 'Translation', plural: 'Translation memory' },
+    admin: { useAsTitle: 'source', defaultColumns: ['locale', 'source', 'text', 'createdAt'], description: 'Every machine-translated sentence, reused so nothing is translated twice.' },
+    access: { read: ({ req }) => Boolean(req.user), create: () => false, update: () => false, delete: ({ req }) => Boolean(req.user) },
+    fields: [
+        { name: 'key', type: 'text', required: true, unique: true, admin: { hidden: true } },
+        { name: 'locale', type: 'text', required: true, index: true },
+        { name: 'source', type: 'textarea', required: true },
+        { name: 'text', type: 'textarea', required: true },
+    ],
+    timestamps: true,
+});
+/**
+ * Polyglot: keeps your content translated into every language of your Payload
+ * localization, a little at a time.
+ *
+ * - The fields you list become per-language (Payload localization).
+ * - Publishing in the default language translates the other languages (in
+ *   Next.js after the response); `syncAll()` sweeps everything (cron/script),
+ *   optionally through the translator's batch API.
+ * - A fingerprint of each document's text skips unchanged documents; a memory of
+ *   every sentence skips known text, so edits only pay for what changed.
+ * - Placeholder copy (lorem ipsum) is never sent; languages marked "Reviewed by a
+ *   human" are never overwritten (they are flagged when the source changes).
+ * - Identity fields (slug, path…) never change when another language is saved.
+ */
+export const polyglotPlugin = (options) => (config) => {
+    const loc = config.localization;
+    if (!loc)
+        throw new Error('payload-plugin-polyglot: enable Payload `localization` first.');
+    const codes = loc.locales.map((l) => (typeof l === 'string' ? l : l.code));
+    const resolved = {
+        collections: options.collections,
+        translator: options.translator,
+        enabled: options.enabled,
+        include: options.include,
+        keep: options.keep ?? [],
+        translatorFor: options.translatorFor,
+        maxCharactersPerRun: options.maxCharactersPerRun,
+        skip: options.skip ?? FILLER,
+        skipKeys: [...SKIP_KEYS, ...(options.skipKeys ?? [])],
+        identityFields: options.identityFields ?? ['slug', 'generateSlug', 'path'],
+        memorySlug: options.memorySlug ?? 'polyglot-memory',
+        stateSlug: options.stateSlug ?? 'polyglot-state',
+        statusField: options.statusField ?? 'translations',
+        writeContext: options.writeContext,
+        describe: options.describe,
+        onPublish: options.onPublish ?? true,
+        canManage: options.canManage,
+        adminView: options.adminView ?? true,
+        defaultLocale: loc.defaultLocale,
+        locales: codes.filter((c) => c !== loc.defaultLocale),
+    };
+    const labels = loc.locales.filter((l) => (typeof l === 'string' ? l : l.code) !== loc.defaultLocale).map((l) => typeof l === 'string' ? { label: l, value: l } : { label: typeof l.label === 'string' ? l.label : l.code, value: l.code });
+    const keepIdentity = ({ data, originalDoc, req }) => {
+        if (!originalDoc || !req.locale || req.locale === resolved.defaultLocale || req.locale === 'all')
+            return data;
+        for (const k of resolved.identityFields)
+            if (k in originalDoc)
+                data[k] = originalDoc[k];
+        return data;
+    };
+    const onPublish = async ({ collection, doc, req, context }) => {
+        if (!resolved.onPublish || context?.polyglot || (req.locale && req.locale !== resolved.defaultLocale))
+            return doc;
+        if (!included(resolved, collection.slug, doc))
+            return doc;
+        if (resolved.enabled && !(await resolved.enabled({ payload: req.payload, req })))
+            return doc;
+        const run = () => translateDocument(req.payload, collection.slug, String(doc.id), { inRequest: true }).catch((err) => req.payload.logger.error({ err }, 'Polyglot: publish translation failed'));
+        try {
+            const { after } = await import('next/server.js');
+            after(run);
+        }
+        catch {
+            // Not in a Next.js request (scripts, tests): the sweep picks it up.
+        }
+        return doc;
+    };
+    const statusField = {
+        name: resolved.statusField,
+        type: 'group',
+        admin: { position: 'sidebar', description: 'Machine translations show a notice until a person reviews them.' },
+        fields: [
+            {
+                name: 'reviewed',
+                label: 'Reviewed by a human',
+                type: 'select',
+                hasMany: true,
+                options: labels,
+                admin: { description: 'Reviewed languages are never re-translated automatically.' },
+            },
+        ],
+    };
+    const components = config.admin?.components ?? {};
+    return {
+        ...config,
+        custom: { ...config.custom, polyglot: resolved },
+        endpoints: [...(config.endpoints ?? []), coverageEndpoint, syncEndpoint],
+        admin: resolved.adminView
+            ? {
+                ...config.admin,
+                components: {
+                    ...components,
+                    afterNavLinks: [...(components.afterNavLinks ?? []), '@captiveorigins/payload-plugin-polyglot/rsc#PolyglotNavLink'],
+                    views: { ...components.views, polyglot: { Component: '@captiveorigins/payload-plugin-polyglot/rsc#PolyglotView', path: '/polyglot' } },
+                },
+            }
+            : config.admin,
+        collections: [
+            ...(config.collections ?? []).map((c) => {
+                const targets = resolved.collections[c.slug];
+                if (!targets)
+                    return c;
+                return {
+                    ...c,
+                    fields: [...localizeFields(c.fields, new Set(targets)), statusField],
+                    hooks: {
+                        ...c.hooks,
+                        beforeChange: [...(c.hooks?.beforeChange ?? []), keepIdentity],
+                        afterChange: [...(c.hooks?.afterChange ?? []), onPublish],
+                    },
+                };
+            }),
+            ...((config.collections ?? []).some((c) => c.slug === resolved.memorySlug) ? [] : [memoryCollection(resolved.memorySlug)]),
+            ...((config.collections ?? []).some((c) => c.slug === resolved.stateSlug) ? [] : [stateCollection(resolved.stateSlug)]),
+        ],
+    };
+};

package/dist/rsc/PolyglotView.d.ts

@@ -0,0 +1,9 @@
+import type { AdminViewServerProps, Payload } from 'payload';
+import React from 'react';
+/** /admin/polyglot: coverage per collection and language, Translate now. */
+export declare function PolyglotView({ initPageResult, params, searchParams }: AdminViewServerProps): Promise<React.JSX.Element>;
+/** Nav link, for people who may manage translations. */
+export declare function PolyglotNavLink({ payload, user }: {
+    payload: Payload;
+    user?: unknown;
+}): Promise<React.JSX.Element | null>;