@purposeinplay/payload-ai-translate 0.1.0

package/dist/client/translation-progress.js

@@ -0,0 +1,297 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { toast, useConfig } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * How long to keep the progress bar visible after the job finishes, so the
+ * user sees the bar fill to 100% instead of it vanishing on the last tick.
+ */ const COMPLETION_HOLD_MS = 500;
+const SHIMMER_KEYFRAMES = `
+@keyframes ai-translate-shimmer {
+  0%   { background-position: 0% 0; }
+  100% { background-position: 200% 0; }
+}
+@keyframes ai-translate-pulse {
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.6; }
+}
+@keyframes ai-translate-indeterminate {
+  0%   { left: -35%; right: 100%; }
+  60%  { left: 100%; right: -35%; }
+  100% { left: 100%; right: -35%; }
+}
+`;
+const initialState = {
+    completed: [],
+    failed: [],
+    total: 0,
+    status: 'idle'
+};
+export function TranslationProgress({ jobId, collectionSlug, globalSlug, docId, onComplete }) {
+    const { config } = useConfig();
+    const [state, setState] = useState(initialState);
+    // The status we actually render. Lags behind `state.status` by
+    // COMPLETION_HOLD_MS on the running → completed/failed transition so the
+    // bar can visibly fill to 100% before being replaced by the success line.
+    const [displayStatus, setDisplayStatus] = useState('idle');
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    const buildUrl = useCallback(()=>{
+        const { routes } = config;
+        const apiRoute = routes?.api ?? '/api';
+        const query = jobId ? `?jobId=${encodeURIComponent(jobId)}` : docId ? `?docId=${encodeURIComponent(String(docId))}` : null;
+        if (!query) return null;
+        const slugSegment = globalSlug ? `/globals/${globalSlug}` : collectionSlug ? `/${collectionSlug}` : null;
+        if (!slugSegment) return null;
+        const path = `${slugSegment}/ai-translate/progress${query}`;
+        return formatAdminURL({
+            apiRoute,
+            path
+        });
+    }, [
+        config,
+        collectionSlug,
+        globalSlug,
+        jobId,
+        docId
+    ]);
+    useEffect(()=>{
+        if (typeof EventSource === 'undefined') return;
+        const url = buildUrl();
+        if (!url) return;
+        const es = new EventSource(url, {
+            withCredentials: true
+        });
+        function handleProgress(e) {
+            try {
+                const data = JSON.parse(e.data);
+                setState({
+                    completed: data.completed,
+                    failed: data.failed,
+                    total: data.total,
+                    status: data.status
+                });
+            } catch  {
+            // Malformed event — ignore
+            }
+        }
+        function handleComplete(e) {
+            try {
+                const data = JSON.parse(e.data);
+                setState({
+                    completed: data.completed,
+                    failed: data.failed,
+                    total: data.total,
+                    status: data.status
+                });
+                if (data.failed.length === 0) {
+                    toast.success(`Translated to ${data.completed.length} locale(s)`);
+                } else {
+                    // Headline names the actual locales that failed — vague counts
+                    // ("1/2 locales translated") force the user to look elsewhere
+                    // for which one and why. Each per-locale toast carries the
+                    // provider error directly. Sonner stacks them so they dismiss
+                    // independently.
+                    const failedCodes = data.failed.map((f)=>f.locale).join(', ');
+                    if (data.completed.length > 0) {
+                        toast.error(`Translated to ${data.completed.length} of ${data.total} locales — failed: ${failedCodes}`);
+                    } else {
+                        toast.error(`Translation failed for: ${failedCodes}`);
+                    }
+                    for (const f of data.failed){
+                        toast.error(`Failed: ${f.locale} — ${(f.error ?? 'unknown error').slice(0, 200)}`);
+                    }
+                }
+                // Delay parent's onComplete by the same hold so the parent doesn't
+                // unmount this component before the bar finishes filling.
+                setTimeout(()=>{
+                    onCompleteRef.current?.();
+                }, COMPLETION_HOLD_MS);
+            } catch  {
+            // Malformed event — ignore
+            }
+        }
+        es.addEventListener('progress', handleProgress);
+        es.addEventListener('complete', handleComplete);
+        es.onerror = ()=>{
+        // EventSource auto-reconnects; if it fails permanently the browser closes it
+        };
+        return ()=>{
+            es.removeEventListener('progress', handleProgress);
+            es.removeEventListener('complete', handleComplete);
+            es.close();
+        };
+    }, [
+        buildUrl
+    ]);
+    // Drive displayStatus from state.status. When the job finishes, hold the
+    // running view briefly so the user sees the bar fill — otherwise the bar
+    // jumps from a partial value straight into the success line.
+    useEffect(()=>{
+        if (state.status === 'idle' || state.status === 'running') {
+            setDisplayStatus(state.status);
+            return;
+        }
+        const timer = setTimeout(()=>{
+            setDisplayStatus(state.status);
+        }, COMPLETION_HOLD_MS);
+        return ()=>clearTimeout(timer);
+    }, [
+        state.status
+    ]);
+    // Nothing to render if SSR or no EventSource support
+    if (typeof EventSource === 'undefined') return null;
+    // Nothing to render in idle state
+    if (displayStatus === 'idle' || state.total === 0) return null;
+    // While we're holding on the "running" view after the job already finished,
+    // pin the bar to 100% so it visibly fills before the view swaps out.
+    const finishedButHolding = displayStatus === 'running' && state.status !== 'running';
+    const done = state.completed.length + state.failed.length;
+    const percent = finishedButHolding ? 100 : state.total > 0 ? Math.round(done / state.total * 100) : 0;
+    // Build set of all locale codes for rendering
+    const completedSet = new Set(state.completed);
+    const failedMap = new Map(state.failed.map((f)=>[
+            f.locale,
+            f.error
+        ]));
+    return /*#__PURE__*/ _jsxs("div", {
+        style: {
+            padding: '12px 16px',
+            backgroundColor: 'var(--theme-elevation-50)',
+            border: '1px solid var(--theme-elevation-200)',
+            borderRadius: '4px',
+            fontSize: '13px',
+            color: 'var(--theme-text)'
+        },
+        children: [
+            displayStatus === 'running' && /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsx("style", {
+                        children: SHIMMER_KEYFRAMES
+                    }),
+                    /*#__PURE__*/ _jsxs("div", {
+                        style: {
+                            marginBottom: '8px',
+                            fontWeight: 500
+                        },
+                        children: [
+                            "Translating: ",
+                            finishedButHolding ? state.total : done,
+                            "/",
+                            state.total,
+                            " locales"
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("div", {
+                        style: {
+                            position: 'relative',
+                            width: '100%',
+                            height: '6px',
+                            backgroundColor: 'var(--theme-elevation-200)',
+                            borderRadius: '3px',
+                            overflow: 'hidden',
+                            marginBottom: '8px'
+                        },
+                        children: done === 0 && !finishedButHolding ? // Indeterminate slider — uses left/right anchors so the
+                        // pill is always 35% wide regardless of track width.
+                        /*#__PURE__*/ _jsx("div", {
+                            style: {
+                                position: 'absolute',
+                                top: 0,
+                                bottom: 0,
+                                borderRadius: '3px',
+                                backgroundColor: 'var(--theme-success-500)',
+                                backgroundImage: 'linear-gradient(90deg, color-mix(in srgb, var(--theme-success-500) 70%, white) 0%, var(--theme-success-500) 50%, color-mix(in srgb, var(--theme-success-500) 70%, white) 100%)',
+                                animation: 'ai-translate-indeterminate 1.6s ease-in-out infinite'
+                            }
+                        }) : // Percent-based fill — shimmer animation runs while still
+                        // in flight, freezes when the bar is held at 100%.
+                        /*#__PURE__*/ _jsx("div", {
+                            style: {
+                                width: `${percent}%`,
+                                height: '100%',
+                                borderRadius: '3px',
+                                transition: 'width 0.3s ease',
+                                backgroundColor: 'var(--theme-success-500)',
+                                backgroundImage: finishedButHolding ? 'none' : 'linear-gradient(90deg, var(--theme-success-500) 0%, color-mix(in srgb, var(--theme-success-500) 70%, white) 50%, var(--theme-success-500) 100%)',
+                                backgroundSize: '200% 100%',
+                                animation: finishedButHolding ? 'none' : 'ai-translate-shimmer 1.4s linear infinite, ai-translate-pulse 2.2s ease-in-out infinite'
+                            }
+                        })
+                    }),
+                    /*#__PURE__*/ _jsxs("div", {
+                        style: {
+                            display: 'flex',
+                            flexWrap: 'wrap',
+                            gap: '6px'
+                        },
+                        children: [
+                            state.completed.map((locale)=>/*#__PURE__*/ _jsxs("span", {
+                                    style: {
+                                        color: 'var(--theme-success-500)'
+                                    },
+                                    children: [
+                                        "✓ ",
+                                        locale
+                                    ]
+                                }, locale)),
+                            state.failed.map((f)=>/*#__PURE__*/ _jsxs("span", {
+                                    style: {
+                                        color: 'var(--theme-error-500)'
+                                    },
+                                    children: [
+                                        "✗ ",
+                                        f.locale
+                                    ]
+                                }, f.locale))
+                        ]
+                    })
+                ]
+            }),
+            displayStatus === 'completed' && /*#__PURE__*/ _jsxs("div", {
+                style: {
+                    color: 'var(--theme-success-500)',
+                    fontWeight: 500
+                },
+                children: [
+                    "✓ Translated to ",
+                    state.completed.length,
+                    " locale",
+                    state.completed.length !== 1 ? 's' : ''
+                ]
+            }),
+            displayStatus === 'failed' && /*#__PURE__*/ _jsxs("div", {
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        style: {
+                            color: 'var(--theme-warning-500)',
+                            fontWeight: 500,
+                            marginBottom: '6px'
+                        },
+                        children: [
+                            "⚠ ",
+                            state.completed.length,
+                            "/",
+                            state.total,
+                            " locales translated"
+                        ]
+                    }),
+                    state.failed.map((f)=>/*#__PURE__*/ _jsxs("div", {
+                            style: {
+                                color: 'var(--theme-error-500)',
+                                fontSize: '12px',
+                                marginTop: '2px'
+                            },
+                            children: [
+                                "✗ ",
+                                f.locale,
+                                ": ",
+                                f.error
+                            ]
+                        }, f.locale))
+                ]
+            })
+        ]
+    });
+}

