@focus-reactive/payload-plugin-translator 0.1.4 → 0.1.6

package/README.md

@@ -16,12 +16,15 @@ Translation plugin for Payload CMS 3.x. Automatically translate your localized c
 ## Installation
 
 ```bash
-# pnpm
-pnpm add @focus-reactive/payload-plugin-translator
-
 # npm
 npm install @focus-reactive/payload-plugin-translator
 
+# bun
+bun add @focus-reactive/payload-plugin-translator
+
+# pnpm
+pnpm add @focus-reactive/payload-plugin-translator
+
 # yarn
 yarn add @focus-reactive/payload-plugin-translator
 ```
@@ -29,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],
@@ -50,10 +53,10 @@ export default buildConfig({
     }),
   ],
   localization: {
-    locales: ['en', 'de', 'fr'],
-    defaultLocale: 'en',
+    locales: ["en", "de", "fr"],
+    defaultLocale: "en",
   },
-})
+});
 ```
 
 ## Configuration
@@ -62,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. |
@@ -71,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
@@ -110,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
@@ -124,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
@@ -236,7 +234,7 @@ export default buildConfig({
   jobs: {
     deleteJobOnComplete: false,
   },
-})
+});
 ```
 
 ## Task Runners
@@ -246,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
@@ -263,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
@@ -275,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
@@ -290,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.
 
@@ -302,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
@@ -318,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;
     }
   }
 }
