@purposeinplay/payload-ai-translate 0.1.0

package/dist/client/field-translate-button.js

@@ -0,0 +1,199 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { toast, useConfig, useDocumentInfo, useField, useLocale } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import { Component, useState } from 'react';
+import { useGlobalKillSwitches } from './lib/use-global-kill-switches.js';
+// Error boundary — if useDocumentInfo throws on create view, render nothing
+let FieldTranslateButtonBoundary = class FieldTranslateButtonBoundary extends Component {
+    constructor(props){
+        super(props);
+        this.state = {
+            hasError: false
+        };
+    }
+    static getDerivedStateFromError() {
+        return {
+            hasError: true
+        };
+    }
+    render() {
+        if (this.state.hasError) return null;
+        return this.props.children;
+    }
+};
+function FieldTranslateButtonInner({ path }) {
+    const [translating, setTranslating] = useState(false);
+    // Inline error message rendered next to the button. Toast notifications
+    // can be missed when the consumer's admin layout doesn't mount a
+    // `<Toaster />` correctly (Sonner version mismatch, plugin queue
+    // orphaned by RootProvider position, etc.). The inline indicator gives
+    // the user feedback even in those cases. Cleared when the user clicks
+    // again or a translation succeeds.
+    const [errorMsg, setErrorMsg] = useState(null);
+    const documentInfo = useDocumentInfo();
+    const { config } = useConfig();
+    const locale = useLocale();
+    // Hook into the surrounding field's form state so we can write the
+    // translated value back into the input without making the user reload.
+    const { setValue } = useField({
+        path
+    });
+    // Plugin-wide manual-translate kill switch (v1.2.8). Called here at
+    // the top of the component (before any early returns) to satisfy
+    // rules-of-hooks. The actual hide check happens further down.
+    const killSwitches = useGlobalKillSwitches();
+    const globalSlug = documentInfo.globalSlug;
+    const id = documentInfo.id;
+    const collectionSlug = documentInfo.collectionSlug ?? documentInfo.slug;
+    const defaultLocale = config.localization ? config.localization.defaultLocale : 'en';
+    const currentLocale = typeof locale === 'string' ? locale : locale?.code;
+    if (!currentLocale || currentLocale === defaultLocale) return null;
+    // Hide on manual-translate kill switch off (see top-of-component
+    // hook call for rules-of-hooks rationale). Optimistic while loading
+    // (`null`) — server-side endpoint gate is the real authority.
+    if (killSwitches && !killSwitches.manualEnabled) return null;
+    // Resolve doc context: globals don't have a numeric id, just a slug
+    let pathPrefix = null;
+    let bodyForGlobal = false;
+    if (globalSlug) {
+        pathPrefix = `/globals/${globalSlug}`;
+        bodyForGlobal = true;
+    } else if (id && collectionSlug) {
+        pathPrefix = `/${collectionSlug}`;
+    } else {
+        return null;
+    }
+    const handleTranslate = async ()=>{
+        if (translating) return;
+        setTranslating(true);
+        setErrorMsg(null);
+        try {
+            const { routes } = config;
+            const apiRoute = routes?.api ?? '/api';
+            const body = {
+                targetLocales: [
+                    currentLocale
+                ],
+                fields: [
+                    path
+                ],
+                // Per-field translate writes only the field the user clicked.
+                // The form patches the value into the local form state via
+                // `setValue` regardless — the locale write is a server-side
+                // side effect that should match the user's narrow intent.
+                writeMode: 'minimal'
+            };
+            if (!bodyForGlobal) body.id = id;
+            const apiPath = `${pathPrefix}/ai-translate`;
+            const res = await fetch(formatAdminURL({
+                apiRoute,
+                path: apiPath
+            }), {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(body)
+            });
+            if (!res.ok) {
+                const errorData = await res.json().catch(()=>({}));
+                throw new Error(errorData.error ?? `HTTP ${res.status}`);
+            }
+            const data = await res.json();
+            const result = data.results[0];
+            const failCount = result?.failed?.length ?? 0;
+            if (failCount === 0) {
+                // Patch the form state with the new value when the API returns it
+                // (plain text/textarea only — richText/blocks need a doc reload).
+                const successEntry = result?.succeeded?.find((s)=>s.fieldPath === path);
+                if (typeof successEntry?.translatedText === 'string') {
+                    const newValue = successEntry.translatedText;
+                    // 1) Update Payload's form state via the field-level setValue.
+                    //    This is the "right" path but doesn't always trigger the
+                    //    sibling input's re-render — Payload's text input is
+                    //    React-Compiler-memoized and may not observe a dispatch
+                    //    that originates from a different `useField` registration.
+                    setValue(newValue);
+                    // 2) Belt-and-suspenders: drive the DOM input directly and fire
+                    //    an `input` event the way a real keystroke would. This goes
+                    //    through the input's own onChange → its own setValue, which
+                    //    is the codepath Payload's memoization tracks.
+                    //    Runs in the next microtask so we don't fight React's
+                    //    render of step 1.
+                    queueMicrotask(()=>{
+                        const inputId = `field-${path.replace(/\./g, '__')}`;
+                        const el = document.getElementById(inputId);
+                        if (!el || el.value === newValue) return;
+                        const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+                        const setter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+                        if (!setter) return;
+                        setter.call(el, newValue);
+                        el.dispatchEvent(new Event('input', {
+                            bubbles: true
+                        }));
+                    });
+                }
+                toast.success(`Translated "${path}" to ${currentLocale}`);
+            } else {
+                const reason = result?.failed?.[0]?.error;
+                const msg = reason ? `Failed to translate "${path}": ${reason.slice(0, 200)}` : `Failed to translate "${path}"`;
+                toast.error(msg);
+                setErrorMsg(reason ?? 'Translation failed');
+            }
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : 'Translation failed';
+            toast.error(msg);
+            setErrorMsg(msg);
+        } finally{
+            setTranslating(false);
+        }
+    };
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsx("button", {
+                // Without an explicit type the browser defaults to "submit" inside the
+                // Payload edit `<form>`, so a click would save the document (bumping
+                // the version + showing "Updated successfully") in addition to firing
+                // the translation. Force "button" to keep it side-effect-free.
+                type: "button",
+                onClick: handleTranslate,
+                disabled: translating,
+                title: `Translate this field to ${currentLocale}`,
+                style: {
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    gap: '4px',
+                    padding: '4px 8px',
+                    marginTop: '4px',
+                    backgroundColor: 'transparent',
+                    border: '1px solid var(--theme-elevation-300)',
+                    borderRadius: '3px',
+                    color: 'var(--theme-elevation-500)',
+                    cursor: translating ? 'wait' : 'pointer',
+                    fontSize: '12px',
+                    opacity: translating ? 0.6 : 1
+                },
+                children: translating ? 'Translating...' : 'Translate'
+            }),
+            errorMsg && /*#__PURE__*/ _jsx("div", {
+                role: "alert",
+                style: {
+                    marginTop: '4px',
+                    color: 'var(--theme-error-500)',
+                    fontSize: '12px',
+                    maxWidth: '100%'
+                },
+                children: errorMsg
+            })
+        ]
+    });
+}
+export function FieldTranslateButton(props) {
+    return /*#__PURE__*/ _jsx(FieldTranslateButtonBoundary, {
+        children: /*#__PURE__*/ _jsx(FieldTranslateButtonInner, {
+            ...props
+        })
+    });
+}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export { EstimatedCostCell } from './estimated-cost-cell.js';
+export { ExcludedFieldsField } from './excluded-fields-field.js';
+export { FieldTranslateButton } from './field-translate-button.js';
+export { TranslateButton } from './translate-button.js';
+export { TranslateModal } from './translate-modal.js';
+export { TranslationProgress } from './translation-progress.js';