package/dist/components/TranslationNavGroup.d.ts

@@ -0,0 +1,45 @@
+import type React from 'react';
+/**
+ * Collapsible "Translation" sidebar group. Renders ONLY the two
+ * operator-facing entry points:
+ *
+ *   1. "Translation Hub" — custom view at `/admin/translation`
+ *   2. "Bulk Translate Runs" — custom view at `/admin/translation-runs`
+ *
+ * Every other translation-related surface (AI Translate Jobs, AI
+ * Translate Meta, Bulk Translate Batches, Bulk Translate Units,
+ * Translation Daily Spend, Translation Rate Limits, Translation
+ * Usage, OpenRouter Settings, Translation Settings) is DELIBERATELY
+ * omitted from the sidebar:
+ *
+ *   - Usage / alerts / in-flight jobs surface inside the Hub's
+ *     Overview + Audit tabs in a polished form.
+ *   - OpenRouter + Translation Settings live inside the Hub's
+ *     Configuration tab.
+ *   - Bulk batches + units are drilled into from the Runs hub's
+ *     inline drill-down — opening them as raw collection lists
+ *     would be a debugging escape hatch, not a daily workflow.
+ *   - Daily spend + rate-limit counters are internal counter tables;
+ *     operators never edit them.
+ *
+ * The collections + globals stay registered with
+ * `admin.group: 'Translation'` so they remain reachable via direct
+ * URL (`/admin/collections/<slug>`) for debugging — they just don't
+ * clutter the sidebar. Payload's auto-generated `Translation` group
+ * is hidden by the consumer's `custom.scss` (the
+ * `.nav-group.Translation { display: none }` rule is differentiated
+ * from our custom group via the `.translation-nav-group-host`
+ * wrapper).
+ *
+ * Wires via `admin.components.beforeNavLinks` /
+ * `afterNavLinks` in the consumer's payload.config.ts.
+ *
+ * Next.js basePath handling: `<Link>` auto-prepends the configured
+ * basePath (e.g. `/blog`). Hrefs MUST be the logical paths
+ * (`/admin/translation`) — including the basePath manually would
+ * produce `/blog/blog/admin/translation` in production. Next 14+'s
+ * `usePathname()` returns the pathname EXCLUDING basePath, so the
+ * active-state comparison matches the logical href directly.
+ */
+export declare const TranslationNavGroup: React.FC;
+export default TranslationNavGroup;