@@ -361,7 +361,7 @@ translatorPlugin({
   collections: [Posts],
   translationProvider: new DeepLProvider(process.env.DEEPL_API_KEY),
   runner: createPayloadJobsRunner(),
-})
+});
 ```
 
 ## UI Components
@@ -401,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:
@@ -420,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/app/cache/CacheProvider.d.ts

@@ -2,6 +2,5 @@ import type { PropsWithChildren } from 'react';
 type CacheProviderProps = PropsWithChildren<{
     basePath?: string;
 }>;
-export declare function CacheProvider({ basePath, children }: CacheProviderProps): import("react").JSX.Element;
+export declare function CacheProvider({ basePath, children }: CacheProviderProps): import("react/jsx-runtime").JSX.Element;
 export default CacheProvider;
-//# sourceMappingURL=CacheProvider.d.ts.map

package/dist/client/app/cache/CacheProvider.export.d.ts

@@ -6,4 +6,3 @@ export declare class CacheProviderExport implements RawPayloadComponentExport {
     };
     constructor(basePath: string);
 }
-//# sourceMappingURL=CacheProvider.export.d.ts.map

package/dist/client/app/config/TranslateKitConfigContext.d.ts

@@ -3,7 +3,6 @@ type TranslateKitConfig = {
     basePath: string;
 };
 export type TranslateKitConfigProviderProps = PropsWithChildren<Partial<TranslateKitConfig>>;
-export declare function TranslateKitConfigProvider({ basePath, children, }: TranslateKitConfigProviderProps): import("react").JSX.Element;
+export declare function TranslateKitConfigProvider({ basePath, children, }: TranslateKitConfigProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useTranslateKitConfig(): TranslateKitConfig;
 export {};
-//# sourceMappingURL=TranslateKitConfigContext.d.ts.map

package/dist/client/app/config/index.d.ts

@@ -1,3 +1,2 @@
 export { TranslateKitConfigProvider, useTranslateKitConfig } from './TranslateKitConfigContext';
 export type { TranslateKitConfigProviderProps } from './TranslateKitConfigContext';
-//# sourceMappingURL=index.d.ts.map

package/dist/client/entities/translation/api/mutations/useCancelCollectionTranslations.d.ts

@@ -3,4 +3,3 @@ type Variables = {
 };
 export declare function useCancelCollectionTranslations(): import("@tanstack/react-query").UseMutationResult<void, Error, Variables, unknown>;
 export {};
-//# sourceMappingURL=useCancelCollectionTranslations.d.ts.map

package/dist/client/entities/translation/api/mutations/useCancelDocumentTranslation.d.ts

@@ -3,4 +3,3 @@ type Variables = {
 };
 export declare function useCancelDocumentTranslation(): import("@tanstack/react-query").UseMutationResult<void, Error, Variables, unknown>;
 export {};
-//# sourceMappingURL=useCancelDocumentTranslation.d.ts.map

package/dist/client/entities/translation/api/mutations/useQueueDocumentTranslation.d.ts

@@ -10,4 +10,3 @@ type Variables = {
 };
 export declare function useQueueDocumentTranslation(): import("@tanstack/react-query").UseMutationResult<void, Error, Variables, unknown>;
 export {};
-//# sourceMappingURL=useQueueDocumentTranslation.d.ts.map

package/dist/client/entities/translation/api/mutations/useQueueDocumentTranslations.d.ts

@@ -6,4 +6,3 @@ type Variables = {
 };
 export declare function useQueueDocumentTranslations(): import("@tanstack/react-query").UseMutationResult<void, Error, Variables, unknown>;
 export {};
-//# sourceMappingURL=useQueueDocumentTranslations.d.ts.map

package/dist/client/entities/translation/api/mutations/useRunDocumentTranslation.d.ts

@@ -3,4 +3,3 @@ type Variables = {
 };
 export declare function useRunDocumentTranslation(): import("@tanstack/react-query").UseMutationResult<void, Error, Variables, unknown>;
 export {};
-//# sourceMappingURL=useRunDocumentTranslation.d.ts.map

package/dist/client/entities/translation/api/queries/useCollectionTranslationStatus.d.ts

@@ -12,11 +12,9 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     error: Error;
     isError: true;
     isPending: false;
-    isLoading: false;
     isLoadingError: false;
     isRefetchError: true;
     isSuccess: false;
-    isPlaceholderData: false;
     status: "error";
     dataUpdatedAt: number;
     errorUpdatedAt: number;
@@ -26,25 +24,23 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     isFetched: boolean;
     isFetchedAfterMount: boolean;
     isFetching: boolean;
+    isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
+    isPlaceholderData: boolean;
     isRefetching: boolean;
     isStale: boolean;
-    isEnabled: boolean;
     refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
 } | {
     invalidate: () => void;
     data: GroupedCollectionTranslationStatus;
     error: null;
     isError: false;
     isPending: false;
-    isLoading: false;
     isLoadingError: false;
     isRefetchError: false;
     isSuccess: true;
-    isPlaceholderData: false;
     status: "success";
     dataUpdatedAt: number;
     errorUpdatedAt: number;
@@ -54,25 +50,23 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     isFetched: boolean;
     isFetchedAfterMount: boolean;
     isFetching: boolean;
+    isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
+    isPlaceholderData: boolean;
     isRefetching: boolean;
     isStale: boolean;
-    isEnabled: boolean;
     refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
 } | {
     invalidate: () => void;
     data: undefined;
     error: Error;
     isError: true;
     isPending: false;
-    isLoading: false;
     isLoadingError: true;
     isRefetchError: false;
     isSuccess: false;
-    isPlaceholderData: false;
     status: "error";
     dataUpdatedAt: number;
     errorUpdatedAt: number;
@@ -82,42 +76,14 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     isFetched: boolean;
     isFetchedAfterMount: boolean;
     isFetching: boolean;
+    isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
+    isPlaceholderData: boolean;
     isRefetching: boolean;
     isStale: boolean;
-    isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
-} | {
-    invalidate: () => void;
-    data: undefined;
-    error: null;
-    isError: false;
-    isPending: true;
-    isLoading: true;
-    isLoadingError: false;
-    isRefetchError: false;
-    isSuccess: false;
-    isPlaceholderData: false;
-    status: "pending";
-    dataUpdatedAt: number;
-    errorUpdatedAt: number;
-    failureCount: number;
-    failureReason: Error | null;
-    errorUpdateCount: number;
-    isFetched: boolean;
-    isFetchedAfterMount: boolean;
-    isFetching: boolean;
-    isInitialLoading: boolean;
-    isPaused: boolean;
-    isRefetching: boolean;
-    isStale: boolean;
-    isEnabled: boolean;
     refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
 } | {
     invalidate: () => void;
     data: undefined;
@@ -127,7 +93,6 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     isLoadingError: false;
     isRefetchError: false;
     isSuccess: false;
-    isPlaceholderData: false;
     status: "pending";
     dataUpdatedAt: number;
     errorUpdatedAt: number;
@@ -140,40 +105,10 @@ export declare function useCollectionTranslationStatus({ collection }: Props, op
     isLoading: boolean;
     isInitialLoading: boolean;
     isPaused: boolean;
+    isPlaceholderData: boolean;
     isRefetching: boolean;
     isStale: boolean;
-    isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
-} | {
-    invalidate: () => void;
-    data: GroupedCollectionTranslationStatus;
-    isError: false;
-    error: null;
-    isPending: false;
-    isLoading: false;
-    isLoadingError: false;
-    isRefetchError: false;
-    isSuccess: true;
-    isPlaceholderData: true;
-    status: "success";
-    dataUpdatedAt: number;
-    errorUpdatedAt: number;
-    failureCount: number;
-    failureReason: Error | null;
-    errorUpdateCount: number;
-    isFetched: boolean;
-    isFetchedAfterMount: boolean;
-    isFetching: boolean;
-    isInitialLoading: boolean;
-    isPaused: boolean;
-    isRefetching: boolean;
-    isStale: boolean;
-    isEnabled: boolean;
     refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<GroupedCollectionTranslationStatus, Error>>;
     fetchStatus: import("@tanstack/react-query").FetchStatus;
-    promise: Promise<GroupedCollectionTranslationStatus>;
 };
 export {};
-//# sourceMappingURL=useCollectionTranslationStatus.d.ts.map