@focus-reactive/payload-plugin-translator 0.4.0 → 0.5.0

package/dist/server/modules/translation-levels/documentLevel.js

@@ -0,0 +1,28 @@
+import { TranslateDocumentExport } from "../../../client/widgets/translate-document";
+import { useDocTranslationApi } from "./useDocTranslationApi";
+/**
+ * Per-document translation: a popup control on the document edit view, backed by
+ * the shared document-translation API (async/job by default; synchronous if the
+ * configured `runner` is a sync runner).
+ *
+ * @since 0.5.0
+ * @returns An opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`.
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider,
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), collectionLevel()], // this is the default — omit for the same result
+ * })
+ * ```
+ */ export function documentLevel() {
+    return {
+        extend (ctx) {
+            useDocTranslationApi(ctx);
+            ctx.addCollectionComponent("beforeDocumentControls", (collection)=>new TranslateDocumentExport(collection, ctx.access));
+        }
+    };
+}
+
+//# sourceMappingURL=documentLevel.js.map

package/dist/server/modules/translation-levels/index.d.ts

@@ -0,0 +1,3 @@
+export type { TranslationLevel } from "./types";
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";

package/dist/server/modules/translation-levels/index.js

@@ -0,0 +1,4 @@
+export { documentLevel } from "./documentLevel";
+export { collectionLevel } from "./collectionLevel";
+
+//# sourceMappingURL=index.js.map

package/dist/server/modules/translation-levels/types.d.ts

@@ -0,0 +1,42 @@
+import type { CollectionConfig, Endpoint } from "payload";
+import type { AccessGuard } from "../../../types/AccessGuard";
+import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { TaskRunnerFactory } from "../task-runner";
+export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";
+/**
+ * A composable translation surface (document / collection / field).
+ *
+ * Treat it as an **opaque value**: create one with `documentLevel()` /
+ * `collectionLevel()` (and, later, `fieldLevel()`) and list it in
+ * `translatorPlugin({ levels })`. It is produced only by those built-in
+ * factories — not externally implementable yet, since {@link LevelContext} is
+ * intentionally not exported. Opening it later (export `LevelContext`, drop the
+ * `@internal` tag) is additive and non-breaking.
+ *
+ * @since 0.5.0
+ */
+export interface TranslationLevel {
+    /**
+     * Not a stable contract yet — produce via the level factories.
+     * @internal
+     */
+    extend(ctx: LevelContext): void;
+}
+/**
+ * Public-ready shape, kept internal until external levels are needed.
+ *
+ * A level contributes via these generic primitives; it never mutates the raw
+ * Payload config. The plugin deduplicates endpoints by method + path on apply.
+ * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
+ * @internal
+ */
+export interface LevelContext {
+    readonly collections: CollectionConfig[];
+    readonly basePath: string;
+    readonly access?: AccessGuard;
+    readonly taskRunnerFactory: TaskRunnerFactory;
+    /** Register endpoints. Deduplicated by method + path when applied. */
+    addEndpoints(endpoints: Endpoint[]): void;
+    /** Attach an admin component to a slot on every managed collection. */
+    addCollectionComponent(slot: CollectionAdminSlot, make: (collection: CollectionConfig) => RawPayloadComponentExport): void;
+}

package/dist/server/modules/translation-levels/types.js

@@ -0,0 +1,10 @@
+/**
+ * Public-ready shape, kept internal until external levels are needed.
+ *
+ * A level contributes via these generic primitives; it never mutates the raw
+ * Payload config. The plugin deduplicates endpoints by method + path on apply.
+ * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
+ * @internal
+ */ export { };
+
+//# sourceMappingURL=types.js.map

package/dist/server/modules/translation-levels/useDocTranslationApi.d.ts

@@ -0,0 +1,8 @@
+import type { LevelContext } from "./types";
+/**
+ * Contribute the runner-agnostic document-translation API — the shared 6-route
+ * bundle, bound to the level context's runner. Both `documentLevel` and
+ * `collectionLevel` call this; the plugin deduplicates the endpoints by method +
+ * path, so the bundle registers exactly once.
+ */
+export declare function useDocTranslationApi(ctx: LevelContext): void;

