@focus-reactive/payload-plugin-translator 0.1.5 → 0.2.0

package/README.md

@@ -32,14 +32,14 @@ yarn add @focus-reactive/payload-plugin-translator
 ## Quick Start
 
 ```typescript
-import { buildConfig } from 'payload'
+import { buildConfig } from "payload";
 import {
   translatorPlugin,
   createOpenAIProvider,
   createPayloadJobsRunner,
-} from '@focus-reactive/payload-plugin-translator'
-import { Posts } from './collections/Posts'
-import { Pages } from './collections/Pages'
+} from "@focus-reactive/payload-plugin-translator";
+import { Posts } from "./collections/Posts";
+import { Pages } from "./collections/Pages";
 
 export default buildConfig({
   collections: [Posts, Pages],
@@ -53,10 +53,10 @@ export default buildConfig({
     }),
   ],
   localization: {
-    locales: ['en', 'de', 'fr'],
-    defaultLocale: 'en',
+    locales: ["en", "de", "fr"],
+    defaultLocale: "en",
   },
-})
+});
 ```
 
 ## Configuration
@@ -65,7 +65,6 @@ export default buildConfig({
 
 Configuration for `translatorPlugin()`.
 
-
 | Property              | Type                  | Required | Default        | Description                                                                                                         |
 | --------------------- | --------------------- | -------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `collections`         | `CollectionConfig[]`  | Yes      | —              | Original collection configs to enable translation for. Must be the same objects passed to `buildConfig`, not slugs. |
@@ -74,38 +73,37 @@ Configuration for `translatorPlugin()`.
 | `access`              | `AccessGuard`         | No       | `undefined`    | Access control function for translation endpoints                                                                   |
 | `basePath`            | `string`              | No       | `'/translate'` | Base path for all API endpoints                                                                                     |
 
-
 ```typescript
 translatorPlugin({
   collections: [Posts, Pages],
-  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  translationProvider: createOpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY,
+  }),
   runner: createPayloadJobsRunner(),
-  access: async ({ req }) => req.user?.role === 'admin',
-  basePath: '/translate',
-})
+  access: async ({ req }) => req.user?.role === "admin",
+  basePath: "/translate",
+});
 ```
 
 ### OpenAIProviderConfig
 
 Configuration for `createOpenAIProvider()`.
 
-
-| Property       | Type                     | Required | Default         | Description                                |
-| -------------- | ------------------------ | -------- | --------------- | ------------------------------------------ |
-| `apiKey`       | `string`                 | Yes      | —               | OpenAI API key                             |
-| `model`        | `string | ChatModel`     | No       | `'gpt-4o'`      | OpenAI model to use for translation        |
-| `systemPrompt` | `SystemPromptBuilder`    | No       | Built-in prompt | Custom function to build the system prompt |
-| `dryRun`       | `boolean | DryRunConfig` | No       | `false`         | Simulate translations without API calls    |
-
+| Property       | Type                      | Required | Default         | Description                                |
+| -------------- | ------------------------- | -------- | --------------- | ------------------------------------------ |
+| `apiKey`       | `string`                  | Yes      | —               | OpenAI API key                             |
+| `model`        | `string \| ChatModel`     | No       | `'gpt-4o'`      | OpenAI model to use for translation        |
+| `systemPrompt` | `SystemPromptBuilder`     | No       | Built-in prompt | Custom function to build the system prompt |
+| `dryRun`       | `boolean \| DryRunConfig` | No       | `false`         | Simulate translations without API calls    |
 
 ```typescript
 createOpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-4o-mini',
+  model: "gpt-4o-mini",
   systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) =>
     `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`,
   dryRun: false,
-})
+});
 ```
 
 #### SystemPromptBuilder
@@ -113,13 +111,13 @@ createOpenAIProvider({
 Function signature for custom system prompt:
 
 ```typescript
-type SystemPromptBuilder = (context: SystemPromptContext) => string
+type SystemPromptBuilder = (context: SystemPromptContext) => string;
 
 type SystemPromptContext = {
-  sourceLang: string
-  targetLang: string
-  defaultPrompt: string
-}
+  sourceLang: string;
+  targetLang: string;
+  defaultPrompt: string;
+};
 ```
 
 #### DryRunConfig
@@ -127,64 +125,61 @@ type SystemPromptContext = {
 When `dryRun` is an object, it allows custom transformation with optional delay:
 
 ```typescript
-type DryRunTransformer = (text: string) => string | Promise<string>
+type DryRunTransformer = (text: string) => string | Promise<string>;
 
 type DryRunConfig = {
-  transform: DryRunTransformer // Custom transformer function
-  timeout?: number // Delay in ms (simulates API latency)
-}
+  transform: DryRunTransformer; // Custom transformer function
+  timeout?: number; // Delay in ms (simulates API latency)
+};
 ```
 
 ### PayloadJobsRunnerOptions
 
 Configuration for `createPayloadJobsRunner()`.
 
-
-| Property    | Type                      | Required | Default                            | Description                                             |
-| ----------- | ------------------------- | -------- | ---------------------------------- | ------------------------------------------------------- |
-| `taskName`  | `string`                  | No       | `'translate_document'`             | Task name in Payload jobs collection                    |
-| `queueName` | `string`                  | No       | `'translations'`                   | Queue name for grouping jobs                            |
-| `autoRun`   | `false | { cron, limit }` | No       | `{ cron: '* * * * *', limit: 50 }` | Auto-run config, or `false` to disable (for serverless) |
-
+| Property    | Type                       | Required | Default                            | Description                                             |
+| ----------- | -------------------------- | -------- | ---------------------------------- | ------------------------------------------------------- |
+| `taskName`  | `string`                   | No       | `'translate_document'`             | Task name in Payload jobs collection                    |
+| `queueName` | `string`                   | No       | `'translations'`                   | Queue name for grouping jobs                            |
+| `autoRun`   | `false \| { cron, limit }` | No       | `{ cron: '* * * * *', limit: 50 }` | Auto-run config, or `false` to disable (for serverless) |
 
 ```typescript
 createPayloadJobsRunner({
-  taskName: 'translate_document',
-  queueName: 'translations',
+  taskName: "translate_document",
+  queueName: "translations",
   autoRun: {
-    cron: '* * * * *',
+    cron: "* * * * *",
     limit: 50,
   },
-})
+});
 ```
 
 ### FieldTranslationConfig
 
 Configuration for `withFieldTranslation()` helper or `field.custom.translateKit`.
 
-
 | Property  | Type      | Required | Default | Description                         |
 | --------- | --------- | -------- | ------- | ----------------------------------- |
 | `exclude` | `boolean` | No       | `false` | Exclude this field from translation |
 
-
 ```typescript
-import { withFieldTranslation } from '@focus-reactive/payload-plugin-translator'
+import { withFieldTranslation } from "@focus-reactive/payload-plugin-translator";
 
-withFieldTranslation({ name: 'sku', type: 'text', localized: true }, { exclude: true })
+withFieldTranslation(
+  { name: "sku", type: "text", localized: true },
+  { exclude: true },
+);
 ```
 
 ## Translation Strategies
 
 When translating, you can choose how to handle existing translations:
 
-
 | Strategy          | Description                                                              |
 | ----------------- | ------------------------------------------------------------------------ |
 | `'overwrite'`     | (Default) Replaces all existing translated content with new translations |
 | `'skip_existing'` | Only translates fields that are empty in the target locale               |
 
-
 ## Important Notes
 
 ### Explicit `localized: true` for nested fields
@@ -239,7 +234,7 @@ export default buildConfig({
   jobs: {
     deleteJobOnComplete: false,
   },
-})
+});
 ```
 
 ## Task Runners
@@ -249,16 +244,16 @@ export default buildConfig({
 Uses Payload's built-in job queue for background processing:
 
 ```typescript
-import { createPayloadJobsRunner } from '@focus-reactive/payload-plugin-translator'
+import { createPayloadJobsRunner } from "@focus-reactive/payload-plugin-translator";
 
 const runner = createPayloadJobsRunner({
-  taskName: 'translate_document',
-  queueName: 'translations',
+  taskName: "translate_document",
+  queueName: "translations",
   autoRun: {
-    cron: '* * * * *',
+    cron: "* * * * *",
     limit: 50,
   },
-})
+});
 ```
 
 ### SyncRunner
@@ -266,9 +261,9 @@ const runner = createPayloadJobsRunner({
 Executes translations synchronously (useful for development or small datasets):
 
 ```typescript
-import { createSyncRunner } from '@focus-reactive/payload-plugin-translator'
+import { createSyncRunner } from "@focus-reactive/payload-plugin-translator";
 
-const runner = createSyncRunner()
+const runner = createSyncRunner();
 ```
 
 ## Translation Providers
@@ -278,13 +273,13 @@ const runner = createSyncRunner()
 Built-in provider using OpenAI's API:
 
 ```typescript
-import { createOpenAIProvider } from '@focus-reactive/payload-plugin-translator'
+import { createOpenAIProvider } from "@focus-reactive/payload-plugin-translator";
 
 const provider = createOpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY,
-  model: 'gpt-4o-mini',
+  model: "gpt-4o-mini",
   systemPrompt: ({ defaultPrompt }) => `${defaultPrompt}\nUse formal language.`,
-})
+});
 ```
 
 ### Custom Provider
@@ -293,11 +288,9 @@ Create your own translation provider by implementing the `TranslationProvider` i
 
 #### TranslationProvider Interface
 
-
-| Method      | Signature                                                                                                | Description                                       |
-| ----------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `translate` | `(content: TranslationInput, sourceLng: string, targetLng: string) => Promise<TranslationOutput | null>` | Translates content from source to target language |
-
+| Method      | Signature                                                                                                 | Description                                       |
+| ----------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `translate` | `(content: TranslationInput, sourceLng: string, targetLng: string) => Promise<TranslationOutput \| null>` | Translates content from source to target language |
 
 **Important:** The numeric indices in `TranslationInput` must be preserved exactly in `TranslationOutput`. Each index maps to a specific field in the document structure, so the provider must return the same keys with translated values.
 
@@ -305,13 +298,13 @@ Create your own translation provider by implementing the `TranslationProvider` i
 
 ```typescript
 // Numeric index representing position in document structure
