@captiveorigins/payload-plugin-polyglot 0.0.0-stage → 0.2.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,115 @@
-# 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.
+- **Cheap or free engines.** Claude built in (Haiku by default: in our test a 24,000-character
+  site into 21 languages cost $0.30, about half that through the Batch API, with quality close
+  to Opus); Microsoft Translator (free tier, about 2 million characters a month) built in; 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.
+- **Translation settings in the admin** (no deploy): pause automatic translation, languages not
+  machine-translated, extra never-translate terms, notes for the translator (tone, audience), a
+  glossary of preferred translations per language, a per-sweep character cap, and characters
+  sent per month. The Translations view shows coverage per collection and language, with
+  Translate now.
+- **Tells admins when it stops.** Out of credits, a free quota used up or a refused key stops
+  translation cleanly (nothing is lost) and shows why on the admin dashboard, as ⚠ next to
+  Translations in the menu, and on the Translations view; `onStop` runs once (e.g. to email
+  admins) and everything clears with the next successful translation.
+- **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' | 'paused', … }
+```
+
+Claude instead of Microsoft:
+
+```ts
+import { claudeTranslator } from '@captiveorigins/payload-plugin-polyglot/claude'
+
+translator: claudeTranslator({ instructions: 'A website for reptile keepers.' }) // ANTHROPIC_API_KEY
+// Default model claude-haiku-5-5; pass { model: 'claude-sonnet-5-5' } for more care.
+// syncAll(payload, { useBatch: true }) uses the Message Batches API (half price)
+```
+
+Notes and glossary from Translation settings reach AI engines (Claude); Microsoft ignores them.
+Engines we tried and did not build in: MyMemory (no key, but about 50,000 characters a day),
+Firefox's Bergamot models and MADLAD-400 (free and local, but noticeably weaker, and MADLAD
+repeats sentences), LibreTranslate's public server (now needs a key).
+
+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 |
+| `onStop` | | Called once when translation stops (`{ payload, stop: { reason, message, at } }`), e.g. to email admins |
+| `canManage` | signed-in users | Who sees the Translations view and can Translate now |
+| `canConfigure` | `canManage` | Who may change Translation settings |
+| `settings` | `true` | Add the Translation settings global (`settingsSlug` `polyglot-settings`, `settingsGroup` `Settings`) |
+
+## License
+
+MIT

package/dist/claude.d.ts

@@ -0,0 +1,22 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { type Item, type StopReason, type 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>;
+/** Errors no retry fixes: no credits, key refused, spend limit reached. */
+export declare function stopReasonOf(status: number | undefined, type: string | undefined, message: string): StopReason | undefined;
+export type ClaudeTranslatorOptions = {
+    /** An Anthropic client; default `new Anthropic()` (reads ANTHROPIC_API_KEY). */
+    client?: Anthropic;
+    /** Default `claude-haiku-5-5`: fast, very low cost, and close to Opus for website translation. */
+    model?: string;
+    /** Retry refusals on a fallback model (server-side fallback). Default on, except for Haiku models (not supported). */
+    fallbacks?: boolean;
+    /** 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 (Haiku by default): structured output, placeholder checks, editors' notes and glossary, server-side fallback on refusals where supported, and the Batch API for sweeps. */
+export declare function claudeTranslator(options?: ClaudeTranslatorOptions): Translator;

package/dist/claude.js

@@ -0,0 +1,127 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { QuotaExceededError } from './types.js';
+/** 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;
+}
+/** Errors no retry fixes: no credits, key refused, spend limit reached. */
+export function stopReasonOf(status, type, message) {
+    if (status === 402 || type === 'billing_error' || /credit balance|billing|spend limit|usage limit/i.test(message))
+        return 'credits';
+    if (status === 401 || status === 403 || type === 'authentication_error' || type === 'permission_error')
+        return 'auth';
+    return undefined;
+}
+const stopping = (error) => {
+    if (!(error instanceof Anthropic.APIError))
+        return error;
+    const type = error.error?.error?.type;
+    const reason = stopReasonOf(error.status, type, error.message);
+    return reason ? new QuotaExceededError(`Claude: ${error.message}`, reason) : error;
+};
+const textOf = (m) => m.content.flatMap((b) => (b.type === 'text' ? [b.text] : [])).join('');
+/** Translation with Claude (Haiku by default): structured output, placeholder checks, editors' notes and glossary, server-side fallback on refusals where supported, and the Batch API for sweeps. */
+export function claudeTranslator(options = {}) {
+    const client = () => options.client ?? new Anthropic();
+    const model = options.model ?? 'claude-haiku-5-5';
+    const fallbacks = options.fallbacks ?? !model.includes('haiku');
+    const system = [options.instructions?.trim(), RULES].filter(Boolean).join('\n\n');
+    const params = ({ locale, items, context, keep, sourceLocale, instructions, glossary }) => ({
+        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(', ')}` : ''}${instructions ? `\nNotes from the site's editors: ${instructions}` : ''}${glossary?.length ? `\nUse these translations: ${glossary.map((g) => `${g.term} → ${g.translation}`).join('; ')}` : ''}\n\nItems (JSON):\n${JSON.stringify({ items })}`,
+            },
+        ],
+    });
+    return {
+        async translate(args) {
+            if (!args.items.length)
+                return new Map();
+            let m;
+            try {
+                m = (fallbacks
+                    ? await client()
+                        .beta.messages.stream({ ...params(args), betas: ['server-side-fallback-2026-07-01'], fallbacks: 'default' })
+                        .finalMessage()
+                    : await client().messages.stream(params(args)).finalMessage());
+            }
+            catch (error) {
+                throw stopping(error);
+            }
+            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) })) })
+                .catch((error) => {
+                throw stopping(error);
+            });
+            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());
+            let stop;
+            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));
+                if (result.result.type === 'errored') {
+                    const e = result.result.error.error;
+                    const reason = stopReasonOf(undefined, e?.type, e?.message ?? '');
+                    if (reason)
+                        stop ??= new QuotaExceededError(`Claude: ${e?.message ?? e?.type}`, reason);
+                }
+            }
+            // Nothing came back because of credits or the key: stop and tell admins (what did succeed is kept by the caller next run).
+            if (stop && out.every((m) => m.size === 0))
+                throw stop;
+            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,41 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } 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" })] }), data?.settings?.stop && (_jsxs("div", { role: "alert", style: { border: '1px solid var(--theme-error-500)', background: 'var(--theme-error-50)', color: 'var(--theme-error-800)', borderRadius: 4, padding: 'calc(var(--base) / 2) var(--base)' }, children: [_jsxs("strong", { children: ["Translation stopped ", new Date(data.settings.stop.at).toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' }), "."] }), " ", data.settings.stop.help, _jsx("div", { style: { fontSize: '0.85em', opacity: 0.8, marginTop: 4 }, children: data.settings.stop.message })] })), data?.settings && (_jsxs("p", { style: { margin: 0 }, children: [_jsx("strong", { children: "Automatic translation:" }), ' ', !data.settings.enabled ? 'off here (no engine, or turned off for this environment)' : data.settings.stop ? 'stopped (see above)' : data.settings.paused ? 'paused' : 'on', ' · ', data.settings.charactersThisMonth.toLocaleString(), " characters sent this month", data.settings.skipped.length ? ` · not machine-translated: ${data.settings.skipped.join(', ')}` : '', data.settings.url && (_jsxs(_Fragment, { children: [' · ', _jsx("a", { href: data.settings.url, children: "Translation settings" })] }))] })), 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);
+                                        if (data.settings?.skipped.includes(l))
+                                            return (_jsx("td", { style: { ...cell, color: 'var(--theme-elevation-400)' }, title: "Not machine-translated (Translation settings)", children: "\u2013" }, l));
+                                        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. \u2013 marks languages not machine-translated." })] }));
+}

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,56 @@
+import { APIError, addDataAndFileToRequest } from 'payload';
+import { charactersThisMonth, loadSettings, STOP_HELP } from './settings.js';
+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')) });
+        const s = await loadSettings(req.payload, o);
+        const enabled = o.enabled ? await o.enabled({ payload: req.payload, req }) : true;
+        return Response.json({
+            locales: o.locales,
+            rows,
+            settings: {
+                stop: s.stop ? { ...s.stop, help: STOP_HELP[s.stop.reason] } : null,
+                enabled,
+                paused: s.paused,
+                skipped: [...s.skipLocales],
+                charactersThisMonth: charactersThisMonth(s),
+                url: o.settings ? `${req.payload.config.routes.admin}/globals/${o.settingsSlug}` : null,
+            },
+        });
+    },
+};
+/** 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, force: true }).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,7 @@
+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';
+export { loadSettings, type GlossaryEntry, type Settings } from './settings.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+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';
+export { loadSettings } from './settings.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,69 @@
+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 === 401)
+                        throw new QuotaExceededError(`Microsoft Translator refused the key: ${await res.text()}`, 'auth');
+                    if (res.status === 403)
+                        throw new QuotaExceededError(`Microsoft Translator quota used up: ${await res.text()}`, 'quota');
+                    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,24 @@
+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.
+ * - Translation settings (a global) let admins pause translation, skip languages,
+ *   add never-translate terms, notes and a glossary, and see characters sent.
+ * - When the engine stops (out of credits, quota used up, key refused) admins
+ *   see why on the dashboard, the menu and the Translations view; `onStop`
+ *   runs once (e.g. email); everything clears on the next success.
+ */
+export declare const polyglotPlugin: (options: PolyglotOptions) => Plugin;