package/dist/server/modules/translation-levels/useDocTranslationApi.js

@@ -0,0 +1,18 @@
+import { createTranslationRoutes } from "../../features/createTranslationRoutes";
+/**
+ * Contribute the runner-agnostic document-translation API — the shared 6-route
+ * bundle, bound to the level context's runner. Both `documentLevel` and
+ * `collectionLevel` call this; the plugin deduplicates the endpoints by method +
+ * path, so the bundle registers exactly once.
+ */ export function useDocTranslationApi(ctx) {
+    ctx.addEndpoints(createTranslationRoutes({
+        taskRunnerFactory: ctx.taskRunnerFactory,
+        collectionConfig: {
+            availableCollections: new Set(ctx.collections.map((collection)=>collection.slug))
+        },
+        access: ctx.access,
+        basePath: ctx.basePath
+    }));
+}
+
+//# sourceMappingURL=useDocTranslationApi.js.map

package/dist/server/modules/translation-pipeline/index.d.ts

@@ -1,3 +1,5 @@
-export { TranslationPipeline } from './TranslationPipeline';
-export type { TranslationStrategy } from './strategies';
-export { OverwriteStrategy, SkipExistingStrategy } from './strategies';
+export { TranslationPipeline } from "./TranslationPipeline";
+export { translateContent } from "./translateContent";
+export type { TranslateContentArgs } from "./translateContent";
+export type { TranslationStrategy } from "./strategies";
+export { OverwriteStrategy, SkipExistingStrategy } from "./strategies";

package/dist/server/modules/translation-pipeline/index.js

@@ -1,4 +1,5 @@
-export { TranslationPipeline } from './TranslationPipeline';
-export { OverwriteStrategy, SkipExistingStrategy } from './strategies';
+export { TranslationPipeline } from "./TranslationPipeline";
+export { translateContent } from "./translateContent";
+export { OverwriteStrategy, SkipExistingStrategy } from "./strategies";
 
 //# sourceMappingURL=index.js.map

package/dist/server/modules/translation-pipeline/translateContent.d.ts

@@ -0,0 +1,35 @@
+import type { Field } from "payload";
+import type { TranslationProvider } from "../translation-providers";
+import type { TranslationStrategyName } from "./strategies";
+export type TranslateContentArgs = {
+    /** Schema subtree to translate (e.g. `[declaredFieldConfig]`). */
+    schema: Field[];
+    /** Source values, rooted to match `schema` (e.g. `{ [fieldName]: value }`). */
+    sourceData: Record<string, unknown>;
+    /**
+     * Existing target-locale values to reconcile against (target wins when
+     * non-empty under `skip_existing`). Defaults to `{}` — i.e. translate the
+     * source in place (`overwrite`).
+     */
+    targetData?: Record<string, unknown>;
+    /** Source language code, or `''` for provider auto-detect. */
+    sourceLng: string;
+    targetLng: string;
+    translationProvider: TranslationProvider;
+    /** @default 'overwrite' */
+    strategy?: TranslationStrategyName;
+};
+/**
+ * Translate a content object over a schema subtree — no DB, no document.
+ *
+ * A thin reusable entry over {@link TranslationPipeline}, which is already pure
+ * and walks any `Field[]` + matching data (a subtree + partial data works
+ * unchanged). The document level routes through this wrapper today (instead of
+ * constructing the pipeline inline); the upcoming field level will too —
+ * passing a single declared field's subtree + its current unsaved form value.
+ *
+ * Only `localized` text/richText leaves are translated; non-localized values
+ * are reconciled through unchanged. Returns the translated data (same shape as
+ * `sourceData`) or `null` when nothing was translatable.
+ */
+export declare function translateContent({ schema, sourceData, targetData, sourceLng, targetLng, translationProvider, strategy, }: TranslateContentArgs): Promise<Record<string, unknown> | null>;

package/dist/server/modules/translation-pipeline/translateContent.js