-type TranslationIndex = number
+type TranslationIndex = number;
 
 // Input: Map of numeric indices to text strings
-type TranslationInput = Record<TranslationIndex, string>
+type TranslationInput = Record<TranslationIndex, string>;
 
 // Output: Same indices with translated values
-type TranslationOutput = Record<TranslationIndex, string>
+type TranslationOutput = Record<TranslationIndex, string>;
 ```
 
 #### Example Implementation
@@ -321,40 +314,44 @@ import type {
   TranslationProvider,
   TranslationInput,
   TranslationOutput,
-} from '@focus-reactive/payload-plugin-translator'
+} from "@focus-reactive/payload-plugin-translator";
 
 class DeepLProvider implements TranslationProvider {
   constructor(private apiKey: string) {}
 
-  async translate(content: TranslationInput, sourceLng: string, targetLng: string): Promise<TranslationOutput | null> {
+  async translate(
+    content: TranslationInput,
+    sourceLng: string,
+    targetLng: string,
+  ): Promise<TranslationOutput | null> {
     try {
       // content example: { "0": "Hello", "1": "World" }
-      const texts = Object.values(content)
+      const texts = Object.values(content);
 
-      const response = await fetch('https://api.deepl.com/v2/translate', {
-        method: 'POST',
+      const response = await fetch("https://api.deepl.com/v2/translate", {
+        method: "POST",
         headers: {
           Authorization: `DeepL-Auth-Key ${this.apiKey}`,
-          'Content-Type': 'application/json',
+          "Content-Type": "application/json",
         },
         body: JSON.stringify({
           text: texts,
           source_lang: sourceLng.toUpperCase(),
           target_lang: targetLng.toUpperCase(),
         }),
-      })
+      });
 
-      const data = await response.json()
+      const data = await response.json();
 
       // Reconstruct the result with same keys
-      const result: TranslationOutput = {}
+      const result: TranslationOutput = {};
       Object.keys(content).forEach((key, index) => {
-        result[key] = data.translations[index].text
-      })
+        result[key] = data.translations[index].text;
+      });
 
-      return result
+      return result;
     } catch {
-      return null
+      return null;
     }
   }
 }
@@ -364,7 +361,7 @@ translatorPlugin({
   collections: [Posts],
   translationProvider: new DeepLProvider(process.env.DEEPL_API_KEY),
   runner: createPayloadJobsRunner(),
-})
+});
 ```
 
 ## UI Components