package/dist/client/index.js

@@ -0,0 +1,6 @@
+export { EstimatedCostCell } from './estimated-cost-cell.js';
+export { ExcludedFieldsField } from './excluded-fields-field.js';
+export { FieldTranslateButton } from './field-translate-button.js';
+export { TranslateButton } from './translate-button.js';
+export { TranslateModal } from './translate-modal.js';
+export { TranslationProgress } from './translation-progress.js';

package/dist/client/lib/use-global-kill-switches.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Client-side view of the three plugin-wide kill switches (v1.2.8).
+ * Fetched from `/api/ai-translate/client-config` on mount; the response
+ * is cached at module scope with a 15-second TTL so multiple buttons
+ * mounting on the same admin view collapse to one network call.
+ *
+ * Optimistic default: components that consume this hook should treat
+ * `null` (still loading) as "show normally". On a slow connection an
+ * admin user briefly sees the affordance before it hides — accepted
+ * trade-off since the server-side gates are the real source of truth
+ * (Translate endpoint returns 403, Enqueue endpoint returns 403).
+ */
+export type GlobalKillSwitchesClient = {
+    autoEnabled: boolean;
+    manualEnabled: boolean;
+    bulkEnabled: boolean;
+};
+/** @internal test helper */
+export declare function _resetGlobalKillSwitchesCache(): void;
+export declare function useGlobalKillSwitches(): GlobalKillSwitchesClient | null;