@@ -0,0 +1,30 @@
+import { TranslationPipeline } from "./TranslationPipeline";
+import { createTranslationStrategy } from "./strategies";
+/**
+ * Translate a content object over a schema subtree — no DB, no document.
+ *
+ * A thin reusable entry over {@link TranslationPipeline}, which is already pure
+ * and walks any `Field[]` + matching data (a subtree + partial data works
+ * unchanged). The document level routes through this wrapper today (instead of
+ * constructing the pipeline inline); the upcoming field level will too —
+ * passing a single declared field's subtree + its current unsaved form value.
+ *
+ * Only `localized` text/richText leaves are translated; non-localized values
+ * are reconciled through unchanged. Returns the translated data (same shape as
+ * `sourceData`) or `null` when nothing was translatable.
+ */ export async function translateContent({ schema, sourceData, targetData = {}, sourceLng, targetLng, translationProvider, strategy = "overwrite" }) {
+    const pipeline = new TranslationPipeline({
+        translationProvider,
+        translationStrategy: createTranslationStrategy(strategy)
+    });
+    const result = await pipeline.execute({
+        schema,
+        sourceData,
+        targetData,
+        sourceLng,
+        targetLng
+    });
+    return result ? result.translatedData : null;
+}
+
+//# sourceMappingURL=translateContent.js.map

package/dist/server/modules/translation-providers/OpenAITranslation.provider.d.ts