package/dist/components/TranslationNavGroup.js

@@ -0,0 +1,104 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { NavGroup, useConfig } from '@payloadcms/ui';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { useMemo } from 'react';
+/**
+ * Collapsible "Translation" sidebar group. Renders ONLY the two
+ * operator-facing entry points:
+ *
+ *   1. "Translation Hub" — custom view at `/admin/translation`
+ *   2. "Bulk Translate Runs" — custom view at `/admin/translation-runs`
+ *
+ * Every other translation-related surface (AI Translate Jobs, AI
+ * Translate Meta, Bulk Translate Batches, Bulk Translate Units,
+ * Translation Daily Spend, Translation Rate Limits, Translation
+ * Usage, OpenRouter Settings, Translation Settings) is DELIBERATELY
+ * omitted from the sidebar:
+ *
+ *   - Usage / alerts / in-flight jobs surface inside the Hub's
+ *     Overview + Audit tabs in a polished form.
+ *   - OpenRouter + Translation Settings live inside the Hub's
+ *     Configuration tab.
+ *   - Bulk batches + units are drilled into from the Runs hub's
+ *     inline drill-down — opening them as raw collection lists
+ *     would be a debugging escape hatch, not a daily workflow.
+ *   - Daily spend + rate-limit counters are internal counter tables;
+ *     operators never edit them.
+ *
+ * The collections + globals stay registered with
+ * `admin.group: 'Translation'` so they remain reachable via direct
+ * URL (`/admin/collections/<slug>`) for debugging — they just don't
+ * clutter the sidebar. Payload's auto-generated `Translation` group
+ * is hidden by the consumer's `custom.scss` (the
+ * `.nav-group.Translation { display: none }` rule is differentiated
+ * from our custom group via the `.translation-nav-group-host`
+ * wrapper).
+ *
+ * Wires via `admin.components.beforeNavLinks` /
+ * `afterNavLinks` in the consumer's payload.config.ts.
+ *
+ * Next.js basePath handling: `<Link>` auto-prepends the configured
+ * basePath (e.g. `/blog`). Hrefs MUST be the logical paths
+ * (`/admin/translation`) — including the basePath manually would
+ * produce `/blog/blog/admin/translation` in production. Next 14+'s
+ * `usePathname()` returns the pathname EXCLUDING basePath, so the
+ * active-state comparison matches the logical href directly.
+ */ export const TranslationNavGroup = ()=>{
+    const pathname = usePathname();
+    const { config } = useConfig();
+    // basePath stripping for the active-state check ONLY. We do NOT
+    // prepend basePath to the href because `<Link>` does that itself.
+    // Older Next versions occasionally include basePath in
+    // `usePathname()`; normalize defensively by stripping the runtime
+    // basePath from the pathname before comparing.
+    const runtimeBasePath = useMemo(()=>{
+        if (typeof window === 'undefined') {
+            return config?.routes?.admin?.replace(/\/admin$/, '') ?? '';
+        }
+        const idx = window.location.pathname.indexOf('/admin');
+        return idx > 0 ? window.location.pathname.slice(0, idx) : '';
+    }, [
+        config?.routes?.admin
+    ]);
+    const cleanPath = runtimeBasePath && pathname?.startsWith(runtimeBasePath) ? pathname.slice(runtimeBasePath.length) : pathname ?? '';
+    const hubHref = '/admin/translation';
+    const runsHref = '/admin/translation-runs';
+    const hubActive = cleanPath === hubHref;
+    const runsActive = cleanPath.startsWith(runsHref);
+    // The wrapper class `translation-nav-group-host` exists so the
+    // consumer's custom.scss can differentiate THIS NavGroup from
+    // Payload's auto-generated Translation group (both share className
+    // `nav-group Translation`). The recommended consumer CSS pattern:
+    //
+    //   .nav-group.Translation { display: none !important; }
+    //   .translation-nav-group-host .nav-group.Translation {
+    //     display: revert !important;
+    //   }
+    return /*#__PURE__*/ _jsx("div", {
+        className: "translation-nav-group-host",
+        children: /*#__PURE__*/ _jsxs(NavGroup, {
+            label: "Translation",
+            children: [
+                /*#__PURE__*/ _jsx(Link, {
+                    className: `nav__link${hubActive ? ' active' : ''}`,
+                    href: hubHref,
+                    children: /*#__PURE__*/ _jsx("span", {
+                        className: "nav__link-label",
+                        children: "Translation Hub"
+                    })
+                }),
+                /*#__PURE__*/ _jsx(Link, {
+                    className: `nav__link${runsActive ? ' active' : ''}`,
+                    href: runsHref,
+                    children: /*#__PURE__*/ _jsx("span", {
+                        className: "nav__link-label",
+                        children: "Bulk Translate Runs"
+                    })
+                })
+            ]
+        })
+    });
+};
+export default TranslationNavGroup;