@@ -404,17 +401,9 @@ import type {
 
   // Field config
   FieldTranslationConfig,
-} from '@focus-reactive/payload-plugin-translator'
+} from "@focus-reactive/payload-plugin-translator";
 ```
 
-## Known Issues
-
-### SQLite: Nested JSON queries not supported
-
-SQLite adapter doesn't support nested JSON field queries like `{ 'input.collection.value': { equals: '5' } }`.
-
-**Affected databases:** SQLite only
-
 ## Roadmap
 
 Planned features for future releases:
@@ -423,4 +412,3 @@ Planned features for future releases:
 - **Global translation dashboard** — Translate all collections at once from a single interface, with progress tracking across the entire CMS
 - **Vercel Cron Jobs runner** — Built-in runner for seamless Vercel/serverless deployments without manual API route configuration
 - Auto-translate on source change — Automatically trigger translation when the default locale content is updated
-

package/dist/client/features/collection-translation-form/model/form-model.d.ts

@@ -1,5 +1,5 @@
-import type { UseFormReturn } from 'react-hook-form';
-import type { FormInput, FormValues } from './schema';
+import type { UseFormReturn } from "react-hook-form";
+import type { FormInput, FormValues } from "./schema";
 type UseFormReturn_ = {
     form: UseFormReturn<FormValues>;
 };

package/dist/client/features/collection-translation-form/model/form-model.js

@@ -1,9 +1,9 @@
-'use client';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useEffect, useMemo } from 'react';
-import { useForm } from 'react-hook-form';
-import { defaultValues } from './constants';
-import { validationSchema } from './schema';
+"use client";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useEffect, useMemo, useRef } from "react";
+import { useForm } from "react-hook-form";
+import { defaultValues } from "./constants";
+import { validationSchema } from "./schema";
 export const useCollectionTranslationForm = ({ initialValues, disabled } = {})=>{
     const defaultFormValues = useMemo(()=>({
             ...defaultValues,
@@ -14,15 +14,18 @@ export const useCollectionTranslationForm = ({ initialValues, disabled } = {})=>
     const form = useForm({
         defaultValues: defaultFormValues,
         resolver: zodResolver(validationSchema),
-        mode: 'onTouched',
+        mode: "onTouched",
         disabled
     });
+    const isFirstRender = useRef(true);
     useEffect(()=>{
+        if (isFirstRender.current) {
+            isFirstRender.current = false;
+            return;
+        }
         form.reset(defaultFormValues);
     }, [
-        defaultFormValues,
-        form,
-        form.reset
+        defaultFormValues
     ]);
     return {
         form

package/dist/client/features/translate-document-form/model/form-model.d.ts

@@ -1,5 +1,5 @@
-import type { UseFormReturn } from 'react-hook-form';
-import type { FormInput, FormValues } from './schema';
+import type { UseFormReturn } from "react-hook-form";
+import type { FormInput, FormValues } from "./schema";
 type UseFormReturn_ = {
     form: UseFormReturn<FormValues>;
 };

package/dist/client/features/translate-document-form/model/form-model.js

@@ -1,9 +1,9 @@
-'use client';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useEffect, useMemo } from 'react';
-import { useForm } from 'react-hook-form';
-import { defaultValues } from './constants';
-import { validationSchema } from './schema';
+"use client";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useEffect, useMemo, useRef } from "react";
+import { useForm } from "react-hook-form";
+import { defaultValues } from "./constants";
+import { validationSchema } from "./schema";
 export const useTranslateDocumentForm = ({ initialValues, disabled } = {})=>{
     const defaultFormValues = useMemo(()=>({
             ...defaultValues,
@@ -14,15 +14,18 @@ export const useTranslateDocumentForm = ({ initialValues, disabled } = {})=>{
     const form = useForm({
         defaultValues: defaultFormValues,
         resolver: zodResolver(validationSchema),
-        mode: 'onTouched',
+        mode: "onTouched",
         disabled
     });
+    const isFirstRender = useRef(true);
     useEffect(()=>{
+        if (isFirstRender.current) {
+            isFirstRender.current = false;
+            return;
+        }
         form.reset(defaultFormValues);
     }, [
-        defaultFormValues,
-        form,
-        form.reset
+        defaultFormValues
     ]);
     return {
         form

package/dist/server/features/cancel/model.d.ts

@@ -1,11 +1,11 @@
-import { z } from 'zod';
+import { z } from "zod";
 /**
- * Input validation schema for batch cancel
+ * Input validation schema for batch cancel.
  */
 export declare const CancelInputSchema: z.ZodObject<{
-    ids: z.ZodArray<z.ZodString, "many">;
+    ids: z.ZodArray<z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>, "many">;
 }, "strip", z.ZodTypeAny, {
     ids: string[];
 }, {
-    ids: string[];
+    ids: (string | number)[];
 }>;

package/dist/server/features/cancel/model.js

@@ -1,8 +1,9 @@
-import { z } from 'zod';
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
 /**
- * Input validation schema for batch cancel
+ * Input validation schema for batch cancel.
  */ export const CancelInputSchema = z.object({
-    ids: z.array(z.string().nonempty()).min(1)
+    ids: z.array(JobIdSchema).min(1)
 });
 
 //# sourceMappingURL=model.js.map

package/dist/server/features/get-document-status/model.d.ts

@@ -1,18 +1,22 @@
-import { z } from 'zod';
-import type { CollectionSlug } from 'payload';
-import type { Task, TaskStatus } from '../../modules/task-runner';
+import { z } from "zod";
+import type { CollectionSlug } from "payload";
+import type { Task, TaskStatus } from "../../modules/task-runner";
 /**
- * Input validation schema
+ * Input validation schema.
+ *
+ * `collection_id` accepts any of the shapes Payload allows as a document ID
+ * (integer autoincrement, UUID, MongoDB ObjectId, etc.). See JobIdSchema for
+ * the rationale.
  */
 export declare const GetDocumentStatusInputSchema: z.ZodObject<{
-    collection_id: z.ZodEffects<z.ZodString, string, string>;
+    collection_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
     collection_slug: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     collection_slug: string;
     collection_id: string;
 }, {
     collection_slug: string;
-    collection_id: string;
+    collection_id: string | number;
 }>;
 export type GetDocumentStatusInput = z.infer<typeof GetDocumentStatusInputSchema>;
 /**

package/dist/server/features/get-document-status/model.js

@@ -1,10 +1,13 @@
-import { z } from 'zod';
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
 /**
- * Input validation schema
+ * Input validation schema.
+ *
+ * `collection_id` accepts any of the shapes Payload allows as a document ID
+ * (integer autoincrement, UUID, MongoDB ObjectId, etc.). See JobIdSchema for
+ * the rationale.
  */ export const GetDocumentStatusInputSchema = z.object({
-    collection_id: z.coerce.string().refine((val)=>val.length > 0 && val !== 'undefined', {
-        message: 'Required'
-    }),
+    collection_id: JobIdSchema,
     collection_slug: z.string().nonempty()
 });
 /**

package/dist/server/features/run-translation/model.d.ts

@@ -1,11 +1,15 @@
-import { z } from 'zod';
+import { z } from "zod";
 /**
- * Input validation schema
+ * Input validation schema.
+ *
+ * `id` comes from the URL route param (always a string at the HTTP edge),
+ * but we reuse the canonical JobIdSchema so the contract stays consistent
+ * with batch cancel.
  */
 export declare const RunInputSchema: z.ZodObject<{
-    id: z.ZodString;
+    id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
 }, "strip", z.ZodTypeAny, {
     id: string;
 }, {
-    id: string;
+    id: string | number;
 }>;

package/dist/server/features/run-translation/model.js

@@ -1,8 +1,13 @@
-import { z } from 'zod';
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
 /**
- * Input validation schema
+ * Input validation schema.
+ *
+ * `id` comes from the URL route param (always a string at the HTTP edge),
+ * but we reuse the canonical JobIdSchema so the contract stays consistent
+ * with batch cancel.
  */ export const RunInputSchema = z.object({
-    id: z.string().nonempty()
+    id: JobIdSchema
 });
 
 //# sourceMappingURL=model.js.map

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.d.ts

@@ -1,7 +1,7 @@
-import type { Payload, CollectionSlug } from 'payload';
-import type { TaskRunner } from '../TaskRunner.interface';
-import type { Task, TaskInput, RunResult } from '../types';
-import type { PayloadJobsRunnerConfig } from './types';
+import type { Payload, CollectionSlug } from "payload";
+import type { TaskRunner } from "../TaskRunner.interface";
+import type { Task, TaskInput, RunResult } from "../types";
+import type { PayloadJobsRunnerConfig } from "./types";
 /**
  * TaskRunner implementation using Payload Jobs.
  *
@@ -14,6 +14,82 @@ export declare class PayloadJobsTaskRunner implements TaskRunner {
     enqueue(tasks: TaskInput[]): Promise<void>;
     cancel(taskIds: string[]): Promise<void>;
     run(taskId: string): Promise<RunResult>;
+    /**
+     * Find translation jobs for a collection, optionally narrowed by document IDs.
+     *
+     * IMPORTANT — why we filter `collection.value` in memory instead of in WHERE
+     * ------------------------------------------------------------------------
+     * The "natural" implementation would be a single `payload.find` with the
+     * full where clause:
+     *
+     *     where: {
+     *       and: [
+     *         { 'input.collection.relationTo': { equals: collectionSlug } },
+     *         { 'input.collection.value':      { in: documentIds } },
+     *       ],
+     *     }
+     *
+     * This DOES NOT work on SQLite (and is unreliable on any adapter) because
+     * of two compounding bugs in Payload's drizzle layer.
+     *
+     * 1. The `input` field on `payload-jobs` is declared `type: 'json'`. The
+     *    drizzle path resolver (`@payloadcms/drizzle/queries/getTableColumnFromPath`)
+     *    has no `case 'json'` branch, so the value is left as a raw column and
+     *    the path segments are passed through to `parseParams.js`, which on
+     *    SQLite builds raw SQL using `convertPathToJSONTraversal` — generating
+     *    expressions like `input->>'collection'->>'value'`.
+     *
+     * 2. When `parseParams.js` formats the right-hand side of `in`/`not_in`
+     *    (and even `equals` when `!isNaN(val)`), it inlines values via JS
+     *    template literals WITHOUT wrapping strings in quotes. The string
+     *    `'1'` from our WHERE becomes raw `1` in the SQL. Drizzle therefore
+     *    emits queries like:
+     *
+     *        WHERE input->>'collection'->>'value' IN (1)
+     *
+     *    even though the caller passed `['1']` (an array of strings).
+     *
+     * On SQLite, `->>` preserves the JSON value's type — if the stored JSON
+     * has `"value": "1"` (a JSON string), `->>` returns SQLite TEXT `'1'`;
+     * if the JSON has `"value": 1` (a JSON number), `->>` returns INTEGER `1`.
+     * SQLite's `IN (...)` does NOT coerce between TEXT and INTEGER. So:
+     *
+     *     TEXT '1'    IN (1)    → false   (text vs integer, no match)
+     *     INTEGER 1   IN ('1')  → false   (integer vs text, no match)
+     *
+     * Combined with bug #2 above, any value passed by the caller — even if
+     * we normalize it to a string on write — gets re-coerced to a number in
+     * the generated SQL and never matches the stored JSON.
+     *
+     * Postgres avoids most of this because `jsonb_path_query` returns text
+     * uniformly and PG's type coercion is more permissive, but the same
+     * un-quoted-string bug technically affects it too.
+     *
+     * Why we don't fix it upstream / patch the dep
+     * --------------------------------------------
+     * - This plugin is published to npm. Consumers install it with their own
+     *   Payload version and would not receive any local `bun patch` /
+     *   `patch-package` overrides on `@payloadcms/drizzle`. The plugin must
+     *   work against vanilla Payload.
+     * - A PR to Payload core is the proper long-term fix, but the plugin
+     *   cannot block on its merge/release cycle.
+     * - Forcing a non-numeric prefix on the stored ID (e.g., `"id:1"`) would
+     *   work around bug #2, but bloats the data shape and breaks anything
+     *   that reads `input.collection.value` expecting a plain id.
+     *
+     * Why in-memory filtering is acceptable here
+     * ------------------------------------------
+     * We narrow the SQL query to `taskSlug + relationTo` (both string
+     * equality, which Payload quotes correctly), then filter the result set
+     * by `collection.value` in JavaScript. Per-collection job sets are
+     * small (typically <100 rows; the plugin actively cancels superseded
+     * jobs so they don't accumulate), so a Set-membership check in JS is
+     * effectively free.
+     *
+     * If/when the upstream drizzle bug is fixed (or this plugin gains a
+     * mirror collection with indexed flat columns), this method can collapse
+     * back to a single SQL query.
+     */
     findByCollection(collectionSlug: CollectionSlug, documentIds?: Array<string | number>): Promise<Task[]>;
     /**
      * Group tasks by collection slug

package/dist/server/modules/task-runner/payload-jobs-runner/PayloadJobsTaskRunner.js

@@ -1,4 +1,4 @@
-import { normalizeJob } from './normalizeJob';
+import { normalizeJob } from "./normalizeJob";
 /**
  * TaskRunner implementation using Payload Jobs.
  *
@@ -13,21 +13,8 @@ import { normalizeJob } from './normalizeJob';
     async enqueue(tasks) {
         const byCollection = this.groupByCollection(tasks);
         for (const [collectionSlug, items] of byCollection){
-            const documentIds = items.map((t)=>t.collectionId);
-            const existing = await this.findJobsInternal({
-                and: [
-                    {
-                        'input.collection.relationTo': {
-                            equals: collectionSlug
-                        }
-                    },
-                    {
-                        'input.collection.value': {
-                            in: documentIds
-                        }
-                    }
-                ]
-            });
+            const documentIds = items.map((t)=>String(t.collectionId));
+            const existing = await this.findByCollection(collectionSlug, documentIds);
             if (existing.length > 0) {
                 await this.cancelInternal(existing.map((t)=>t.id));
             }
@@ -37,6 +24,15 @@ import { normalizeJob } from './normalizeJob';
                 queue: this.config.queueName,
                 input: {
                     collection: {
+                        // Pass `value` through verbatim. The Payload Jobs `input` schema
+                        // declares this as a `relationship` field, which validates the
+                        // value's type against the target collection's ID type (number
+                        // for autoincrement, string for uuid). Coercing to string here
+                        // would silently fail validation for number-id collections and
+                        // leave jobs stuck in processing without ever invoking the
+                        // task handler. `findByCollection` reads back via in-memory
+                        // filtering and normalizes both sides with String(...) for the
+                        // comparison, so it does not need write-side normalization.
                         relationTo: task.collectionSlug,
                         value: task.collectionId
                     },
@@ -63,19 +59,19 @@ import { normalizeJob } from './normalizeJob';
         if (!task) {
             return {
                 success: false,
-                error: 'not_found'
+                error: "not_found"
             };
         }
         if (task.completedAt) {
             return {
                 success: false,
-                error: 'already_completed'
+                error: "already_completed"
             };
         }
-        if (task.status === 'running') {
+        if (task.status === "running") {
             return {
                 success: false,
-                error: 'already_running'
+                error: "already_running"
             };
         }
         this.payload.jobs.runByID({
@@ -85,28 +81,92 @@ import { normalizeJob } from './normalizeJob';
             success: true
         };
     }
-    async findByCollection(collectionSlug, documentIds) {
-        const where = documentIds?.length ? {
-            and: [
-                {
-                    'input.collection.relationTo': {
-                        equals: collectionSlug
-                    }
-                },
-                {
-                    'input.collection.value': {
-                        in: documentIds
-                    }
-                }
-            ]
-        } : {
-            'input.collection.relationTo': {
+    /**
+   * Find translation jobs for a collection, optionally narrowed by document IDs.
+   *
+   * IMPORTANT — why we filter `collection.value` in memory instead of in WHERE
+   * ------------------------------------------------------------------------
+   * The "natural" implementation would be a single `payload.find` with the
+   * full where clause:
+   *
+   *     where: {
+   *       and: [
+   *         { 'input.collection.relationTo': { equals: collectionSlug } },
+   *         { 'input.collection.value':      { in: documentIds } },
+   *       ],
+   *     }
+   *
+   * This DOES NOT work on SQLite (and is unreliable on any adapter) because
+   * of two compounding bugs in Payload's drizzle layer.
+   *
+   * 1. The `input` field on `payload-jobs` is declared `type: 'json'`. The
+   *    drizzle path resolver (`@payloadcms/drizzle/queries/getTableColumnFromPath`)
+   *    has no `case 'json'` branch, so the value is left as a raw column and
+   *    the path segments are passed through to `parseParams.js`, which on
+   *    SQLite builds raw SQL using `convertPathToJSONTraversal` — generating
+   *    expressions like `input->>'collection'->>'value'`.
+   *
+   * 2. When `parseParams.js` formats the right-hand side of `in`/`not_in`
+   *    (and even `equals` when `!isNaN(val)`), it inlines values via JS
+   *    template literals WITHOUT wrapping strings in quotes. The string
+   *    `'1'` from our WHERE becomes raw `1` in the SQL. Drizzle therefore
+   *    emits queries like:
+   *
+   *        WHERE input->>'collection'->>'value' IN (1)
+   *
+   *    even though the caller passed `['1']` (an array of strings).
+   *
+   * On SQLite, `->>` preserves the JSON value's type — if the stored JSON
+   * has `"value": "1"` (a JSON string), `->>` returns SQLite TEXT `'1'`;
+   * if the JSON has `"value": 1` (a JSON number), `->>` returns INTEGER `1`.
+   * SQLite's `IN (...)` does NOT coerce between TEXT and INTEGER. So:
+   *
+   *     TEXT '1'    IN (1)    → false   (text vs integer, no match)
+   *     INTEGER 1   IN ('1')  → false   (integer vs text, no match)
+   *
+   * Combined with bug #2 above, any value passed by the caller — even if
+   * we normalize it to a string on write — gets re-coerced to a number in
+   * the generated SQL and never matches the stored JSON.
+   *
+   * Postgres avoids most of this because `jsonb_path_query` returns text
+   * uniformly and PG's type coercion is more permissive, but the same
+   * un-quoted-string bug technically affects it too.
+   *
+   * Why we don't fix it upstream / patch the dep
+   * --------------------------------------------
+   * - This plugin is published to npm. Consumers install it with their own
+   *   Payload version and would not receive any local `bun patch` /
+   *   `patch-package` overrides on `@payloadcms/drizzle`. The plugin must
+   *   work against vanilla Payload.
+   * - A PR to Payload core is the proper long-term fix, but the plugin
+   *   cannot block on its merge/release cycle.
+   * - Forcing a non-numeric prefix on the stored ID (e.g., `"id:1"`) would
+   *   work around bug #2, but bloats the data shape and breaks anything
+   *   that reads `input.collection.value` expecting a plain id.
+   *
+   * Why in-memory filtering is acceptable here
+   * ------------------------------------------
+   * We narrow the SQL query to `taskSlug + relationTo` (both string
+   * equality, which Payload quotes correctly), then filter the result set
+   * by `collection.value` in JavaScript. Per-collection job sets are
+   * small (typically <100 rows; the plugin actively cancels superseded
+   * jobs so they don't accumulate), so a Set-membership check in JS is
+   * effectively free.
+   *
+   * If/when the upstream drizzle bug is fixed (or this plugin gains a
+   * mirror collection with indexed flat columns), this method can collapse
+   * back to a single SQL query.
+   */ async findByCollection(collectionSlug, documentIds) {
+        const tasks = await this.findJobsInternal({
+            "input.collection.relationTo": {
                 equals: collectionSlug
             }
-        };
-        return this.findJobsInternal(where, {
+        }, {
             pagination: false
         });
+        if (!documentIds?.length) return tasks;
+        const wanted = new Set(documentIds.map(String));
+        return tasks.filter((t)=>wanted.has(String(t.input.collectionId)));
     }
     /**
    * Group tasks by collection slug

package/dist/server/shared/index.d.ts

@@ -1,10 +1,11 @@
-export { ServerResponse, withErrorHandler, withAccessCheck } from './http';
-export { AnyAccessGuard } from './access';
-export type { AccessGuard, AccessGuardRequest, Handler } from './access';
-export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields } from './utils';
-export type { TranslatableField } from './guards';
-export { isTranslatableField, isLocalizedField, isRelationshipField, isTabsField, isBlockItem, hasFields, } from './guards';
-export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig } from './field-config';
-export type { TranslateKitFieldConfig } from './field-config';
-export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes, } from './lexical';
-export type { SerializedTextNodeRef } from './lexical';
+export { ServerResponse, withErrorHandler, withAccessCheck } from "./http";
+export { AnyAccessGuard } from "./access";
+export type { AccessGuard, AccessGuardRequest, Handler } from "./access";
+export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields, } from "./utils";
+export type { TranslatableField } from "./guards";
+export { isTranslatableField, isLocalizedField, isRelationshipField, isTabsField, isBlockItem, hasFields, } from "./guards";
+export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig, } from "./field-config";
+export type { TranslateKitFieldConfig } from "./field-config";
+export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes, } from "./lexical";
+export type { SerializedTextNodeRef } from "./lexical";
+export { JobIdSchema } from "./validation";

package/dist/server/shared/index.js

@@ -1,13 +1,15 @@
 // HTTP utilities
-export { ServerResponse, withErrorHandler, withAccessCheck } from './http';
+export { ServerResponse, withErrorHandler, withAccessCheck } from "./http";
 // Access control
-export { AnyAccessGuard } from './access';
+export { AnyAccessGuard } from "./access";
 // General utilities
-export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields } from './utils';
-export { isTranslatableField, isLocalizedField, isRelationshipField, isTabsField, isBlockItem, hasFields } from './guards';
+export { isEmpty, isObject, normalizePath, pipe, getByPath, setByPath, filterLocalizedFields } from "./utils";
+export { isTranslatableField, isLocalizedField, isRelationshipField, isTabsField, isBlockItem, hasFields } from "./guards";
 // Field config
-export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig } from './field-config';
+export { isFieldExcludedFromTranslation, getTranslateKitFieldConfig } from "./field-config";
 // Lexical utilities
-export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes } from './lexical';
+export { isSerializedLexicalRoot, isEmptyRichText, traverseLexicalTree, collectSerializedLexicalTextNodes } from "./lexical";
+// Validation primitives
+export { JobIdSchema } from "./validation";
 
 //# sourceMappingURL=index.js.map

package/dist/server/shared/validation/index.d.ts

@@ -0,0 +1 @@
+export { JobIdSchema } from "./jobId";

package/dist/server/shared/validation/index.js

@@ -0,0 +1,3 @@
+export { JobIdSchema } from "./jobId";
+
+//# sourceMappingURL=index.js.map

package/dist/server/shared/validation/jobId.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Zod schema for a Payload document/job ID over the HTTP boundary.
+ *
+ * Accepts the two shapes IDs can arrive in: a JS string (UUID, MongoDB
+ * ObjectId hex, custom string id) or a JS number (SQLite/Postgres integer
+ * autoincrement). Anything else (null, undefined, boolean, object, array)
+ * is rejected by the union itself. The schema normalizes to a non-empty
+ * string so callers can compare and Set-membership-check uniformly.
+ *
+ * NOTE: This is intentionally a wire-format guard, not a domain check. We
+ * do not pattern-match for UUID v4 or ObjectId here — different deployments
+ * use different ID formats, and a stricter regex would lock the plugin to
+ * one adapter. Callers that need DB-specific validation should layer it
+ * on top.
+ */
+export declare const JobIdSchema: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;

package/dist/server/shared/validation/jobId.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+/**
+ * Zod schema for a Payload document/job ID over the HTTP boundary.
+ *
+ * Accepts the two shapes IDs can arrive in: a JS string (UUID, MongoDB
+ * ObjectId hex, custom string id) or a JS number (SQLite/Postgres integer
+ * autoincrement). Anything else (null, undefined, boolean, object, array)
+ * is rejected by the union itself. The schema normalizes to a non-empty
+ * string so callers can compare and Set-membership-check uniformly.
+ *
+ * NOTE: This is intentionally a wire-format guard, not a domain check. We
+ * do not pattern-match for UUID v4 or ObjectId here — different deployments
+ * use different ID formats, and a stricter regex would lock the plugin to
+ * one adapter. Callers that need DB-specific validation should layer it
+ * on top.
+ */ export const JobIdSchema = z.union([
+    z.string().refine((val)=>val.length > 0 && val !== "undefined", {
+        message: "ID must be a non-empty string"
+    }),
+    z.number().finite()
+]).transform(String);
+
+//# sourceMappingURL=jobId.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",
@@ -47,15 +47,15 @@
   "scripts": {
     "build": "bun run clean && bun run build:swc && bun run build:types && bun run copyfiles",
     "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths --ignore '**/*.test.ts' --ignore '**/*.d.ts' --ignore '**/__tests__/**' --ignore '**/__mocks__/**'",
-    "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "copyfiles": "copyfiles -u 1 \"src/**/*.scss\" dist",
     "clean": "rm -rf dist",
     "dev": "bun run build:swc -- --watch",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "ultracite check",
+    "lint:fix": "ultracite fix",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check-types": "tsc --noEmit"
+    "check-types": "tsgo --noEmit"
   },
   "peerDependencies": {
     "@payloadcms/richtext-lexical": "^3.76.0",
@@ -84,14 +84,9 @@
     "@types/react": "19.2.9",
     "@vitest/coverage-v8": "3.2.4",
     "copyfiles": "2.4.1",
-    "eslint": "9.0.0",
-    "eslint-config-prettier": "9.0.0",
-    "next": "15.4.11",
     "payload": "3.79.0",
     "react": "19.0.0",
     "typescript": "5.5.2",
-    "eslint-plugin-react-hooks": "6.0.0-rc.2",
-    "typescript-eslint": "8.0.0",
     "vitest": "3.2.4"
   }
 }