@@ -1,5 +1,5 @@
-import type { TranslationProvider, TranslationInput, TranslationOutput } from './TranslationProvider.interface';
-import type { ChatModel } from 'openai/resources/index.mjs';
+import type { TranslationProvider, TranslationInput, TranslationOutput } from "./TranslationProvider.interface";
+import type { ChatModel } from "openai/resources/index.mjs";
 /**
  * Function to transform text in dry run mode.
  * Receives the original text and returns the transformed text.
@@ -30,6 +30,7 @@ export type SystemPromptContext = {
  */
 type SystemPromptBuilder = (context: SystemPromptContext) => string;
 export type OpenAIProviderConfig = {
+    /** OpenAI API key (required). Read it from an env var — never hard-code it. */
     apiKey: string;
     /**
      * OpenAI model to use for translation.
@@ -78,8 +79,8 @@ export type OpenAIProviderConfig = {
 };
 /** @deprecated Use `createOpenAIProvider` function instead */
 export declare class OpenAITranslationProvider implements TranslationProvider {
-    private readonly config;
     private openAiClient;
+    private readonly config;
     constructor(config: OpenAIProviderConfig);
     translate(content: TranslationInput, souceLng: string, targetLng: string): Promise<TranslationOutput | null>;
     /**

package/dist/server/modules/translation-providers/OpenAITranslation.provider.js

@@ -1,21 +1,21 @@
-import OpenAI from 'openai';
-import { isObject } from '../../shared';
+import OpenAI from "openai";
+import { isObject } from "../../shared";
 /** @deprecated Use `createOpenAIProvider` function instead */ export class OpenAITranslationProvider {
-    config;
     openAiClient;
+    config;
     constructor(config){
-        this.config = config;
         this.openAiClient = new OpenAI({
             apiKey: config.apiKey
         });
+        this.config = config;
     }
     async translate(content, souceLng, targetLng) {
         if (this.config.dryRun) {
-            console.info('[DRY RUN] Translation simulation:', {
+            console.info("[DRY RUN] Translation simulation:", {
                 content,
                 sourceLang: souceLng,
                 targetLang: targetLng,
-                provider: 'OpenAI'
+                provider: "OpenAI"
             });
             const timeout = this.getDryRunTimeout();
             if (timeout > 0) await new Promise((resolve)=>setTimeout(resolve, timeout));
@@ -26,21 +26,21 @@ import { isObject } from '../../shared';
         const chatCompletion = await this.openAiClient.chat.completions.create({
             messages: [
                 {
-                    role: 'system',
+                    role: "system",
                     content: systemPrompt
                 },
                 {
-                    role: 'user',
+                    role: "user",
                     content: JSON.stringify(content)
                 }
             ],
-            model: this.config.model ?? 'gpt-4o',
+            model: this.config.model ?? "gpt-4o",
             temperature: 0,
             top_p: 1,
             frequency_penalty: 0,
             presence_penalty: 0,
             response_format: {
-                type: 'json_object'
+                type: "json_object"
             }
         });
         const translatedContent = chatCompletion.choices[0].message.content;
@@ -54,7 +54,7 @@ import { isObject } from '../../shared';
     /**
    * Builds the system prompt for translation.
    */ buildSystemPrompt(sourceLang, targetLang) {
-        const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLang ? ` from ${sourceLang}` : ''} into ${targetLang}. Keep all JSON keys exactly as they are, only translate the values.
+        const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLang ? ` from ${sourceLang}` : ""} into ${targetLang}. Keep all JSON keys exactly as they are, only translate the values.
 The response should be a valid JSON object with the same structure and keys as the input, but with translated values.
 Maintain any special formatting, placeholders, or variables within the values if they exist.`;
         if (this.config.systemPrompt) {
@@ -71,17 +71,17 @@ Maintain any special formatting, placeholders, or variables within the values if
    * If dryRun is an object with transform, returns it.
    * If dryRun is true, returns the default transformer that reverses text.
    */ getDryRunTransformer() {
-        if (typeof this.config.dryRun === 'object' && this.config.dryRun.transform) {
+        if (typeof this.config.dryRun === "object" && this.config.dryRun.transform) {
             return this.config.dryRun.transform;
         }
-        return (text)=>text.split('').reverse().join('');
+        return (text)=>text.split("").reverse().join("");
     }
     /**
    * Returns the timeout for dry run mode.
    * If dryRun is an object with timeout, returns it.
    * Otherwise returns 0 (no delay).
    */ getDryRunTimeout() {
-        if (typeof this.config.dryRun === 'object' && this.config.dryRun.timeout) {
+        if (typeof this.config.dryRun === "object" && this.config.dryRun.timeout) {
             return this.config.dryRun.timeout;
         }
         return 0;
@@ -89,7 +89,7 @@ Maintain any special formatting, placeholders, or variables within the values if
     async createMockTranslation(content, transformer) {
         try {
             const mockTranslation = await this.transformObjectValues(content, async (value)=>{
-                if (typeof value === 'string' && value.trim()) return transformer(value);
+                if (typeof value === "string" && value.trim()) return transformer(value);
                 return value;
             });
             return mockTranslation;

package/dist/types/AccessGuard.d.ts

@@ -1,10 +1,33 @@
-import type { BasePayload, TypedUser } from 'payload';
+import type { BasePayload, TypedUser } from "payload";
+/**
+ * The request context an {@link AccessGuard} receives when deciding whether to
+ * allow a translation API call.
+ */
 export type AccessGuardRequest = {
+    /** Incoming request headers (e.g. for token/cookie checks). */
     headers: Headers;
+    /** The authenticated user, or `null`/`undefined` if the request is anonymous. */
     user?: TypedUser | null;
+    /** The Payload instance, for any DB/permission lookups the guard needs. */
     payload: BasePayload;
 };
+/**
+ * Gate for the translation API endpoints. Provide one via `translatorPlugin({ access })`
+ * to control who may trigger translations; omit it to leave the endpoints open.
+ *
+ * @example
+ * ```ts
+ * const adminsOnly: AccessGuard = {
+ *   check: ({ req }) => req.user?.role === 'admin',
+ * }
+ * translatorPlugin({ collections, translationProvider, runner, access: adminsOnly })
+ * ```
+ */
 export interface AccessGuard {
+    /**
+     * Return `true` to allow the request, `false` to reject it with `403 Forbidden`.
+     * May be async (e.g. to query permissions).
+     */
     check<R extends AccessGuardRequest>({ req }: {
         req: R;
     }): Promise<boolean> | boolean;

package/dist/types/AccessGuard.js

@@ -1,3 +1,14 @@
-export { };
+/**
+ * Gate for the translation API endpoints. Provide one via `translatorPlugin({ access })`
+ * to control who may trigger translations; omit it to leave the endpoints open.
+ *
+ * @example
+ * ```ts
+ * const adminsOnly: AccessGuard = {
+ *   check: ({ req }) => req.user?.role === 'admin',
+ * }
+ * translatorPlugin({ collections, translationProvider, runner, access: adminsOnly })
+ * ```
+ */ export { };
 
 //# sourceMappingURL=AccessGuard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",