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

package/dist/plugin.js

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

package/dist/rsc/PolyglotView.d.ts

@@ -0,0 +1,14 @@
+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 (⚠ 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

@@ -0,0 +1,40 @@
+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;
+    return typeof l === 'string' ? l : slug;
+};
+/** /admin/polyglot: coverage per collection and language, Translate now. */
+export async function PolyglotView({ initPageResult, params, searchParams }) {
+    const { req, permissions, visibleEntities, locale } = initPageResult;
+    const o = polyglotOf(req.payload);
+    const allowed = Boolean(req.user) && (await (o.canManage ?? (() => true))({ req }));
+    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." }))] }) }));
+}
+const mayManage = async (payload, user) => {
+    const o = polyglotOf(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;
+    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

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

package/dist/rsc/index.js

@@ -0,0 +1 @@
+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

@@ -0,0 +1,27 @@
+/** 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[];
+export type Json = string | number | boolean | null | Json[] | {
+    [k: string]: Json;
+};
+type Rules = {
+    skip: RegExp;
+    skipKeys: Set<string>;
+};
+/**
+ * Visits every visible string in a value: words of rich-text (Lexical) text
+ * nodes, and plain strings outside skipped keys. `set` replaces it in place.
+ */
+export declare function visitText(node: Json, rules: Rules, onText: (text: string, set: (t: string) => void) => void): void;
+/** All visible strings of the listed paths, in order. */
+export declare function textsOf(source: Record<string, Json>, paths: string[], rules: Rules): string[];
+export declare const fingerprint: (texts: string[]) => string;
+export declare const memoryKey: (locale: string, text: string) => string;
+/**
+ * Visits the text of exactly the listed paths of a document: `title` visits the
+ * whole field; `sections.heading` only the heading of each section (other fields
+ * of the rows, shared across languages, are never touched).
+ */
+export declare function visitPaths(source: Record<string, Json>, paths: string[], rules: Rules, onText: (text: string, set: (t: string) => void) => void): void;
+export {};

package/dist/text.js

@@ -0,0 +1,83 @@
+import crypto from 'node:crypto';
+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',
+    'style', 'detail', 'relationTo', 'value', 'tag', 'listType', 'textFormat', 'textStyle', 'linkType', 'appearance',
+    'reference', 'icon', 'status', 'newTab', 'indent', 'start', 'checked', 'language', 'mediaType', 'collection',
+];
+/** Strings that are links, ids, slugs, option values or dates rather than text. */
+const NOT_TEXT = /^(https?:\/\/|mailto:|\/|#)|^[a-f0-9]{24}$|^[a-z0-9]+(-[a-z0-9]+)*$|^\d{4}-\d{2}-\d{2}/;
+const isText = (v, r) => Boolean(v.trim()) && !NOT_TEXT.test(v.trim()) && !r.skip.test(v);
+/**
+ * Visits every visible string in a value: words of rich-text (Lexical) text
+ * nodes, and plain strings outside skipped keys. `set` replaces it in place.
+ */
+export function visitText(node, rules, onText) {
+    if (Array.isArray(node)) {
+        node.forEach((child, i) => {
+            if (typeof child === 'string') {
+                if (isText(child, rules))
+                    onText(child, (t) => (node[i] = t));
+            }
+            else
+                visitText(child, rules, onText);
+        });
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const lexicalText = node.type === 'text' && typeof node.text === 'string';
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === 'string') {
+            const wanted = lexicalText ? k === 'text' && !rules.skip.test(v) && Boolean(v.trim()) : !rules.skipKeys.has(k) && isText(v, rules);
+            if (wanted)
+                onText(v, (t) => (node[k] = t));
+        }
+        else if (v && typeof v === 'object') {
+            if (lexicalText || rules.skipKeys.has(k))
+                continue;
+            visitText(v, rules, onText);
+        }
+    }
+}
+/** All visible strings of the listed paths, in order. */
+export function textsOf(source, paths, rules) {
+    const found = [];
+    visitPaths(source, paths, rules, (t) => found.push(t));
+    return found;
+}
+export const fingerprint = (texts) => crypto.createHash('sha256').update(JSON.stringify(texts)).digest('hex').slice(0, 32);
+export const memoryKey = (locale, text) => crypto.createHash('sha256').update(`${locale}\u0000${text}`).digest('hex');
+/**
+ * Visits the text of exactly the listed paths of a document: `title` visits the
+ * whole field; `sections.heading` only the heading of each section (other fields
+ * of the rows, shared across languages, are never touched).
+ */
+export function visitPaths(source, paths, rules, onText) {
+    const walk = (holder, segs) => {
+        const [head, ...rest] = segs;
+        if (!head || !(head in holder))
+            return;
+        const value = holder[head];
+        if (!rest.length) {
+            if (typeof value === 'string') {
+                if (isText(value, rules))
+                    onText(value, (t) => (holder[head] = t));
+            }
+            else if (value && typeof value === 'object')
+                visitText(value, rules, onText);
+            return;
+        }
+        if (Array.isArray(value))
+            for (const row of value)
+                if (row && typeof row === 'object' && !Array.isArray(row))
+                    walk(row, rest);
+                else if (value && typeof value === 'object' && !Array.isArray(value))
+                    walk(value, rest);
+    };
+    for (const p of paths)
+        walk(source, p.split('.'));
+}

package/dist/translate.d.ts

@@ -0,0 +1,74 @@
+import type { Payload } from 'payload';
+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;
+/** A per-run character budget (free tiers). */
+export declare class Budget {
+    private readonly max?;
+    used: number;
+    constructor(max?: number | undefined);
+    allows(chars: number): boolean;
+    spend(chars: number): void;
+}
+/**
+ * Bring one document up to date in every language (or `locales`). Unchanged
+ * source costs nothing (the fingerprint matches); known sentences come from
+ * memory; only new ones reach the translator. Reviewed languages are never
+ * overwritten: they are marked stale. Languages are written one at a time.
+ */
+export declare function translateDocument(payload: Payload, collection: string, id: string, opts?: {
+    locales?: string[];
+    dryRun?: boolean;
+    memoryOnly?: boolean;
+    inRequest?: boolean;
+    budget?: Budget;
+    settings?: Settings;
+}): Promise<DocumentResult>;
+export type SyncReport = {
+    documents: number;
+    upToDate: number;
+    translated: number;
+    pending: number;
+    reviewedStale: number;
+    failed: number;
+    characters: number;
+    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. Respects the
+ * Translation settings (paused, skipped languages, cap); `force` runs even when
+ * paused (Translate now).
+ */
+export declare function syncAll(payload: Payload, opts?: {
+    dryRun?: boolean;
+    useBatch?: boolean;
+    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">;
+export type CoverageRow = {
+    collection: string;
+    documents: number;
+    /** Per language: up to date, waiting, reviewed by a human, reviewed but the source changed. */
+    locales: Record<string, {
+        translated: number;
+        pending: number;
+        reviewed: number;
+        stale: number;
+    }>;
+};
+/** Translation coverage per collection and language (for the admin view and reports). */
+export declare function coverage(payload: Payload, opts?: {
+    collections?: string[];
+}): Promise<CoverageRow[]>;