package/dist/defaults.d.ts

@@ -0,0 +1,11 @@
+import type { ConcurrencyLimits, RetryConfig } from './types.js';
+export declare const DEFAULT_CONCURRENCY: ConcurrencyLimits;
+export declare const DEFAULT_RETRY: RetryConfig;
+export declare const DEFAULT_TARGET_POLICY: "mirror";
+export declare const DEFAULT_COALESCING_WINDOW_MS = 12000;
+export declare const REENTRY_FLAG: "aiTranslateInternal";
+export declare const SKIP_FLAG: "skipAutoTranslate";
+export declare const DEFAULT_USAGE_COLLECTION_SLUG = "translation-usage";
+export declare const USAGE_TRACKING_CONTEXT_FLAG: "aiTranslateUsageInternal";
+export declare const DEFAULT_ALERTS_COLLECTION_SLUG = "translation-alerts";
+export declare const ALERTS_CONTEXT_FLAG: "aiTranslateAlertsInternal";

package/dist/defaults.js

@@ -0,0 +1,16 @@
+export const DEFAULT_CONCURRENCY = {
+    perDocument: 3,
+    perProvider: 5
+};
+export const DEFAULT_RETRY = {
+    attempts: 2,
+    backoffMs: 1000
+};
+export const DEFAULT_TARGET_POLICY = 'mirror';
+export const DEFAULT_COALESCING_WINDOW_MS = 12_000;
+export const REENTRY_FLAG = 'aiTranslateInternal';
+export const SKIP_FLAG = 'skipAutoTranslate';
+export const DEFAULT_USAGE_COLLECTION_SLUG = 'translation-usage';
+export const USAGE_TRACKING_CONTEXT_FLAG = 'aiTranslateUsageInternal';
+export const DEFAULT_ALERTS_COLLECTION_SLUG = 'translation-alerts';
+export const ALERTS_CONTEXT_FLAG = 'aiTranslateAlertsInternal';

