@captiveorigins/payload-plugin-polyglot 0.1.0 → 0.2.0

package/README.md

@@ -15,11 +15,22 @@ have, a little at a time.
 - **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.
+- **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.
 
@@ -55,7 +66,7 @@ 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', … }
+const report = await syncAll(payload) // { translated, pending, stopped: 'done' | 'budget' | 'quota' | 'paused', … }
 ```
 
 Claude instead of Microsoft:
@@ -64,9 +75,15 @@ Claude instead of Microsoft:
 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`.
 
@@ -88,6 +105,10 @@ Show visitors what they are reading: `languageStatus(payload, collection, doc, l
 | `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
 

package/dist/claude.d.ts

@@ -1,12 +1,16 @@
 import Anthropic from '@anthropic-ai/sdk';
-import type { Item, Translator } from './types.js';
+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-opus-5-5`. */
+    /** 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)`. */
@@ -14,5 +18,5 @@ export type ClaudeTranslatorOptions = {
     /** 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. */
+/** 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

@@ -1,4 +1,5 @@
 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',
@@ -36,13 +37,29 @@ export function acceptTranslations(source, raw) {
     }
     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: structured output, placeholder checks, server-side fallback on refusals, and the Batch API for sweeps. */
+/** 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-opus-5-5';
+    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 }) => ({
+    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 } },
@@ -50,7 +67,7 @@ export function claudeTranslator(options = {}) {
         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 })}`,
+                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 })}`,
             },
         ],
     });
@@ -58,9 +75,17 @@ export function claudeTranslator(options = {}) {
         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());
+            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));
@@ -69,8 +94,10 @@ export function claudeTranslator(options = {}) {
             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) })),
+            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);
@@ -79,11 +106,21 @@ export function claudeTranslator(options = {}) {
                 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.js

@@ -1,5 +1,5 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 }) {
@@ -31,9 +31,11 @@ export function PolyglotDashboard({ apiRoute, collections, labels }) {
     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) => {
+    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." })] }));
+                                    })] }, 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/endpoints.js

@@ -1,4 +1,5 @@
 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);
@@ -16,7 +17,20 @@ export const coverageEndpoint = {
     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 });
+        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). */
@@ -29,7 +43,7 @@ export const syncEndpoint = {
             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'));
+        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);

package/dist/index.d.ts

@@ -4,3 +4,4 @@ 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

@@ -4,3 +4,4 @@ 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.js

@@ -48,8 +48,10 @@ export function microsoftTranslator(options) {
                         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: ${await res.text()}`);
+                        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());

package/dist/plugin.d.ts

@@ -15,5 +15,10 @@ export declare function localizeFields(fields: Field[], targets: Set<string>, pr
  * - 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;

package/dist/plugin.js

@@ -1,5 +1,6 @@
 import { FILLER, SKIP_KEYS } from './text.js';
 import { coverageEndpoint, syncEndpoint } from './endpoints.js';
+import { loadSettings, settingsGlobal } from './settings.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 = '') {
@@ -67,6 +68,11 @@ const memoryCollection = (slug) => ({
  * - 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 const polyglotPlugin = (options) => (config) => {
     const loc = config.localization;
@@ -91,6 +97,11 @@ export const polyglotPlugin = (options) => (config) => {
         describe: options.describe,
         onPublish: options.onPublish ?? true,
         canManage: options.canManage,
+        canConfigure: options.canConfigure,
+        onStop: options.onStop,
+        settings: options.settings ?? true,
+        settingsSlug: options.settingsSlug ?? 'polyglot-settings',
+        settingsGroup: options.settingsGroup ?? 'Settings',
         adminView: options.adminView ?? true,
         defaultLocale: loc.defaultLocale,
         locales: codes.filter((c) => c !== loc.defaultLocale),
@@ -111,6 +122,8 @@ export const polyglotPlugin = (options) => (config) => {
             return doc;
         if (resolved.enabled && !(await resolved.enabled({ payload: req.payload, req })))
             return doc;
+        if ((await loadSettings(req.payload, resolved)).paused)
+            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');
@@ -141,12 +154,14 @@ export const polyglotPlugin = (options) => (config) => {
         ...config,
         custom: { ...config.custom, polyglot: resolved },
         endpoints: [...(config.endpoints ?? []), coverageEndpoint, syncEndpoint],
+        globals: resolved.settings && !(config.globals ?? []).some((g) => g.slug === resolved.settingsSlug) ? [...(config.globals ?? []), settingsGlobal(resolved, labels)] : config.globals,
         admin: resolved.adminView
             ? {
                 ...config.admin,
                 components: {
                     ...components,
                     afterNavLinks: [...(components.afterNavLinks ?? []), '@captiveorigins/payload-plugin-polyglot/rsc#PolyglotNavLink'],
+                    beforeDashboard: [...(components.beforeDashboard ?? []), '@captiveorigins/payload-plugin-polyglot/rsc#PolyglotStopBanner'],
                     views: { ...components.views, polyglot: { Component: '@captiveorigins/payload-plugin-polyglot/rsc#PolyglotView', path: '/polyglot' } },
                 },
             }

package/dist/rsc/PolyglotView.d.ts

@@ -2,8 +2,13 @@ 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. */
+/** Nav link, for people who may manage translations (⚠ while translation is stopped). */
 export declare function PolyglotNavLink({ payload, user }: {
     payload: Payload;
     user?: unknown;
 }): Promise<React.JSX.Element | null>;
+/** Dashboard banner while translation is stopped (credits, quota, key), for people who may manage translations. */
+export declare function PolyglotStopBanner({ payload, user }: {
+    payload: Payload;
+    user?: unknown;
+}): Promise<React.JSX.Element | null>;

package/dist/rsc/PolyglotView.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DefaultTemplate } from '@payloadcms/next/templates';
 import { PolyglotDashboard } from '../client/PolyglotDashboard.js';
+import { loadSettings, STOP_HELP } from '../settings.js';
 import { polyglotOf } from '../translate.js';
 const labelOf = (payload, slug) => {
     const l = payload.collections[slug]?.config.labels?.plural;
@@ -14,10 +15,26 @@ export async function PolyglotView({ initPageResult, params, searchParams }) {
     const collections = Object.keys(o.collections);
     return (_jsx(DefaultTemplate, { i18n: req.i18n, locale: locale, params: params, payload: req.payload, permissions: permissions, req: req, searchParams: searchParams, user: req.user ?? undefined, visibleEntities: visibleEntities, children: _jsxs("div", { className: "gutter--left gutter--right", style: { paddingBlock: 'calc(var(--base) * 2)' }, children: [_jsx("h1", { children: "Translations" }), allowed ? (_jsx(PolyglotDashboard, { apiRoute: req.payload.config.routes.api, collections: collections, labels: Object.fromEntries(collections.map((c) => [c, labelOf(req.payload, c)])) })) : (_jsx("p", { children: "You don\u2019t have access to translations." }))] }) }));
 }
-/** Nav link, for people who may manage translations. */
-export async function PolyglotNavLink({ payload, user }) {
+const mayManage = async (payload, user) => {
     const o = polyglotOf(payload);
-    if (!user || !(await (o.canManage ?? (() => true))({ req: { user, payload } })))
+    return Boolean(user) && (await (o.canManage ?? (() => true))({ req: { user, payload } }));
+};
+/** Nav link, for people who may manage translations (⚠ while translation is stopped). */
+export async function PolyglotNavLink({ payload, user }) {
+    if (!(await mayManage(payload, user)))
         return null;
-    return (_jsx("a", { className: "nav__link", href: `${payload.config.routes.admin}/polyglot`, style: { display: 'block', marginTop: 'calc(var(--base) / 2)' }, children: _jsx("span", { className: "nav__link-label", children: "Translations" }) }));
+    const { stop } = await loadSettings(payload, polyglotOf(payload));
+    return (_jsx("a", { className: "nav__link", href: `${payload.config.routes.admin}/polyglot`, style: { display: 'block', marginTop: 'calc(var(--base) / 2)' }, title: stop ? 'Translation has stopped' : undefined, children: _jsxs("span", { className: "nav__link-label", children: ["Translations", stop ? ' ⚠' : ''] }) }));
+}
+/** Dashboard banner while translation is stopped (credits, quota, key), for people who may manage translations. */
+export async function PolyglotStopBanner({ payload, user }) {
+    if (!(await mayManage(payload, user)))
+        return null;
+    const { stop } = await loadSettings(payload, polyglotOf(payload));
+    if (!stop)
+        return null;
+    return _jsx(StopNotice, { stop: stop, href: `${payload.config.routes.admin}/polyglot` });
+}
+function StopNotice({ stop, href }) {
+    return (_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)', marginBottom: 'var(--base)' }, children: [_jsxs("strong", { children: ["Translation stopped ", new Date(stop.at).toLocaleString('en', { dateStyle: 'medium', timeStyle: 'short' }), "."] }), " ", STOP_HELP[stop.reason], ' ', href && _jsx("a", { href: href, children: "Open Translations" }), _jsx("div", { style: { fontSize: '0.85em', opacity: 0.8, marginTop: 4 }, children: stop.message })] }));
 }

package/dist/rsc/index.d.ts

@@ -1 +1 @@
-export { PolyglotNavLink, PolyglotView } from './PolyglotView.js';
+export { PolyglotNavLink, PolyglotStopBanner, PolyglotView } from './PolyglotView.js';

package/dist/rsc/index.js

@@ -1 +1 @@
-export { PolyglotNavLink, PolyglotView } from './PolyglotView.js';
+export { PolyglotNavLink, PolyglotStopBanner, PolyglotView } from './PolyglotView.js';

package/dist/settings.d.ts

@@ -0,0 +1,37 @@
+import type { GlobalConfig, Payload } from 'payload';
+import type { EngineStop, QuotaExceededError, ResolvedPolyglot } from './types.js';
+export type GlossaryEntry = {
+    locale: string;
+    term: string;
+    translation: string;
+};
+/** What admins can change without a deploy (the Translation settings global). */
+export type Settings = {
+    paused: boolean;
+    skipLocales: Set<string>;
+    keep: string[];
+    instructions?: string;
+    glossary: GlossaryEntry[];
+    maxCharactersPerRun?: number;
+    usage: {
+        month: string;
+        characters: number;
+    }[];
+    /** Set while translation is stopped (credits, quota, key); cleared by the next success. */
+    stop?: EngineStop;
+};
+export declare function settingsGlobal(o: ResolvedPolyglot, labels: {
+    label: string;
+    value: string;
+}[]): GlobalConfig;
+/** Current settings (defaults when the settings global is off). */
+export declare function loadSettings(payload: Payload, o: ResolvedPolyglot): Promise<Settings>;
+/** Adds characters sent this month (keeps a year of months). */
+export declare function recordUsage(payload: Payload, o: ResolvedPolyglot, characters: number): Promise<void>;
+export declare const charactersThisMonth: (s: Settings) => number;
+/** What admins should do about a stop. */
+export declare const STOP_HELP: Record<EngineStop['reason'], string>;
+/** Records that translation stopped; calls `onStop` once (not again until it has recovered). */
+export declare function recordStop(payload: Payload, o: ResolvedPolyglot, error: QuotaExceededError): Promise<void>;
+/** Clears a recorded stop after a successful translation. */
+export declare function clearStop(payload: Payload, o: ResolvedPolyglot): Promise<void>;

package/dist/settings.js

@@ -0,0 +1,152 @@
+const DEFAULTS = { paused: false, skipLocales: new Set(), keep: [], glossary: [], usage: [] };
+const month = () => new Date().toISOString().slice(0, 7);
+const hasGlobal = (payload, slug) => payload.config.globals?.some((g) => g.slug === slug);
+export function settingsGlobal(o, labels) {
+    const access = async ({ req }) => Boolean(req.user) && (await (o.canConfigure ?? o.canManage ?? (() => true))({ req }));
+    return {
+        slug: o.settingsSlug,
+        label: 'Translation settings',
+        admin: { group: o.settingsGroup, description: 'How automatic translation behaves. Changes apply to the next translation; nothing needs a deploy.' },
+        access: { read: access, update: access },
+        fields: [
+            {
+                name: 'paused',
+                label: 'Pause automatic translation',
+                type: 'checkbox',
+                defaultValue: false,
+                admin: { description: 'Publishing and the scheduled sweep stop translating. “Translate now” in Translations still works.' },
+            },
+            {
+                name: 'skipLocales',
+                label: 'Languages not machine-translated',
+                type: 'select',
+                hasMany: true,
+                options: labels,
+                admin: { description: 'Visitors see the default language there until someone translates by hand. Existing translations stay.' },
+            },
+            {
+                name: 'keep',
+                label: 'Never translate',
+                type: 'textarea',
+                admin: { description: 'One term per line (names, brands, product names). Added to the terms set in code.' },
+            },
+            {
+                name: 'instructions',
+                label: 'Notes for the translator',
+                type: 'textarea',
+                admin: { description: 'Tone, audience, words to prefer, e.g. “Address readers formally in German.” Used by AI engines (Claude); ignored by Microsoft.' },
+            },
+            {
+                name: 'glossary',
+                label: 'Preferred translations',
+                type: 'array',
+                admin: { description: 'How a term should be translated in one language. Used by AI engines (Claude); changing it does not re-translate existing text.' },
+                fields: [
+                    {
+                        type: 'row',
+                        fields: [
+                            { name: 'locale', type: 'select', options: labels, required: true },
+                            { name: 'term', type: 'text', required: true },
+                            { name: 'translation', type: 'text', required: true },
+                        ],
+                    },
+                ],
+            },
+            {
+                name: 'maxCharactersPerRun',
+                label: 'Characters per sweep (cap)',
+                type: 'number',
+                min: 0,
+                admin: { description: `Stops a sweep after sending this many characters; the next run continues. Empty: ${o.maxCharactersPerRun ? `${o.maxCharactersPerRun.toLocaleString('en')} (set in code)` : 'no cap'}.` },
+            },
+            {
+                name: 'stop',
+                label: 'Stopped',
+                type: 'group',
+                admin: {
+                    readOnly: true,
+                    condition: (data) => Boolean(data?.stop?.reason),
+                    description: 'Translation stopped and is waiting for someone to act. Cleared automatically by the next successful translation.',
+                },
+                fields: [
+                    {
+                        type: 'row',
+                        fields: [
+                            { name: 'reason', type: 'select', options: [{ label: 'Out of credits', value: 'credits' }, { label: 'Free quota used up', value: 'quota' }, { label: 'Key refused', value: 'auth' }] },
+                            { name: 'at', type: 'date', admin: { date: { pickerAppearance: 'dayAndTime' } } },
+                        ],
+                    },
+                    { name: 'message', type: 'textarea' },
+                ],
+            },
+            {
+                name: 'usage',
+                label: 'Characters sent, by month',
+                type: 'array',
+                admin: { readOnly: true, description: 'Recorded by Polyglot: characters sent to the translation engine (memory hits and skipped text are free).' },
+                fields: [
+                    {
+                        type: 'row',
+                        fields: [
+                            { name: 'month', type: 'text' },
+                            { name: 'characters', type: 'number' },
+                        ],
+                    },
+                ],
+            },
+        ],
+    };
+}
+/** Current settings (defaults when the settings global is off). */
+export async function loadSettings(payload, o) {
+    if (!hasGlobal(payload, o.settingsSlug))
+        return { ...DEFAULTS, skipLocales: new Set() };
+    const g = (await payload.findGlobal({ slug: o.settingsSlug, depth: 0, overrideAccess: true }));
+    return {
+        paused: Boolean(g.paused),
+        skipLocales: new Set(g.skipLocales ?? []),
+        keep: String(g.keep ?? '')
+            .split('\n')
+            .map((t) => t.trim())
+            .filter(Boolean),
+        instructions: typeof g.instructions === 'string' && g.instructions.trim() ? g.instructions.trim() : undefined,
+        glossary: (g.glossary ?? []).filter((e) => e.locale && e.term && e.translation),
+        maxCharactersPerRun: typeof g.maxCharactersPerRun === 'number' ? g.maxCharactersPerRun : undefined,
+        usage: (g.usage ?? []).map(({ month, characters }) => ({ month, characters })),
+        stop: g.stop?.reason ? g.stop : undefined,
+    };
+}
+/** Adds characters sent this month (keeps a year of months). */
+export async function recordUsage(payload, o, characters) {
+    if (!characters || !hasGlobal(payload, o.settingsSlug))
+        return;
+    const { usage } = await loadSettings(payload, o);
+    const now = month();
+    const rows = usage.some((u) => u.month === now) ? usage.map((u) => (u.month === now ? { ...u, characters: u.characters + characters } : u)) : [...usage, { month: now, characters }];
+    await payload.updateGlobal({ slug: o.settingsSlug, data: { usage: rows.slice(-12) }, overrideAccess: true, context: { polyglot: true } });
+}
+export const charactersThisMonth = (s) => s.usage.find((u) => u.month === month())?.characters ?? 0;
+/** What admins should do about a stop. */
+export const STOP_HELP = {
+    credits: 'The translation engine’s account is out of credits (or hit its spending limit). Add credits, then click Translate now; nothing is lost meanwhile.',
+    quota: 'The engine’s free quota for this period is used up. Translation resumes on its own next period, or upgrade the plan.',
+    auth: 'The engine refused its key (missing, wrong or revoked). Update the key, then click Translate now.',
+};
+/** Records that translation stopped; calls `onStop` once (not again until it has recovered). */
+export async function recordStop(payload, o, error) {
+    const current = (await loadSettings(payload, o)).stop;
+    const stop = { reason: error.reason, message: error.message.slice(0, 1000), at: new Date().toISOString() };
+    payload.logger.error({ reason: stop.reason, message: stop.message }, 'Polyglot: translation stopped');
+    if (current?.reason === stop.reason)
+        return;
+    if (hasGlobal(payload, o.settingsSlug))
+        await payload.updateGlobal({ slug: o.settingsSlug, data: { stop }, overrideAccess: true, context: { polyglot: true } });
+    await o.onStop?.({ payload, stop });
+}
+/** Clears a recorded stop after a successful translation. */
+export async function clearStop(payload, o) {
+    if (!hasGlobal(payload, o.settingsSlug))
+        return;
+    await payload.updateGlobal({ slug: o.settingsSlug, data: { stop: { reason: null, message: null, at: null } }, overrideAccess: true, context: { polyglot: true } });
+    payload.logger.info('Polyglot: translation running again');
+}

package/dist/text.d.ts

@@ -1,4 +1,4 @@
-/** Default placeholder copy that is never translated (nor paid for). */
+/** Default placeholder copy that is never translated (nor paid for): any text with three or more lorem ipsum words, wherever it starts. */
 export declare const FILLER: RegExp;
 /** Keys whose string values are never visible text. */
 export declare const SKIP_KEYS: string[];

package/dist/text.js

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
-/** Default placeholder copy that is never translated (nor paid for). */
-export const FILLER = /lorem ipsum|dolor sit amet|consectetur adipiscing|sed do eiusmod|ut labore et dolore/i;
+const LOREM_WORDS = 'lorem|ipsum|dolor|amet|consectetur|adipiscing|eiusmod|tempor|incididunt|labore|dolore|aliqua|veniam|nostrud|exercitation|ullamco|laboris|aliquip|commodo|consequat|reprehenderit|voluptate|cillum|fugiat|pariatur|excepteur|occaecat|cupidatat|proident|culpa|officia|deserunt|mollit';
+/** Default placeholder copy that is never translated (nor paid for): any text with three or more lorem ipsum words, wherever it starts. */
+export const FILLER = new RegExp(`(?:\\b(?:${LOREM_WORDS})\\b[\\s\\S]*?){3}`, 'i');
 /** Keys whose string values are never visible text. */
 export const SKIP_KEYS = [
     'id', 'url', 'href', 'slug', 'path', 'key', 'type', 'blockType', 'blockName', 'format', 'mode', 'direction', 'version',

package/dist/translate.d.ts

@@ -1,5 +1,6 @@
 import type { Payload } from 'payload';
-import { type DocumentResult, type ResolvedPolyglot } from './types.js';
+import { type Settings } from './settings.js';
+import { type DocumentResult, type ResolvedPolyglot, type StopReason } from './types.js';
 export declare const polyglotOf: (payload: Payload) => ResolvedPolyglot;
 /** Is this document one Polyglot translates? */
 export declare function included(o: ResolvedPolyglot, collection: string, doc: Record<string, unknown>): boolean;
@@ -23,6 +24,7 @@ export declare function translateDocument(payload: Payload, collection: string,
     memoryOnly?: boolean;
     inRequest?: boolean;
     budget?: Budget;
+    settings?: Settings;
 }): Promise<DocumentResult>;
 export type SyncReport = {
     documents: number;
@@ -32,14 +34,18 @@ export type SyncReport = {
     reviewedStale: number;
     failed: number;
     characters: number;
-    stopped: 'done' | 'budget' | 'quota';
+    stopped: 'done' | 'budget' | 'quota' | 'paused';
+    /** With `stopped: 'quota'`: credits, quota or auth (see Translation settings). */
+    stopReason?: StopReason;
 };
 /**
  * Find all content and bring it up to date (the sweep). With a translator that
  * has `batch` and `useBatch`, every missing sentence of every language goes in
  * one batch first (cheaper), then documents are written from memory. Stops
  * cleanly at `maxCharactersPerRun` or when the engine's quota is used up; the
- * next run continues. `dryRun` only reports what is pending.
+ * next run continues. `dryRun` only reports what is pending. Respects the
+ * Translation settings (paused, skipped languages, cap); `force` runs even when
+ * paused (Translate now).
  */
 export declare function syncAll(payload: Payload, opts?: {
     dryRun?: boolean;
@@ -47,6 +53,7 @@ export declare function syncAll(payload: Payload, opts?: {
     limit?: number;
     collections?: string[];
     locales?: string[];
+    force?: boolean;
 }): Promise<SyncReport>;
 /** Translation status of one document in one language, for notices: source, reviewed, stale, machine or pending. */
 export declare function languageStatus(payload: Payload, collection: string, doc: Record<string, unknown>, locale: string): Promise<"source" | "stale" | "pending" | "reviewed" | "machine">;

package/dist/translate.js

@@ -1,4 +1,5 @@
 import { fingerprint, memoryKey, textsOf, visitPaths } from './text.js';
+import { clearStop, loadSettings, recordStop, recordUsage } from './settings.js';
 import { QuotaExceededError } from './types.js';
 export const polyglotOf = (payload) => payload.config.custom?.polyglot;
 const rulesOf = (o) => ({ skip: o.skip, skipKeys: new Set(o.skipKeys) });
@@ -74,13 +75,16 @@ async function remember(payload, o, locale, pairs) {
 }
 const CHUNK = 80;
 const chunks = (list) => Array.from({ length: Math.ceil(list.length / CHUNK) }, (_, i) => list.slice(i * CHUNK, (i + 1) * CHUNK));
-const argsFor = (o, locale, items, context) => ({
+const argsFor = (o, s, locale, items, context) => ({
     locale,
     items,
     context,
     sourceLocale: o.defaultLocale,
-    keep: o.keep,
+    keep: [...new Set([...o.keep, ...s.keep])],
+    instructions: s.instructions,
+    glossary: s.glossary.filter((g) => g.locale === locale).map(({ term, translation }) => ({ term, translation })),
 });
+const localesOf = (o, s, wanted) => (wanted ?? o.locales).filter((l) => !s.skipLocales.has(l));
 /** A per-run character budget (free tiers). */
 export class Budget {
     max;
@@ -103,12 +107,13 @@ export class Budget {
  */
 export async function translateDocument(payload, collection, id, opts = {}) {
     const o = polyglotOf(payload);
+    const settings = opts.settings ?? (await loadSettings(payload, o));
     const result = { translated: [], upToDate: [], reviewedStale: [], failed: [], pending: [] };
     const src = await loadSource(payload, o, collection, id);
     if (!src)
         return result;
     const todo = [];
-    for (const locale of opts.locales ?? o.locales) {
+    for (const locale of localesOf(o, settings, opts.locales)) {
         const row = src.state.get(locale);
         if (row?.hash === src.hash)
             result.upToDate.push(locale);
@@ -124,51 +129,65 @@ export async function translateDocument(payload, collection, id, opts = {}) {
         return { ...result, pending: todo };
     const unique = [...new Set(src.texts)];
     const context = { ...(o.writeContext?.({ inRequest: Boolean(opts.inRequest) }) ?? {}), polyglot: true };
-    for (const [n, locale] of todo.entries()) {
-        try {
-            let known = await recall(payload, o, locale, unique);
-            const missing = unique.filter((t) => !known.has(t));
-            if (missing.length && !opts.memoryOnly) {
-                const chars = missing.reduce((s, t) => s + t.length, 0);
-                if (opts.budget && !opts.budget.allows(chars)) {
-                    result.pending.push(...todo.slice(n));
-                    break;
+    let sent = 0;
+    let recovered = !settings.stop;
+    try {
+        for (const [n, locale] of todo.entries()) {
+            try {
+                let known = await recall(payload, o, locale, unique);
+                const missing = unique.filter((t) => !known.has(t));
+                if (missing.length && !opts.memoryOnly) {
+                    const chars = missing.reduce((s, t) => s + t.length, 0);
+                    if (opts.budget && !opts.budget.allows(chars)) {
+                        result.pending.push(...todo.slice(n));
+                        break;
+                    }
+                    for (const part of chunks(missing)) {
+                        const items = part.map((text, i) => ({ key: String(i), text }));
+                        const out = await engineFor(o, locale).translate(argsFor(o, settings, locale, items, o.describe?.(collection)));
+                        const chars = part.reduce((s, t) => s + t.length, 0);
+                        opts.budget?.spend(chars);
+                        sent += chars;
+                        if (!recovered && out.size) {
+                            recovered = true;
+                            await clearStop(payload, o);
+                        }
+                        await remember(payload, o, locale, items.flatMap((it) => (out.get(it.key) ? [[it.text, out.get(it.key)]] : [])));
+                    }
+                    known = await recall(payload, o, locale, unique);
                 }
-                for (const part of chunks(missing)) {
-                    const items = part.map((text, i) => ({ key: String(i), text }));
-                    const out = await engineFor(o, locale).translate(argsFor(o, locale, items, o.describe?.(collection)));
-                    opts.budget?.spend(part.reduce((s, t) => s + t.length, 0));
-                    await remember(payload, o, locale, items.flatMap((it) => (out.get(it.key) ? [[it.text, out.get(it.key)]] : [])));
+                if (unique.some((t) => !known.has(t))) {
+                    ;
+                    (opts.memoryOnly ? result.pending : result.failed).push(locale);
+                    continue;
                 }
-                known = await recall(payload, o, locale, unique);
+                const data = structuredClone(src.source);
+                visitPaths(data, o.collections[collection], rulesOf(o), (t, set) => set(known.get(t) ?? t));
+                await payload.update({
+                    collection: collection,
+                    id,
+                    locale: locale,
+                    data: { ...data, ...(src.doc._status ? { _status: 'published' } : {}) },
+                    overrideAccess: true,
+                    context,
+                });
+                await saveState(payload, o, collection, id, locale, src.hash, false, src.state.get(locale));
+                result.translated.push(locale);
             }
-            if (unique.some((t) => !known.has(t))) {
-                ;
-                (opts.memoryOnly ? result.pending : result.failed).push(locale);
-                continue;
-            }
-            const data = structuredClone(src.source);
-            visitPaths(data, o.collections[collection], rulesOf(o), (t, set) => set(known.get(t) ?? t));
-            await payload.update({
-                collection: collection,
-                id,
-                locale: locale,
-                data: { ...data, ...(src.doc._status ? { _status: 'published' } : {}) },
-                overrideAccess: true,
-                context,
-            });
-            await saveState(payload, o, collection, id, locale, src.hash, false, src.state.get(locale));
-            result.translated.push(locale);
-        }
-        catch (error) {
-            if (error instanceof QuotaExceededError) {
-                result.pending.push(...todo.slice(n));
-                throw Object.assign(error, { result });
+            catch (error) {
+                if (error instanceof QuotaExceededError) {
+                    result.pending.push(...todo.slice(n));
+                    await recordStop(payload, o, error).catch((err) => payload.logger.warn({ err }, 'Polyglot: could not record the stop'));
+                    throw Object.assign(error, { result });
+                }
+                payload.logger.error({ err: error, collection, id, locale }, 'Polyglot: translation failed');
+                result.failed.push(locale);
             }
-            payload.logger.error({ err: error, collection, id, locale }, 'Polyglot: translation failed');
-            result.failed.push(locale);
         }
     }
+    finally {
+        await recordUsage(payload, o, sent).catch((err) => payload.logger.warn({ err }, 'Polyglot: could not record usage'));
+    }
     return result;
 }
 /**
@@ -176,12 +195,17 @@ export async function translateDocument(payload, collection, id, opts = {}) {
  * has `batch` and `useBatch`, every missing sentence of every language goes in
  * one batch first (cheaper), then documents are written from memory. Stops
  * cleanly at `maxCharactersPerRun` or when the engine's quota is used up; the
- * next run continues. `dryRun` only reports what is pending.
+ * next run continues. `dryRun` only reports what is pending. Respects the
+ * Translation settings (paused, skipped languages, cap); `force` runs even when
+ * paused (Translate now).
  */
 export async function syncAll(payload, opts = {}) {
     const o = polyglotOf(payload);
     const report = { documents: 0, upToDate: 0, translated: 0, pending: 0, reviewedStale: 0, failed: 0, characters: 0, stopped: 'done' };
-    const budget = new Budget(o.maxCharactersPerRun);
+    const settings = await loadSettings(payload, o);
+    if (settings.paused && !opts.force && !opts.dryRun)
+        return { ...report, stopped: 'paused' };
+    const budget = new Budget(settings.maxCharactersPerRun ?? o.maxCharactersPerRun);
     const targets = [];
     for (const collection of Object.keys(o.collections).filter((c) => !opts.collections || opts.collections.includes(c))) {
         const { docs } = await payload.find({ collection: collection, locale: o.defaultLocale, depth: 0, pagination: false, overrideAccess: true, draft: false });
@@ -189,7 +213,7 @@ export async function syncAll(payload, opts = {}) {
             if (included(o, collection, d))
                 targets.push({ collection, id: String(d.id) });
     }
-    const locales = opts.locales ?? o.locales;
+    const locales = localesOf(o, settings, opts.locales);
     const work = opts.limit ? targets.slice(0, opts.limit) : targets;
     const batching = Boolean(opts.useBatch && o.translator.batch && !o.translatorFor && !opts.dryRun);
     if (batching) {
@@ -217,11 +241,23 @@ export async function syncAll(payload, opts = {}) {
                     break;
                 }
                 budget.spend(chars);
-                requests.push(argsFor(o, locale, part.map((text, i) => ({ key: String(i), text }))));
+                requests.push(argsFor(o, settings, locale, part.map((text, i) => ({ key: String(i), text }))));
             }
         }
         if (requests.length) {
-            const results = await o.translator.batch(requests);
+            let results;
+            try {
+                results = await o.translator.batch(requests);
+            }
+            catch (error) {
+                if (!(error instanceof QuotaExceededError))
+                    throw error;
+                await recordStop(payload, o, error);
+                return { ...report, stopped: 'quota', stopReason: error.reason, pending: requests.length };
+            }
+            await recordUsage(payload, o, budget.used);
+            if (settings.stop && results.some((m) => m.size))
+                await clearStop(payload, o);
             for (const [i, r] of requests.entries())
                 await remember(payload, o, r.locale, r.items.flatMap((it) => (results[i]?.get(it.key) ? [[it.text, results[i].get(it.key)]] : [])));
         }
@@ -229,13 +265,14 @@ export async function syncAll(payload, opts = {}) {
     for (const t of work) {
         let r;
         try {
-            r = await translateDocument(payload, t.collection, t.id, { locales, dryRun: opts.dryRun, memoryOnly: batching, budget: batching ? undefined : budget });
+            r = await translateDocument(payload, t.collection, t.id, { locales, dryRun: opts.dryRun, memoryOnly: batching, budget: batching ? undefined : budget, settings });
         }
         catch (error) {
             if (!(error instanceof QuotaExceededError))
                 throw error;
             r = error.result;
             report.stopped = 'quota';
+            report.stopReason = error.reason;
         }
         report.documents++;
         report.upToDate += r.upToDate.length;

package/dist/types.d.ts

@@ -15,15 +15,35 @@ export type TranslateArgs = {
     context?: string;
     sourceLocale: string;
     keep: string[];
+    /** Editors' notes (tone, audience); AI engines use them, others may ignore them. */
+    instructions?: string;
+    /** Preferred translations for this language; AI engines use them, others may ignore them. */
+    glossary?: {
+        term: string;
+        translation: string;
+    }[];
 };
 export type Translator = {
     translate: (args: TranslateArgs) => Promise<Map<string, string>>;
     batch?: (requests: TranslateArgs[]) => Promise<Map<string, string>[]>;
 };
-/** Thrown by a translator when its quota (e.g. a free tier) is used up: the run stops and resumes next time. */
+/** Why an engine stopped: out of credits (paid), a free quota used up, or the key refused. */
+export type StopReason = 'credits' | 'quota' | 'auth';
+/**
+ * Thrown by a translator when it cannot continue until someone acts (credits,
+ * quota, key): the run stops cleanly, admins are told why, and the next run
+ * after the fix continues.
+ */
 export declare class QuotaExceededError extends Error {
-    constructor(message?: string);
+    readonly reason: StopReason;
+    constructor(message?: string, reason?: StopReason);
 }
+/** A recorded stop, shown to admins until a translation succeeds again. */
+export type EngineStop = {
+    reason: StopReason;
+    message: string;
+    at: string;
+};
 export type PolyglotOptions = {
     /** Fields to keep in every language, per collection. Dotted paths reach into arrays/groups: `sections.heading`. */
     collections: Record<string, string[]>;
@@ -66,12 +86,27 @@ export type PolyglotOptions = {
     canManage?: (args: {
         req: PayloadRequest;
     }) => boolean | Promise<boolean>;
+    /** Who may change Translation settings (pause, languages, glossary…). Default: `canManage`. */
+    canConfigure?: (args: {
+        req: PayloadRequest;
+    }) => boolean | Promise<boolean>;
+    /** Add the Translation settings global (admin-editable pause, skipped languages, glossary, usage). Default true. */
+    settings?: boolean;
+    /** Slug of the settings global. Default `polyglot-settings`. */
+    settingsSlug?: string;
+    /** Admin group of the settings global. Default `Settings`. */
+    settingsGroup?: string;
     /** Add the Polyglot admin view (coverage per collection and language, Translate now). Default true. */
     adminView?: boolean;
     /** Translate after a document is published (in Next.js, after the response). Default true. */
     onPublish?: boolean;
+    /** Called once when translation stops (credits, quota, key), e.g. to email admins. Not called again until it has recovered. */
+    onStop?: (args: {
+        payload: Payload;
+        stop: EngineStop;
+    }) => void | Promise<void>;
 };
-export type ResolvedPolyglot = Required<Omit<PolyglotOptions, 'enabled' | 'include' | 'writeContext' | 'describe' | 'translatorFor' | 'maxCharactersPerRun' | 'canManage'>> & Pick<PolyglotOptions, 'enabled' | 'include' | 'writeContext' | 'describe' | 'translatorFor' | 'maxCharactersPerRun' | 'canManage'> & {
+export type ResolvedPolyglot = Required<Omit<PolyglotOptions, 'enabled' | 'include' | 'writeContext' | 'describe' | 'translatorFor' | 'maxCharactersPerRun' | 'canManage' | 'canConfigure' | 'onStop'>> & Pick<PolyglotOptions, 'enabled' | 'include' | 'writeContext' | 'describe' | 'translatorFor' | 'maxCharactersPerRun' | 'canManage' | 'canConfigure' | 'onStop'> & {
     defaultLocale: string;
     locales: string[];
 };

package/dist/types.js

@@ -1,7 +1,13 @@
-/** Thrown by a translator when its quota (e.g. a free tier) is used up: the run stops and resumes next time. */
+/**
+ * Thrown by a translator when it cannot continue until someone acts (credits,
+ * quota, key): the run stops cleanly, admins are told why, and the next run
+ * after the fix continues.
+ */
 export class QuotaExceededError extends Error {
-    constructor(message = 'Translation quota used up') {
+    reason;
+    constructor(message = 'Translation quota used up', reason = 'quota') {
         super(message);
+        this.reason = reason;
         this.name = 'QuotaExceededError';
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@captiveorigins/payload-plugin-polyglot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keeps all your Payload content translated into every language you have, a little at a time: finds content on its own, translates on publish and in a sweep, remembers every sentence, skips placeholder text, and never overwrites a human-reviewed translation.",
   "keywords": [
     "payload",