package/dist/client/lib/use-global-kill-switches.js

@@ -0,0 +1,58 @@
+'use client';
+import { useConfig } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import { useEffect, useState } from 'react';
+const TTL_MS = 15_000;
+const cache = new Map();
+const DEFAULT_OPEN = {
+    autoEnabled: true,
+    manualEnabled: true,
+    bulkEnabled: true
+};
+function fetchKillSwitches(url) {
+    return fetch(url, {
+        credentials: 'include'
+    }).then((res)=>res.ok ? res.json() : null).then((data)=>{
+        const raw = data?.globalKillSwitches;
+        if (!raw) return DEFAULT_OPEN;
+        return {
+            autoEnabled: raw.autoEnabled !== false,
+            manualEnabled: raw.manualEnabled !== false,
+            bulkEnabled: raw.bulkEnabled !== false
+        };
+    }).catch(()=>DEFAULT_OPEN);
+}
+/** @internal test helper */ export function _resetGlobalKillSwitchesCache() {
+    cache.clear();
+}
+export function useGlobalKillSwitches() {
+    const { config } = useConfig();
+    const apiRoute = config.routes?.api ?? '/api';
+    const url = formatAdminURL({
+        apiRoute,
+        path: '/ai-translate/client-config',
+        serverURL: ''
+    });
+    const [switches, setSwitches] = useState(null);
+    useEffect(()=>{
+        let cancelled = false;
+        const now = Date.now();
+        const existing = cache.get(url);
+        if (!existing || existing.expiresAt <= now) {
+            cache.set(url, {
+                promise: fetchKillSwitches(url),
+                expiresAt: now + TTL_MS
+            });
+        }
+        const entry = cache.get(url);
+        entry?.promise.then((s)=>{
+            if (!cancelled) setSwitches(s);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        url
+    ]);
+    return switches;
+}

package/dist/client/translate-button.d.ts

@@ -0,0 +1,2 @@
+import React from 'react';
+export declare function TranslateButton(): React.JSX.Element | null;

package/dist/client/translate-button.js

@@ -0,0 +1,228 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useConfig, useDocumentInfo, useFormProcessing } from '@payloadcms/ui';
+import { formatAdminURL } from 'payload/shared';
+import React, { useEffect, useState } from 'react';
+import { useGlobalKillSwitches } from './lib/use-global-kill-switches.js';
+import { TranslateModal } from './translate-modal.js';
+import { TranslationProgress } from './translation-progress.js';
+function resolveDocContext(info) {
+    const globalSlug = info.globalSlug;
+    if (globalSlug) {
+        return {
+            kind: 'global',
+            slug: globalSlug,
+            pathPrefix: `/globals/${globalSlug}`,
+            pollKey: globalSlug
+        };
+    }
+    const id = info.id;
+    const collectionSlug = info.collectionSlug ?? info.slug;
+    if (id && collectionSlug) {
+        return {
+            kind: 'collection',
+            slug: collectionSlug,
+            id,
+            pathPrefix: `/${collectionSlug}`,
+            pollKey: String(id)
+        };
+    }
+    return null;
+}
+const SUBMIT_FEEDBACK_KEYFRAMES = `
+@keyframes ai-translate-pre-indeterminate {
+  0%   { left: -35%; right: 100%; }
+  60%  { left: 100%; right: -35%; }
+  100% { left: 100%; right: -35%; }
+}
+`;
+/**
+ * Optimistic "Saving…" indicator shown while Payload's form is
+ * submitting (or background-autosaving) AND we haven't yet picked up
+ * an active translation job.
+ *
+ * Why: Payload's publish flow round-trips through several
+ * POST/PATCH calls (autosave debounce + server actions + final
+ * publish) which can take 5-9s wall-clock before the after-change
+ * hook fires + `createJob` runs. Without this, the user clicks
+ * Publish and stares at unchanged UI for that whole window, then
+ * suddenly the progress bar appears mid-translation. With this,
+ * they get feedback within ~50ms of click.
+ *
+ * Wording is neutral ("Saving…") because this also fires on plain
+ * draft saves and autosave debounces, where no translation will run.
+ * Naming a translation here would be misleading; the real progress
+ * bar takes over the moment a job is registered server-side.
+ *
+ * Visually matches the indeterminate state of `TranslationProgress`
+ * so the transition into the real bar feels continuous.
+ */ function SubmitFeedback({ formProcessing, showWhileTranslating }) {
+    if (!formProcessing || !showWhileTranslating) return null;
+    return /*#__PURE__*/ _jsxs("div", {
+        style: {
+            marginTop: '8px',
+            padding: '12px 16px',
+            backgroundColor: 'var(--theme-elevation-50)',
+            border: '1px solid var(--theme-elevation-200)',
+            borderRadius: '4px',
+            fontSize: '13px',
+            color: 'var(--theme-text)'
+        },
+        role: "status",
+        "aria-live": "polite",
+        children: [
+            /*#__PURE__*/ _jsx("style", {
+                children: SUBMIT_FEEDBACK_KEYFRAMES
+            }),
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    marginBottom: '8px',
+                    fontWeight: 500
+                },
+                children: "Saving…"
+            }),
+            /*#__PURE__*/ _jsx("div", {
+                style: {
+                    position: 'relative',
+                    width: '100%',
+                    height: '6px',
+                    backgroundColor: 'var(--theme-elevation-200)',
+                    borderRadius: '3px',
+                    overflow: 'hidden'
+                },
+                children: /*#__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-pre-indeterminate 1.6s ease-in-out infinite'
+                    }
+                })
+            })
+        ]
+    });
+}
+export function TranslateButton() {
+    const [modalOpen, setModalOpen] = useState(false);
+    const [activeJobId, setActiveJobId] = useState(null);
+    const documentInfo = useDocumentInfo();
+    const { config } = useConfig();
+    // Only react to the real submit (Save / Publish click).
+    // `useFormBackgroundProcessing` also fires for every autosave
+    // debounce, which on a versioned collection with
+    // `autosave.interval: 400` happens on every keystroke — and the
+    // optimistic indicator below looks identical to the translation
+    // progress bar, so editors read "Saving…" on draft autosave as
+    // "translating now, did I just spend tokens?". Trade the ~5-9s
+    // optimistic head-start on Publish click for that confusion-free
+    // signal: the bar only appears when a translation is actually
+    // imminent (real submit) or running (`activeJobId`).
+    const formProcessing = useFormProcessing();
+    const isAnyFormActivity = formProcessing;
+    // Plugin-wide manual-translate kill switch (v1.2.8). Called at top
+    // level for rules-of-hooks; the `return null` below combines with
+    // the docCtx check.
+    const killSwitches = useGlobalKillSwitches();
+    const docCtx = resolveDocContext(documentInfo);
+    const apiRoute = config.routes?.api ?? '/api';
+    // Open ONE long-lived EventSource on mount. The server holds the
+    // connection open and pushes a 'progress' event the moment a
+    // translation job is created for this doc — typically within ~50ms of
+    // an after-change hook firing. No client polling, no race-the-server
+    // burst timers. Replaces the previous setInterval + form-submit burst
+    // that produced ~10s of dead-air UX between Publish click and
+    // progress bar.
+    //
+    // Effect deps are PRIMITIVES (`pollKey`, `pathPrefix`, `apiRoute`),
+    // not the full `docCtx` object — `resolveDocContext` returns a new
+    // object reference each render, which would tear down + recreate the
+    // EventSource constantly and defeat the whole point.
+    const pollKey = docCtx?.pollKey;
+    const pathPrefix = docCtx?.pathPrefix;
+    useEffect(()=>{
+        if (!pollKey || !pathPrefix) return;
+        if (typeof EventSource === 'undefined') return;
+        const path = `${pathPrefix}/ai-translate/progress?docId=${encodeURIComponent(pollKey)}`;
+        const url = formatAdminURL({
+            apiRoute,
+            path
+        });
+        const es = new EventSource(url, {
+            withCredentials: true
+        });
+        function handleProgress(e) {
+            try {
+                const data = JSON.parse(e.data);
+                if (data.status === 'running' && data.jobId) {
+                    setActiveJobId(data.jobId);
+                }
+            } catch  {
+            // malformed event — ignore
+            }
+        }
+        es.addEventListener('progress', handleProgress);
+        // EventSource auto-reconnects when the server closes; the
+        // `retry: 30000` directive paces idle reconnects.
+        return ()=>{
+            es.removeEventListener('progress', handleProgress);
+            es.close();
+        };
+    }, [
+        pollKey,
+        pathPrefix,
+        apiRoute
+    ]);
+    if (!docCtx) return null;
+    // Hide on manual-translate kill switch off. Optimistic while loading.
+    if (killSwitches && !killSwitches.manualEnabled) return null;
+    return /*#__PURE__*/ _jsxs("div", {
+        style: {
+            marginTop: '16px'
+        },
+        children: [
+            /*#__PURE__*/ _jsx("button", {
+                type: "button",
+                onClick: ()=>setModalOpen(true),
+                disabled: !!activeJobId,
+                style: {
+                    width: '100%',
+                    padding: '10px 16px',
+                    backgroundColor: activeJobId ? 'var(--theme-elevation-50)' : 'var(--theme-elevation-100)',
+                    border: '1px solid var(--theme-elevation-300)',
+                    borderRadius: '4px',
+                    color: 'var(--theme-text)',
+                    cursor: activeJobId ? 'default' : 'pointer',
+                    fontSize: '14px',
+                    fontWeight: 500,
+                    opacity: activeJobId ? 0.7 : 1
+                },
+                children: activeJobId ? 'Translating...' : 'Translate...'
+            }),
+            /*#__PURE__*/ _jsx(SubmitFeedback, {
+                formProcessing: isAnyFormActivity,
+                showWhileTranslating: !activeJobId
+            }),
+            activeJobId && /*#__PURE__*/ _jsx("div", {
+                style: {
+                    marginTop: '8px'
+                },
+                children: /*#__PURE__*/ _jsx(TranslationProgress, {
+                    jobId: activeJobId,
+                    collectionSlug: docCtx.kind === 'collection' ? docCtx.slug : undefined,
+                    globalSlug: docCtx.kind === 'global' ? docCtx.slug : undefined,
+                    onComplete: ()=>setActiveJobId(null)
+                })
+            }),
+            modalOpen && /*#__PURE__*/ _jsx(TranslateModal, {
+                docId: docCtx.kind === 'collection' ? docCtx.id : docCtx.slug,
+                collectionSlug: docCtx.kind === 'collection' ? docCtx.slug : undefined,
+                globalSlug: docCtx.kind === 'global' ? docCtx.slug : undefined,
+                onClose: ()=>setModalOpen(false),
+                onJobStarted: setActiveJobId
+            })
+        ]
+    });
+}

package/dist/client/translate-modal.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+type TranslateModalProps = {
+    docId: string | number;
+    collectionSlug?: string;
+    globalSlug?: string;
+    onClose: () => void;
+    /**
+     * Called when the translate POST returns a `jobId` (async mode).
+     * The parent TranslateButton uses this to hand off the active job to its
+     * sidebar progress widget so the modal can close immediately rather than
+     * trapping the user behind a duplicate progress UI.
+     */
+    onJobStarted?: (jobId: string) => void;
+};
+export declare function TranslateModal({ docId, collectionSlug, globalSlug, onClose, onJobStarted, }: TranslateModalProps): React.ReactPortal | null;
+export {};