package/dist/endpoints/client-config.d.ts

@@ -0,0 +1,44 @@
+import type { PayloadHandler } from 'payload';
+/**
+ * Returns the JSON-safe subset of the plugin's config that the admin
+ * client needs at render time (Translate drawer locale picker,
+ * per-field button visibility, the per-collection field-exclusion
+ * widget on the translation-settings global, etc.).
+ *
+ * Payload's admin client strips function references from `config.custom`
+ * during the client-side serialization pass, so `useConfig()` cannot
+ * read `config.custom.aiTranslate.targetLocales` directly. This
+ * endpoint exposes the safe subset over the API instead.
+ *
+ * Path: `GET /api/ai-translate/client-config`
+ *
+ * Auth: any authenticated user (the response carries no secrets — just
+ * locale codes already visible in Payload's localization config, plus
+ * field paths derivable from the public admin schema).
+ *
+ * Response shape:
+ *   {
+ *     sourceLocale: string,
+ *     targetLocales: string[],
+ *     perFieldButton: boolean,
+ *     translatableFieldsBySlug: Record<string, string[]>,
+ *     bulkExcludedCollections: string[],
+ *     globalKillSwitches: { autoEnabled: boolean, manualEnabled: boolean, bulkEnabled: boolean },
+ *   }
+ *
+ * `globalKillSwitches` (v1.2.8) lets the admin client hide the
+ * Translate dialog / per-field button / BulkTranslate trigger when the
+ * matching plugin-wide kill switch is off. The server gates remain the
+ * source of truth (Translate endpoint 403s, Enqueue endpoint 403s) —
+ * the client uses these flags only for UI affordance.
+ *
+ * `translatableFieldsBySlug` maps each tracked collection / global
+ * slug to the list of translatable field paths the resolver would
+ * produce for that surface. Used by the `ExcludedFieldsField` admin
+ * component on the `translation-settings` global to render a checkbox
+ * list whose options change as the editor picks a `slug`. Computed
+ * per-request (~tens of microseconds for typical configs) so a
+ * dev-time config edit + restart immediately surfaces new fields
+ * without a separate cache-bust.
+ */
+export declare const getClientConfigHandler: () => PayloadHandler;

package/dist/endpoints/client-config.js

@@ -0,0 +1,145 @@
+import { describeAuthRejection } from '../lib/auth-diagnostics.js';
+import { getEffectiveExcludePatternsForSurface, getGlobalKillSwitches } from '../lib/effective-locales.js';
+import { isExcluded } from '../lib/exclude-fields.js';
+import { resolveTranslatableFields } from '../lib/field-resolver.js';
+/**
+ * Returns the JSON-safe subset of the plugin's config that the admin
+ * client needs at render time (Translate drawer locale picker,
+ * per-field button visibility, the per-collection field-exclusion
+ * widget on the translation-settings global, etc.).
+ *
+ * Payload's admin client strips function references from `config.custom`
+ * during the client-side serialization pass, so `useConfig()` cannot
+ * read `config.custom.aiTranslate.targetLocales` directly. This
+ * endpoint exposes the safe subset over the API instead.
+ *
+ * Path: `GET /api/ai-translate/client-config`
+ *
+ * Auth: any authenticated user (the response carries no secrets — just
+ * locale codes already visible in Payload's localization config, plus
+ * field paths derivable from the public admin schema).
+ *
+ * Response shape:
+ *   {
+ *     sourceLocale: string,
+ *     targetLocales: string[],
+ *     perFieldButton: boolean,
+ *     translatableFieldsBySlug: Record<string, string[]>,
+ *     bulkExcludedCollections: string[],
+ *     globalKillSwitches: { autoEnabled: boolean, manualEnabled: boolean, bulkEnabled: boolean },
+ *   }
+ *
+ * `globalKillSwitches` (v1.2.8) lets the admin client hide the
+ * Translate dialog / per-field button / BulkTranslate trigger when the
+ * matching plugin-wide kill switch is off. The server gates remain the
+ * source of truth (Translate endpoint 403s, Enqueue endpoint 403s) —
+ * the client uses these flags only for UI affordance.
+ *
+ * `translatableFieldsBySlug` maps each tracked collection / global
+ * slug to the list of translatable field paths the resolver would
+ * produce for that surface. Used by the `ExcludedFieldsField` admin
+ * component on the `translation-settings` global to render a checkbox
+ * list whose options change as the editor picks a `slug`. Computed
+ * per-request (~tens of microseconds for typical configs) so a
+ * dev-time config edit + restart immediately surfaces new fields
+ * without a separate cache-bust.
+ */ export const getClientConfigHandler = ()=>async (req)=>{
+        if (!req.user) {
+            return Response.json({
+                error: 'Unauthorized',
+                diagnostic: describeAuthRejection(req)
+            }, {
+                status: 401
+            });
+        }
+        const config = req.payload.config?.custom?.aiTranslate;
+        if (!config) {
+            return Response.json({
+                error: 'ai-translate plugin not configured'
+            }, {
+                status: 500
+            });
+        }
+        // Build the slug → translatable-paths map. We walk only surfaces
+        // the plugin is configured to track — there's no point listing
+        // paths for collections the plugin can't translate, and exposing
+        // them would invite editor confusion in the admin UI.
+        //
+        // Use surface-aware exclude patterns so the widget mirrors what
+        // the translate pipeline actually sends per surface. When a row
+        // toggles `translateSlug: true`, `slug` appears in that surface's
+        // path list (and gets a checkbox in the ExcludedFieldsField); for
+        // every other surface the slug stays hidden because the static
+        // `'slug'` exclusion still applies.
+        const trackedCollections = new Set(config.collections ?? []);
+        const trackedGlobals = new Set(config.globals ?? []);
+        const translatableFieldsBySlug = {};
+        for (const collection of req.payload.config.collections ?? []){
+            if (!trackedCollections.has(collection.slug)) continue;
+            const patterns = await getEffectiveExcludePatternsForSurface(req.payload, config, collection.slug);
+            translatableFieldsBySlug[collection.slug] = pathsFor(collection, patterns);
+        }
+        for (const global of req.payload.config.globals ?? []){
+            if (!global.slug || !trackedGlobals.has(global.slug)) continue;
+            const patterns = await getEffectiveExcludePatternsForSurface(req.payload, config, global.slug);
+            translatableFieldsBySlug[global.slug] = pathsFor(global, patterns);
+        }
+        // NEW-9 (v1.2.6): surface the bulk-translate exclusion list so the
+        // Advanced tab can annotate "translatable everywhere but excluded
+        // from bulk runs" (typically `users`). Without this the editor
+        // sees `users` listed under "Translatable fields per surface" but
+        // can't find it in the Bulk Translate breakdown, which looks like
+        // a bug.
+        const bulkExcludedCollections = Array.isArray(config.bulk?.excludeCollections) ? [
+            ...config.bulk?.excludeCollections ?? []
+        ] : [];
+        // v1.2.8: surface the three plugin-wide kill switches so the admin
+        // client can hide the Translate dialog / per-field button / Bulk
+        // trigger when their matching flag is off. Server-side gates remain
+        // the source of truth — these flags only affect UI affordance.
+        const globalKillSwitches = await getGlobalKillSwitches(req.payload, config);
+        return Response.json({
+            sourceLocale: config.sourceLocale,
+            targetLocales: [
+                ...config.targetLocales
+            ],
+            perFieldButton: !!config.perFieldButton,
+            translatableFieldsBySlug,
+            bulkExcludedCollections,
+            globalKillSwitches
+        });
+    };
+function pathsFor(surface, excludePatterns) {
+    // The plugin injects `_aiTranslateAutoLocales` (select),
+    // `_aiTranslateOptOut` (checkbox), and `_aiTranslate` (ui) onto
+    // every tracked surface. None are translatable —
+    // `resolveTranslatableFields` already filters by type, so they're
+    // naturally absent. We still defensively exclude anything starting
+    // with an underscore prefix to keep the admin UI clean if someone
+    // hand-marks one of them `localized: true`.
+    //
+    // Dedupe: a `blocks` field with N block types recurses into each
+    // block's fields under the same parent path, so shared field names
+    // (e.g. every block has its own `blockName`) emit `layout.blockName`
+    // N times. The translate pipeline doesn't care (extractor processes
+    // each block instance separately), but the admin UI uses paths as
+    // React keys — duplicates cause "two children with the same key"
+    // warnings and dropped checkboxes. Set dedupes deterministically.
+    //
+    // Static excludePatterns: paths that the translate pipeline never
+    // sends (URLs via the `**.url` default, plus consumer-configured
+    // `excludeFields`) are removed here too. Mirrors what actually
+    // happens at translation time so the widget doesn't tease the
+    // editor with paths they can't influence.
+    const fields = surface.fields ?? [];
+    const seen = new Set();
+    const out = [];
+    for (const f of resolveTranslatableFields(fields)){
+        if (f.path.split('.').some((seg)=>seg.startsWith('_'))) continue;
+        if (isExcluded(f.path, excludePatterns)) continue;
+        if (seen.has(f.path)) continue;
+        seen.add(f.path);
+        out.push(f.path);
+    }
+    return out;
+}

package/dist/endpoints/estimate.d.ts

@@ -0,0 +1,5 @@
+import type { PayloadHandler } from 'payload';
+import type { HandlerContext } from './translate.js';
+type HandlerArg = HandlerContext | string | undefined;
+export declare const getEstimateHandler: (arg?: HandlerArg) => PayloadHandler;
+export {};