@jhb.software/payload-alt-text-plugin 0.10.0 → 0.12.0

package/dist/resolvers/openAI.js

@@ -1,34 +1,18 @@
-import OpenAI from 'openai';
-import { makeParseableResponseFormat } from 'openai/lib/parser.mjs';
-import { z } from 'zod';
+import { createVisionResolver, VisionProviderError } from './createVisionResolver.js';
 /** @see https://platform.openai.com/docs/guides/images-vision */ const OPENAI_SUPPORTED_MIME_TYPES = [
     'image/jpeg',
     'image/png',
     'image/gif',
     'image/webp'
 ];
-/**
- * Creates a chat completion `JSONSchema` response format object from
- * the given Zod schema.
- *
- * This is a temporary drop in replacement for the zodResponseFormat from openai/helpers/zod.ts
- * because of issue https://github.com/openai/openai-node/issues/1576
- */ function zodResponseFormat(zodObject, name, props) {
-    return makeParseableResponseFormat({
-        type: 'json_schema',
-        json_schema: {
-            ...props,
-            name,
-            schema: z.toJSONSchema(zodObject, {
-                target: 'draft-7'
-            }),
-            strict: true
-        }
-    }, (content)=>zodObject.parse(JSON.parse(content)));
-}
 /**
  * Creates an OpenAI-based resolver for alt text generation.
  *
+ * The thumbnail URL is handed to OpenAI, which fetches it itself — so the URL
+ * has to be reachable from the public internet. When it is not, reach for a
+ * resolver that inlines the bytes instead (`mistralResolver`,
+ * `anthropicResolver`).
+ *
  * @example
  * ```typescript
  * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'
@@ -46,39 +30,15 @@ import { z } from 'zod';
  *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',
  * })
  * ```
- */ export const openAIResolver = (config)=>{
-    const { apiKey, baseUrl, model = 'gpt-4.1-nano' } = config;
-    // Build the client lazily (once, on first use): the `resolver` argument is
-    // evaluated even when the plugin is disabled, so eager construction would
-    // throw on a keyless `enabled: !!process.env.OPENAI_API_KEY` setup.
-    let openai;
-    const getClient = ()=>openai ??= new OpenAI({
-            apiKey,
-            baseURL: baseUrl
-        });
-    return {
-        key: 'openai',
-        resolve: async ({ filename, imageThumbnailUrl, locale })=>{
-            try {
-                const modelResponseSchema = z.object({
-                    altText: z.string().describe('A concise, descriptive alt text for the image'),
-                    keywords: z.array(z.string()).describe('Keywords that describe the content of the image')
-                });
-                const response = await getClient().chat.completions.parse({
-                    max_completion_tokens: 150,
+ */ export const openAIResolver = ({ apiKey, baseUrl = 'https://api.openai.com/v1', instructions, model = 'gpt-4.1-nano', supportedMimeTypes = OPENAI_SUPPORTED_MIME_TYPES, timeoutMs = 30_000 })=>createVisionResolver({
+        apiKey,
+        generate: async ({ filename, imageThumbnailUrl, instructions: resolvedInstructions, maxTokens, responseSchema, signal })=>{
+            const response = await fetch(`${baseUrl}/chat/completions`, {
+                body: JSON.stringify({
+                    max_completion_tokens: maxTokens,
                     messages: [
                         {
-                            content: `
-            You are an expert at analyzing images and creating descriptive image alt text.
-
-            Please analyze the given image and provide the following:
-            - A concise, descriptive alt text (1-2 sentences) as "altText". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.
-            - A list of keywords that describe the content (e.g., ["Camel", "Palm trees", "Desert"]) as "keywords"
-
-            If a context is provided, use it to enhance the alt text.
-
-            Format your response as a JSON object. You must respond in the ${locale} language.
-          `,
+                            content: resolvedInstructions,
                             role: 'system'
                         },
                         {
@@ -100,95 +60,54 @@ import { z } from 'zod';
                         }
                     ],
                     model,
-                    response_format: zodResponseFormat(modelResponseSchema, 'data')
+                    response_format: {
+                        type: 'json_schema',
+                        json_schema: {
+                            name: 'data',
+                            schema: responseSchema,
+                            strict: true
+                        }
+                    }
+                }),
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                method: 'POST',
+                signal
+            });
+            if (!response.ok) {
+                // Bounded: unbounded provider text would land in the log as-is.
+                const body = (await response.text().catch(()=>'')).slice(0, 500);
+                throw new VisionProviderError({
+                    body,
+                    label: 'OpenAI',
+                    status: response.status
                 });
-                const result = response.choices[0]?.message?.parsed;
-                if (!result) {
-                    return {
-                        error: 'No result from OpenAI',
-                        success: false
-                    };
-                }
-                return {
-                    result,
-                    success: true
-                };
-            } catch (error) {
-                console.error('Error generating alt text:', error);
-                return {
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                    success: false
-                };
             }
-        },
-        resolveBulk: async ({ filename, imageThumbnailUrl, locales })=>{
+            const completion = await response.json();
+            const choice = completion.choices?.[0];
+            // A budget exhausted mid-JSON otherwise reaches JSON.parse and reads as
+            // "Unexpected end of JSON input" in the admin panel, which tells an editor
+            // nothing about what to change.
+            if (choice?.finish_reason === 'length') {
+                throw new Error(`OpenAI ran out of tokens before finishing the alt text (max_completion_tokens: ${maxTokens})`);
+            }
+            const content = choice?.message?.content;
+            if (typeof content !== 'string') {
+                throw new Error('No result from OpenAI');
+            }
             try {
-                const modelResponseSchema = z.object(Object.fromEntries(locales.map((locale)=>[
-                        locale,
-                        z.object({
-                            altText: z.string().describe('A concise, descriptive alt text for the image'),
-                            keywords: z.array(z.string()).describe('Keywords that describe the content of the image')
-                        })
-                    ])));
-                const response = await getClient().chat.completions.parse({
-                    max_completion_tokens: 300,
-                    messages: [
-                        {
-                            content: `
-      You are an expert at analyzing images and creating descriptive image alt text.
-
-      Please analyze the given image and provide the following in ${locales.join(', ')}:
-      - A concise, localized descriptive alt text (1-2 sentences) as "altText". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.
-      - A localized list of keywords that describe the content (e.g., ["Camel", "Palm trees", "Desert"]) as "keywords"
-
-      If a context is provided, use it to enhance the alt text.
-
-      Format your response as a JSON object with ${locales.join(', ')} keys, each containing "altText" and "keywords".
-    `,
-                            role: 'system'
-                        },
-                        {
-                            content: [
-                                {
-                                    type: 'image_url',
-                                    image_url: {
-                                        url: imageThumbnailUrl
-                                    }
-                                },
-                                ...filename ? [
-                                    {
-                                        type: 'text',
-                                        text: filename
-                                    }
-                                ] : []
-                            ],
-                            role: 'user'
-                        }
-                    ],
-                    model,
-                    response_format: zodResponseFormat(modelResponseSchema, 'data')
-                });
-                const result = response.choices[0]?.message?.parsed;
-                if (!result) {
-                    return {
-                        error: 'No result from OpenAI',
-                        success: false
-                    };
-                }
-                return {
-                    results: result,
-                    success: true
-                };
-            } catch (error) {
-                console.error('Error generating bulk alt text:', error);
-                return {
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                    success: false
-                };
+                return JSON.parse(content);
+            } catch  {
+                throw new Error('OpenAI returned a response that was not valid JSON');
             }
         },
-        supportedMimeTypes: config.supportedMimeTypes ?? OPENAI_SUPPORTED_MIME_TYPES
-    };
-};
+        instructions,
+        key: 'openai',
+        label: 'OpenAI',
+        supportedMimeTypes,
+        timeoutMs
+    });
 
 //# sourceMappingURL=openAI.js.map

package/dist/resolvers/openAI.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/resolvers/openAI.ts"],"sourcesContent":["import type { AutoParseableResponseFormat } from 'openai/lib/parser.mjs'\nimport type { ChatCompletionContentPartText } from 'openai/resources/chat/completions.mjs'\nimport type { ResponseFormatJSONSchema } from 'openai/resources/shared.mjs'\n\nimport OpenAI from 'openai'\nimport { makeParseableResponseFormat } from 'openai/lib/parser.mjs'\nimport { z } from 'zod'\n\nimport type {\n  AltTextBulkResolverArgs,\n  AltTextBulkResolverResponse,\n  AltTextResolver,\n  AltTextResolverArgs,\n  AltTextResolverResponse,\n} from './types.js'\n\nexport type OpenAIResolverConfig = {\n  /** OpenAI API key for authentication */\n  apiKey: string\n  /**\n   * Base URL for the OpenAI-compatible API.\n   * Use this to point at alternative providers (e.g. Azure, Nebius, local inference).\n   * @default undefined — the OpenAI SDK defaults to 'https://api.openai.com/v1'\n   */\n  baseUrl?: string\n  /**\n   * The OpenAI LLM model to use for alt text generation.\n   * @default 'gpt-4.1-nano'\n   */\n  model?: string\n  /**\n   * The MIME types the provider accepts for the image URL.\n   *\n   * Defaults to the formats documented for OpenAI's vision models. Override it\n   * when pointing `baseUrl` at another provider whose accepted formats differ —\n   * the person choosing the provider is the one who knows.\n   *\n   * @default ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n   */\n  supportedMimeTypes?: string[]\n}\n\n/** @see https://platform.openai.com/docs/guides/images-vision */\nconst OPENAI_SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Creates a chat completion `JSONSchema` response format object from\n * the given Zod schema.\n *\n * This is a temporary drop in replacement for the zodResponseFormat from openai/helpers/zod.ts\n * because of issue https://github.com/openai/openai-node/issues/1576\n */\nfunction zodResponseFormat<ZodInput extends z.ZodType>(\n  zodObject: ZodInput,\n  name: string,\n  props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'name' | 'schema' | 'strict'>,\n): AutoParseableResponseFormat<z.infer<ZodInput>> {\n  return makeParseableResponseFormat(\n    {\n      type: 'json_schema',\n      json_schema: {\n        ...props,\n        name,\n        schema: z.toJSONSchema(zodObject, { target: 'draft-7' }),\n        strict: true,\n      },\n    },\n    (content) => zodObject.parse(JSON.parse(content)),\n  )\n}\n\n/**\n * Creates an OpenAI-based resolver for alt text generation.\n *\n * @example\n * ```typescript\n * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * // OpenAI\n * openAIResolver({\n *   apiKey: process.env.OPENAI_API_KEY,\n *   model: 'gpt-4.1-mini', // optional, defaults to 'gpt-4.1-nano'\n * })\n *\n * // OpenAI-compatible provider (e.g. Nebius)\n * openAIResolver({\n *   apiKey: process.env.NEBIUS_API_KEY,\n *   baseUrl: 'https://api.tokenfactory.us-central1.nebius.com/v1',\n *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',\n * })\n * ```\n */\nexport const openAIResolver = (config: OpenAIResolverConfig): AltTextResolver => {\n  const { apiKey, baseUrl, model = 'gpt-4.1-nano' } = config\n\n  // Build the client lazily (once, on first use): the `resolver` argument is\n  // evaluated even when the plugin is disabled, so eager construction would\n  // throw on a keyless `enabled: !!process.env.OPENAI_API_KEY` setup.\n  let openai: OpenAI | undefined\n  const getClient = (): OpenAI => (openai ??= new OpenAI({ apiKey, baseURL: baseUrl }))\n\n  return {\n    key: 'openai',\n    resolve: async ({\n      filename,\n      imageThumbnailUrl,\n      locale,\n    }: AltTextResolverArgs): Promise<AltTextResolverResponse> => {\n      try {\n        const modelResponseSchema = z.object({\n          altText: z.string().describe('A concise, descriptive alt text for the image'),\n          keywords: z.array(z.string()).describe('Keywords that describe the content of the image'),\n        })\n\n        const response = await getClient().chat.completions.parse({\n          max_completion_tokens: 150,\n          messages: [\n            {\n              content: `\n            You are an expert at analyzing images and creating descriptive image alt text.\n\n            Please analyze the given image and provide the following:\n            - A concise, descriptive alt text (1-2 sentences) as \"altText\". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.\n            - A list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"\n\n            If a context is provided, use it to enhance the alt text.\n\n            Format your response as a JSON object. You must respond in the ${locale} language.\n          `,\n              role: 'system',\n            },\n            {\n              content: [\n                {\n                  type: 'image_url',\n                  image_url: { url: imageThumbnailUrl },\n                },\n                ...(filename\n                  ? [\n                      {\n                        type: 'text',\n                        text: filename,\n                      } satisfies ChatCompletionContentPartText,\n                    ]\n                  : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: zodResponseFormat(modelResponseSchema, 'data'),\n        })\n\n        const result = response.choices[0]?.message?.parsed\n\n        if (!result) {\n          return { error: 'No result from OpenAI', success: false }\n        }\n\n        return {\n          result,\n          success: true,\n        }\n      } catch (error) {\n        console.error('Error generating alt text:', error)\n        return {\n          error: error instanceof Error ? error.message : 'Unknown error',\n          success: false,\n        }\n      }\n    },\n    resolveBulk: async ({\n      filename,\n      imageThumbnailUrl,\n      locales,\n    }: AltTextBulkResolverArgs): Promise<AltTextBulkResolverResponse> => {\n      try {\n        const modelResponseSchema = z.object(\n          Object.fromEntries(\n            locales.map((locale) => [\n              locale,\n              z.object({\n                altText: z.string().describe('A concise, descriptive alt text for the image'),\n                keywords: z\n                  .array(z.string())\n                  .describe('Keywords that describe the content of the image'),\n              }),\n            ]),\n          ),\n        )\n\n        const response = await getClient().chat.completions.parse({\n          max_completion_tokens: 300,\n          messages: [\n            {\n              content: `\n      You are an expert at analyzing images and creating descriptive image alt text.\n\n      Please analyze the given image and provide the following in ${locales.join(', ')}:\n      - A concise, localized descriptive alt text (1-2 sentences) as \"altText\". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.\n      - A localized list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"\n\n      If a context is provided, use it to enhance the alt text.\n\n      Format your response as a JSON object with ${locales.join(', ')} keys, each containing \"altText\" and \"keywords\".\n    `,\n              role: 'system',\n            },\n            {\n              content: [\n                {\n                  type: 'image_url',\n                  image_url: { url: imageThumbnailUrl },\n                },\n                ...(filename\n                  ? [\n                      {\n                        type: 'text',\n                        text: filename,\n                      } satisfies ChatCompletionContentPartText,\n                    ]\n                  : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: zodResponseFormat(modelResponseSchema, 'data'),\n        })\n\n        const result = response.choices[0]?.message?.parsed\n\n        if (!result) {\n          return { error: 'No result from OpenAI', success: false }\n        }\n\n        return {\n          results: result,\n          success: true,\n        }\n      } catch (error) {\n        console.error('Error generating bulk alt text:', error)\n        return {\n          error: error instanceof Error ? error.message : 'Unknown error',\n          success: false,\n        }\n      }\n    },\n    supportedMimeTypes: config.supportedMimeTypes ?? OPENAI_SUPPORTED_MIME_TYPES,\n  }\n}\n"],"names":["OpenAI","makeParseableResponseFormat","z","OPENAI_SUPPORTED_MIME_TYPES","zodResponseFormat","zodObject","name","props","type","json_schema","schema","toJSONSchema","target","strict","content","parse","JSON","openAIResolver","config","apiKey","baseUrl","model","openai","getClient","baseURL","key","resolve","filename","imageThumbnailUrl","locale","modelResponseSchema","object","altText","string","describe","keywords","array","response","chat","completions","max_completion_tokens","messages","role","image_url","url","text","response_format","result","choices","message","parsed","error","success","console","Error","resolveBulk","locales","Object","fromEntries","map","join","results","supportedMimeTypes"],"mappings":"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"}
+{"version":3,"sources":["../../src/resolvers/openAI.ts"],"sourcesContent":["import type { VisionInstructions } from './createVisionResolver.js'\nimport type { AltTextResolver } from './types.js'\n\nimport { createVisionResolver, VisionProviderError } from './createVisionResolver.js'\n\nexport type OpenAIResolverConfig = {\n  /** OpenAI API key for authentication */\n  apiKey: string\n  /**\n   * Base URL for the OpenAI-compatible API, including the version segment.\n   * Use this to point at alternative providers (e.g. Azure, Nebius, local inference).\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string\n  /**\n   * Builds the instructions from the default ones, e.g. to append a house style\n   * rule. Sent as the system message, separately from the image.\n   *\n   * @default ({ defaultInstructions }) => defaultInstructions\n   */\n  instructions?: VisionInstructions\n  /**\n   * The OpenAI LLM model to use for alt text generation.\n   * @default 'gpt-4.1-nano'\n   */\n  model?: string\n  /**\n   * The MIME types the provider accepts for the image URL.\n   *\n   * Defaults to the formats documented for OpenAI's vision models. Override it\n   * when pointing `baseUrl` at another provider whose accepted formats differ —\n   * the person choosing the provider is the one who knows.\n   *\n   * @default ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n   */\n  supportedMimeTypes?: string[]\n  /**\n   * Abort after this many milliseconds, covering the completion call and the\n   * retries the factory makes within it.\n   * @default 30000\n   */\n  timeoutMs?: number\n}\n\n/** @see https://platform.openai.com/docs/guides/images-vision */\nconst OPENAI_SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Creates an OpenAI-based resolver for alt text generation.\n *\n * The thumbnail URL is handed to OpenAI, which fetches it itself — so the URL\n * has to be reachable from the public internet. When it is not, reach for a\n * resolver that inlines the bytes instead (`mistralResolver`,\n * `anthropicResolver`).\n *\n * @example\n * ```typescript\n * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * // OpenAI\n * openAIResolver({\n *   apiKey: process.env.OPENAI_API_KEY,\n *   model: 'gpt-4.1-mini', // optional, defaults to 'gpt-4.1-nano'\n * })\n *\n * // OpenAI-compatible provider (e.g. Nebius)\n * openAIResolver({\n *   apiKey: process.env.NEBIUS_API_KEY,\n *   baseUrl: 'https://api.tokenfactory.us-central1.nebius.com/v1',\n *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',\n * })\n * ```\n */\nexport const openAIResolver = ({\n  apiKey,\n  baseUrl = 'https://api.openai.com/v1',\n  instructions,\n  model = 'gpt-4.1-nano',\n  supportedMimeTypes = OPENAI_SUPPORTED_MIME_TYPES,\n  timeoutMs = 30_000,\n}: OpenAIResolverConfig): AltTextResolver =>\n  createVisionResolver({\n    apiKey,\n    generate: async ({\n      filename,\n      imageThumbnailUrl,\n      instructions: resolvedInstructions,\n      maxTokens,\n      responseSchema,\n      signal,\n    }) => {\n      const response = await fetch(`${baseUrl}/chat/completions`, {\n        body: JSON.stringify({\n          max_completion_tokens: maxTokens,\n          messages: [\n            { content: resolvedInstructions, role: 'system' },\n            {\n              content: [\n                { type: 'image_url', image_url: { url: imageThumbnailUrl } },\n                ...(filename ? [{ type: 'text', text: filename }] : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: {\n            type: 'json_schema',\n            json_schema: { name: 'data', schema: responseSchema, strict: true },\n          },\n        }),\n        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },\n        method: 'POST',\n        signal,\n      })\n\n      if (!response.ok) {\n        // Bounded: unbounded provider text would land in the log as-is.\n        const body = (await response.text().catch(() => '')).slice(0, 500)\n\n        throw new VisionProviderError({ body, label: 'OpenAI', status: response.status })\n      }\n\n      const completion = (await response.json()) as {\n        choices?: { finish_reason?: string; message?: { content?: unknown } }[]\n      }\n      const choice = completion.choices?.[0]\n\n      // A budget exhausted mid-JSON otherwise reaches JSON.parse and reads as\n      // \"Unexpected end of JSON input\" in the admin panel, which tells an editor\n      // nothing about what to change.\n      if (choice?.finish_reason === 'length') {\n        throw new Error(\n          `OpenAI ran out of tokens before finishing the alt text (max_completion_tokens: ${maxTokens})`,\n        )\n      }\n\n      const content = choice?.message?.content\n\n      if (typeof content !== 'string') {\n        throw new Error('No result from OpenAI')\n      }\n\n      try {\n        return JSON.parse(content)\n      } catch {\n        throw new Error('OpenAI returned a response that was not valid JSON')\n      }\n    },\n    instructions,\n    key: 'openai',\n    label: 'OpenAI',\n    supportedMimeTypes,\n    timeoutMs,\n  })\n"],"names":["createVisionResolver","VisionProviderError","OPENAI_SUPPORTED_MIME_TYPES","openAIResolver","apiKey","baseUrl","instructions","model","supportedMimeTypes","timeoutMs","generate","filename","imageThumbnailUrl","resolvedInstructions","maxTokens","responseSchema","signal","response","fetch","body","JSON","stringify","max_completion_tokens","messages","content","role","type","image_url","url","text","response_format","json_schema","name","schema","strict","headers","Authorization","method","ok","catch","slice","label","status","completion","json","choice","choices","finish_reason","Error","message","parse","key"],"mappings":"AAGA,SAASA,oBAAoB,EAAEC,mBAAmB,QAAQ,4BAA2B;AAyCrF,+DAA+D,GAC/D,MAAMC,8BAA8B;IAAC;IAAc;IAAa;IAAa;CAAa;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,MAAMC,iBAAiB,CAAC,EAC7BC,MAAM,EACNC,UAAU,2BAA2B,EACrCC,YAAY,EACZC,QAAQ,cAAc,EACtBC,qBAAqBN,2BAA2B,EAChDO,YAAY,MAAM,EACG,GACrBT,qBAAqB;QACnBI;QACAM,UAAU,OAAO,EACfC,QAAQ,EACRC,iBAAiB,EACjBN,cAAcO,oBAAoB,EAClCC,SAAS,EACTC,cAAc,EACdC,MAAM,EACP;YACC,MAAMC,WAAW,MAAMC,MAAM,GAAGb,QAAQ,iBAAiB,CAAC,EAAE;gBAC1Dc,MAAMC,KAAKC,SAAS,CAAC;oBACnBC,uBAAuBR;oBACvBS,UAAU;wBACR;4BAAEC,SAASX;4BAAsBY,MAAM;wBAAS;wBAChD;4BACED,SAAS;gCACP;oCAAEE,MAAM;oCAAaC,WAAW;wCAAEC,KAAKhB;oCAAkB;gCAAE;mCACvDD,WAAW;oCAAC;wCAAEe,MAAM;wCAAQG,MAAMlB;oCAAS;iCAAE,GAAG,EAAE;6BACvD;4BACDc,MAAM;wBACR;qBACD;oBACDlB;oBACAuB,iBAAiB;wBACfJ,MAAM;wBACNK,aAAa;4BAAEC,MAAM;4BAAQC,QAAQlB;4BAAgBmB,QAAQ;wBAAK;oBACpE;gBACF;gBACAC,SAAS;oBAAEC,eAAe,CAAC,OAAO,EAAEhC,QAAQ;oBAAE,gBAAgB;gBAAmB;gBACjFiC,QAAQ;gBACRrB;YACF;YAEA,IAAI,CAACC,SAASqB,EAAE,EAAE;gBAChB,gEAAgE;gBAChE,MAAMnB,OAAO,AAAC,CAAA,MAAMF,SAASY,IAAI,GAAGU,KAAK,CAAC,IAAM,GAAE,EAAGC,KAAK,CAAC,GAAG;gBAE9D,MAAM,IAAIvC,oBAAoB;oBAAEkB;oBAAMsB,OAAO;oBAAUC,QAAQzB,SAASyB,MAAM;gBAAC;YACjF;YAEA,MAAMC,aAAc,MAAM1B,SAAS2B,IAAI;YAGvC,MAAMC,SAASF,WAAWG,OAAO,EAAE,CAAC,EAAE;YAEtC,wEAAwE;YACxE,2EAA2E;YAC3E,gCAAgC;YAChC,IAAID,QAAQE,kBAAkB,UAAU;gBACtC,MAAM,IAAIC,MACR,CAAC,+EAA+E,EAAElC,UAAU,CAAC,CAAC;YAElG;YAEA,MAAMU,UAAUqB,QAAQI,SAASzB;YAEjC,IAAI,OAAOA,YAAY,UAAU;gBAC/B,MAAM,IAAIwB,MAAM;YAClB;YAEA,IAAI;gBACF,OAAO5B,KAAK8B,KAAK,CAAC1B;YACpB,EAAE,OAAM;gBACN,MAAM,IAAIwB,MAAM;YAClB;QACF;QACA1C;QACA6C,KAAK;QACLV,OAAO;QACPjC;QACAC;IACF,GAAE"}

package/dist/translations/de.js

@@ -14,9 +14,15 @@ export const de = {
         cannotGenerateMissingFields: 'Alternativtext kann nicht generiert werden. Erforderliche Felder fehlen.',
         errorGeneratingAltText: 'Fehler beim Generieren des Alternativtextes. Bitte versuchen Sie es erneut.',
         failedToGenerate: 'Generierung des Alternativtextes fehlgeschlagen. Bitte versuchen Sie es erneut.',
-        failedToGenerateForXImages: 'Generierung des Alternativtextes für {{count}} Bilder fehlgeschlagen.',
+        failedToGenerateForXImages_one: 'Generierung des Alternativtextes für {{count}} Bild fehlgeschlagen.',
+        failedToGenerateForXImages_other: 'Generierung des Alternativtextes für {{count}} Bilder fehlgeschlagen.',
         noAltTextGenerated: 'Kein Alternativtext generiert. Bitte versuchen Sie es erneut.',
-        xOfYImagesUpdated: '{{updated}} von {{total}} Bildern aktualisiert.',
+        skippedNoAltTextNeeded_one: '{{count}} Datei übersprungen, die keinen Alternativtext benötigt.',
+        skippedNoAltTextNeeded_other: '{{count}} Dateien übersprungen, die keinen Alternativtext benötigen.',
+        skippedUnsupportedFormat_one: 'Für {{count}} Datei kann kein Alternativtext generiert werden. Bitte manuell ergänzen.',
+        skippedUnsupportedFormat_other: 'Für {{count}} Dateien kann kein Alternativtext generiert werden. Bitte manuell ergänzen.',
+        xOfYImagesUpdated_one: '{{updated}} von {{total}} Bild aktualisiert.',
+        xOfYImagesUpdated_other: '{{updated}} von {{total}} Bildern aktualisiert.',
         // Help text
         altTextDescription: 'Alternativtext für das Bild. Dieser wird für Screenreader und SEO verwendet. Er sollte die folgenden Anforderungen erfüllen:',
         altTextRequirement1: 'Beschreibt in 1-2 Sätzen, was auf dem Bild zu sehen ist.',
@@ -32,11 +38,13 @@ export const de = {
         altTextHealthWidget: 'Alternativtexte',
         collectionCheckFailed: 'Status nicht verfügbar',
         healthCheckPartialWarning: 'Einige Sammlungen konnten gerade nicht geprüft werden.',
-        localeCount: '{{count}} Sprachen',
+        localeCount_one: '{{count}} Sprache',
+        localeCount_other: '{{count}} Sprachen',
         noImagesFound: 'In den konfigurierten Sammlungen wurden noch keine Bilder gefunden.',
         statusHealthy: 'Alle vorhanden',
         statusUnhealthy: '{{count}} fehlend',
-        totalImageCount: '{{count}} Bilder'
+        totalImageCount_one: '{{count}} Bild',
+        totalImageCount_other: '{{count}} Bilder'
     }
 };
 

package/dist/translations/de.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/translations/de.ts"],"sourcesContent":["import type { GenericTranslationsObject } from './index.js'\n\nexport const de: GenericTranslationsObject = {\n  $schema: './translation-schema.json',\n  '@jhb.software/payload-alt-text-plugin': {\n    // Field labels\n    alternateText: 'Alternativtext',\n    keywords: 'Schlüsselwörter',\n    keywordsDescription:\n      'Schlüsselwörter, die das Bild beschreiben. Wird bei der Suche nach dem Bild verwendet.',\n\n    // Button labels\n    generateAltText: 'Alternativtext generieren',\n    generateAltTextFor_one: 'Alternativtext für {{count}} Bild generieren',\n    generateAltTextFor_other: 'Alternativtext für {{count}} Bilder generieren',\n\n    // Toast messages\n    altTextGeneratedSuccess:\n      'Alternativtext erfolgreich generiert. Bitte überprüfen und speichern Sie das Dokument.',\n    cannotGenerateMissingFields:\n      'Alternativtext kann nicht generiert werden. Erforderliche Felder fehlen.',\n    errorGeneratingAltText:\n      'Fehler beim Generieren des Alternativtextes. Bitte versuchen Sie es erneut.',\n    failedToGenerate:\n      'Generierung des Alternativtextes fehlgeschlagen. Bitte versuchen Sie es erneut.',\n    failedToGenerateForXImages:\n      'Generierung des Alternativtextes für {{count}} Bilder fehlgeschlagen.',\n    noAltTextGenerated: 'Kein Alternativtext generiert. Bitte versuchen Sie es erneut.',\n    xOfYImagesUpdated: '{{updated}} von {{total}} Bildern aktualisiert.',\n\n    // Help text\n    altTextDescription:\n      'Alternativtext für das Bild. Dieser wird für Screenreader und SEO verwendet. Er sollte die folgenden Anforderungen erfüllen:',\n    altTextRequirement1: 'Beschreibt in 1-2 Sätzen, was auf dem Bild zu sehen ist.',\n    altTextRequirement2:\n      'Sollte möglichst die gleichen Informationen oder den gleichen Zweck wie das Bild vermitteln.',\n    altTextRequirement3:\n      'Phrasen wie \"Bild von\" oder \"Foto von\" sind überflüssig, da Screenreader bereits anzeigen, dass es sich um ein Bild handelt.',\n\n    // Tooltips\n    pleaseSaveDocumentFirst: 'Bitte speichern Sie zuerst das Dokument',\n    unsupportedMimeType:\n      'Alternativtext-Generierung wird für {{mimeType}}-Dateien nicht unterstützt',\n\n    // Validation messages\n    theAlternateTextIsRequired: 'Der Alternativtext ist erforderlich.',\n\n    // Dashboard widget\n    altTextHealthDescription: 'Alternativtext Abdeckung in allen Upload-Sammlungen.',\n    altTextHealthWidget: 'Alternativtexte',\n    collectionCheckFailed: 'Status nicht verfügbar',\n    healthCheckPartialWarning: 'Einige Sammlungen konnten gerade nicht geprüft werden.',\n    localeCount: '{{count}} Sprachen',\n    noImagesFound: 'In den konfigurierten Sammlungen wurden noch keine Bilder gefunden.',\n    statusHealthy: 'Alle vorhanden',\n    statusUnhealthy: '{{count}} fehlend',\n    totalImageCount: '{{count}} Bilder',\n  },\n}\n"],"names":["de","$schema","alternateText","keywords","keywordsDescription","generateAltText","generateAltTextFor_one","generateAltTextFor_other","altTextGeneratedSuccess","cannotGenerateMissingFields","errorGeneratingAltText","failedToGenerate","failedToGenerateForXImages","noAltTextGenerated","xOfYImagesUpdated","altTextDescription","altTextRequirement1","altTextRequirement2","altTextRequirement3","pleaseSaveDocumentFirst","unsupportedMimeType","theAlternateTextIsRequired","altTextHealthDescription","altTextHealthWidget","collectionCheckFailed","healthCheckPartialWarning","localeCount","noImagesFound","statusHealthy","statusUnhealthy","totalImageCount"],"mappings":"AAEA,OAAO,MAAMA,KAAgC;IAC3CC,SAAS;IACT,yCAAyC;QACvC,eAAe;QACfC,eAAe;QACfC,UAAU;QACVC,qBACE;QAEF,gBAAgB;QAChBC,iBAAiB;QACjBC,wBAAwB;QACxBC,0BAA0B;QAE1B,iBAAiB;QACjBC,yBACE;QACFC,6BACE;QACFC,wBACE;QACFC,kBACE;QACFC,4BACE;QACFC,oBAAoB;QACpBC,mBAAmB;QAEnB,YAAY;QACZC,oBACE;QACFC,qBAAqB;QACrBC,qBACE;QACFC,qBACE;QAEF,WAAW;QACXC,yBAAyB;QACzBC,qBACE;QAEF,sBAAsB;QACtBC,4BAA4B;QAE5B,mBAAmB;QACnBC,0BAA0B;QAC1BC,qBAAqB;QACrBC,uBAAuB;QACvBC,2BAA2B;QAC3BC,aAAa;QACbC,eAAe;QACfC,eAAe;QACfC,iBAAiB;QACjBC,iBAAiB;IACnB;AACF,EAAC"}
+{"version":3,"sources":["../../src/translations/de.ts"],"sourcesContent":["import type { GenericTranslationsObject } from './index.js'\n\nexport const de: GenericTranslationsObject = {\n  $schema: './translation-schema.json',\n  '@jhb.software/payload-alt-text-plugin': {\n    // Field labels\n    alternateText: 'Alternativtext',\n    keywords: 'Schlüsselwörter',\n    keywordsDescription:\n      'Schlüsselwörter, die das Bild beschreiben. Wird bei der Suche nach dem Bild verwendet.',\n\n    // Button labels\n    generateAltText: 'Alternativtext generieren',\n    generateAltTextFor_one: 'Alternativtext für {{count}} Bild generieren',\n    generateAltTextFor_other: 'Alternativtext für {{count}} Bilder generieren',\n\n    // Toast messages\n    altTextGeneratedSuccess:\n      'Alternativtext erfolgreich generiert. Bitte überprüfen und speichern Sie das Dokument.',\n    cannotGenerateMissingFields:\n      'Alternativtext kann nicht generiert werden. Erforderliche Felder fehlen.',\n    errorGeneratingAltText:\n      'Fehler beim Generieren des Alternativtextes. Bitte versuchen Sie es erneut.',\n    failedToGenerate:\n      'Generierung des Alternativtextes fehlgeschlagen. Bitte versuchen Sie es erneut.',\n    failedToGenerateForXImages_one:\n      'Generierung des Alternativtextes für {{count}} Bild fehlgeschlagen.',\n    failedToGenerateForXImages_other:\n      'Generierung des Alternativtextes für {{count}} Bilder fehlgeschlagen.',\n    noAltTextGenerated: 'Kein Alternativtext generiert. Bitte versuchen Sie es erneut.',\n    skippedNoAltTextNeeded_one: '{{count}} Datei übersprungen, die keinen Alternativtext benötigt.',\n    skippedNoAltTextNeeded_other:\n      '{{count}} Dateien übersprungen, die keinen Alternativtext benötigen.',\n    skippedUnsupportedFormat_one:\n      'Für {{count}} Datei kann kein Alternativtext generiert werden. Bitte manuell ergänzen.',\n    skippedUnsupportedFormat_other:\n      'Für {{count}} Dateien kann kein Alternativtext generiert werden. Bitte manuell ergänzen.',\n    xOfYImagesUpdated_one: '{{updated}} von {{total}} Bild aktualisiert.',\n    xOfYImagesUpdated_other: '{{updated}} von {{total}} Bildern aktualisiert.',\n\n    // Help text\n    altTextDescription:\n      'Alternativtext für das Bild. Dieser wird für Screenreader und SEO verwendet. Er sollte die folgenden Anforderungen erfüllen:',\n    altTextRequirement1: 'Beschreibt in 1-2 Sätzen, was auf dem Bild zu sehen ist.',\n    altTextRequirement2:\n      'Sollte möglichst die gleichen Informationen oder den gleichen Zweck wie das Bild vermitteln.',\n    altTextRequirement3:\n      'Phrasen wie \"Bild von\" oder \"Foto von\" sind überflüssig, da Screenreader bereits anzeigen, dass es sich um ein Bild handelt.',\n\n    // Tooltips\n    pleaseSaveDocumentFirst: 'Bitte speichern Sie zuerst das Dokument',\n    unsupportedMimeType:\n      'Alternativtext-Generierung wird für {{mimeType}}-Dateien nicht unterstützt',\n\n    // Validation messages\n    theAlternateTextIsRequired: 'Der Alternativtext ist erforderlich.',\n\n    // Dashboard widget\n    altTextHealthDescription: 'Alternativtext Abdeckung in allen Upload-Sammlungen.',\n    altTextHealthWidget: 'Alternativtexte',\n    collectionCheckFailed: 'Status nicht verfügbar',\n    healthCheckPartialWarning: 'Einige Sammlungen konnten gerade nicht geprüft werden.',\n    localeCount_one: '{{count}} Sprache',\n    localeCount_other: '{{count}} Sprachen',\n    noImagesFound: 'In den konfigurierten Sammlungen wurden noch keine Bilder gefunden.',\n    statusHealthy: 'Alle vorhanden',\n    statusUnhealthy: '{{count}} fehlend',\n    totalImageCount_one: '{{count}} Bild',\n    totalImageCount_other: '{{count}} Bilder',\n  },\n}\n"],"names":["de","$schema","alternateText","keywords","keywordsDescription","generateAltText","generateAltTextFor_one","generateAltTextFor_other","altTextGeneratedSuccess","cannotGenerateMissingFields","errorGeneratingAltText","failedToGenerate","failedToGenerateForXImages_one","failedToGenerateForXImages_other","noAltTextGenerated","skippedNoAltTextNeeded_one","skippedNoAltTextNeeded_other","skippedUnsupportedFormat_one","skippedUnsupportedFormat_other","xOfYImagesUpdated_one","xOfYImagesUpdated_other","altTextDescription","altTextRequirement1","altTextRequirement2","altTextRequirement3","pleaseSaveDocumentFirst","unsupportedMimeType","theAlternateTextIsRequired","altTextHealthDescription","altTextHealthWidget","collectionCheckFailed","healthCheckPartialWarning","localeCount_one","localeCount_other","noImagesFound","statusHealthy","statusUnhealthy","totalImageCount_one","totalImageCount_other"],"mappings":"AAEA,OAAO,MAAMA,KAAgC;IAC3CC,SAAS;IACT,yCAAyC;QACvC,eAAe;QACfC,eAAe;QACfC,UAAU;QACVC,qBACE;QAEF,gBAAgB;QAChBC,iBAAiB;QACjBC,wBAAwB;QACxBC,0BAA0B;QAE1B,iBAAiB;QACjBC,yBACE;QACFC,6BACE;QACFC,wBACE;QACFC,kBACE;QACFC,gCACE;QACFC,kCACE;QACFC,oBAAoB;QACpBC,4BAA4B;QAC5BC,8BACE;QACFC,8BACE;QACFC,gCACE;QACFC,uBAAuB;QACvBC,yBAAyB;QAEzB,YAAY;QACZC,oBACE;QACFC,qBAAqB;QACrBC,qBACE;QACFC,qBACE;QAEF,WAAW;QACXC,yBAAyB;QACzBC,qBACE;QAEF,sBAAsB;QACtBC,4BAA4B;QAE5B,mBAAmB;QACnBC,0BAA0B;QAC1BC,qBAAqB;QACrBC,uBAAuB;QACvBC,2BAA2B;QAC3BC,iBAAiB;QACjBC,mBAAmB;QACnBC,eAAe;QACfC,eAAe;QACfC,iBAAiB;QACjBC,qBAAqB;QACrBC,uBAAuB;IACzB;AACF,EAAC"}

package/dist/translations/en.js

@@ -14,9 +14,15 @@ export const en = {
         cannotGenerateMissingFields: 'Cannot generate alt text. Missing required fields.',
         errorGeneratingAltText: 'Error generating alt text. Please try again.',
         failedToGenerate: 'Failed to generate alt text. Please try again.',
-        failedToGenerateForXImages: 'Failed to generate alt text for {{count}} images.',
+        failedToGenerateForXImages_one: 'Failed to generate alt text for {{count}} image.',
+        failedToGenerateForXImages_other: 'Failed to generate alt text for {{count}} images.',
         noAltTextGenerated: 'No alt text generated. Please try again.',
-        xOfYImagesUpdated: '{{updated}} of {{total}} images updated.',
+        skippedNoAltTextNeeded_one: 'Skipped {{count}} file that does not need alt text.',
+        skippedNoAltTextNeeded_other: 'Skipped {{count}} files that do not need alt text.',
+        skippedUnsupportedFormat_one: 'Alt text cannot be generated for {{count}} file. Please write it by hand.',
+        skippedUnsupportedFormat_other: 'Alt text cannot be generated for {{count}} files. Please write it by hand.',
+        xOfYImagesUpdated_one: '{{updated}} of {{total}} image updated.',
+        xOfYImagesUpdated_other: '{{updated}} of {{total}} images updated.',
         // Help text
         altTextDescription: 'Alternate text for the image. This will be used for screen readers and SEO. It should meet the following requirements:',
         altTextRequirement1: 'Describes in 1-2 sentences, what is visible in the image.',
@@ -32,11 +38,13 @@ export const en = {
         altTextHealthWidget: 'Alt Texts',
         collectionCheckFailed: 'Status unavailable',
         healthCheckPartialWarning: 'Some collections could not be checked right now.',
-        localeCount: '{{count}} locales',
+        localeCount_one: '{{count}} locale',
+        localeCount_other: '{{count}} locales',
         noImagesFound: 'No images found in the configured collections yet.',
         statusHealthy: 'All set',
         statusUnhealthy: '{{count}} missing',
-        totalImageCount: '{{count}} images'
+        totalImageCount_one: '{{count}} image',
+        totalImageCount_other: '{{count}} images'
     }
 };
 

package/dist/translations/en.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/translations/en.ts"],"sourcesContent":["import type { GenericTranslationsObject } from './index.js'\n\nexport const en: GenericTranslationsObject = {\n  $schema: './translation-schema.json',\n  '@jhb.software/payload-alt-text-plugin': {\n    // Field labels\n    alternateText: 'Alternate text',\n    keywords: 'Keywords',\n    keywordsDescription: 'Keywords which describe the image. Used when searching for the image.',\n\n    // Button labels\n    generateAltText: 'Generate alt text',\n    generateAltTextFor_one: 'Generate alt text for {{count}} image',\n    generateAltTextFor_other: 'Generate alt text for {{count}} images',\n\n    // Toast messages\n    altTextGeneratedSuccess:\n      'Alt text generated successfully. Please review and save the document.',\n    cannotGenerateMissingFields: 'Cannot generate alt text. Missing required fields.',\n    errorGeneratingAltText: 'Error generating alt text. Please try again.',\n    failedToGenerate: 'Failed to generate alt text. Please try again.',\n    failedToGenerateForXImages: 'Failed to generate alt text for {{count}} images.',\n    noAltTextGenerated: 'No alt text generated. Please try again.',\n    xOfYImagesUpdated: '{{updated}} of {{total}} images updated.',\n\n    // Help text\n    altTextDescription:\n      'Alternate text for the image. This will be used for screen readers and SEO. It should meet the following requirements:',\n    altTextRequirement1: 'Describes in 1-2 sentences, what is visible in the image.',\n    altTextRequirement2:\n      'Should convey the same information or purpose as the image, whenever possible.',\n    altTextRequirement3:\n      'Phrases like \"image of\" or \"picture of\" are unnecessary, since screen readers already announce that it\\'s an image.',\n\n    // Tooltips\n    pleaseSaveDocumentFirst: 'Please save the document first',\n    unsupportedMimeType: 'Alt text generation is not supported for {{mimeType}} files',\n\n    // Validation messages\n    theAlternateTextIsRequired: 'An alternate text is required.',\n\n    // Dashboard widget\n    altTextHealthDescription: 'Alt text coverage across upload collections.',\n    altTextHealthWidget: 'Alt Texts',\n    collectionCheckFailed: 'Status unavailable',\n    healthCheckPartialWarning: 'Some collections could not be checked right now.',\n    localeCount: '{{count}} locales',\n    noImagesFound: 'No images found in the configured collections yet.',\n    statusHealthy: 'All set',\n    statusUnhealthy: '{{count}} missing',\n    totalImageCount: '{{count}} images',\n  },\n}\n"],"names":["en","$schema","alternateText","keywords","keywordsDescription","generateAltText","generateAltTextFor_one","generateAltTextFor_other","altTextGeneratedSuccess","cannotGenerateMissingFields","errorGeneratingAltText","failedToGenerate","failedToGenerateForXImages","noAltTextGenerated","xOfYImagesUpdated","altTextDescription","altTextRequirement1","altTextRequirement2","altTextRequirement3","pleaseSaveDocumentFirst","unsupportedMimeType","theAlternateTextIsRequired","altTextHealthDescription","altTextHealthWidget","collectionCheckFailed","healthCheckPartialWarning","localeCount","noImagesFound","statusHealthy","statusUnhealthy","totalImageCount"],"mappings":"AAEA,OAAO,MAAMA,KAAgC;IAC3CC,SAAS;IACT,yCAAyC;QACvC,eAAe;QACfC,eAAe;QACfC,UAAU;QACVC,qBAAqB;QAErB,gBAAgB;QAChBC,iBAAiB;QACjBC,wBAAwB;QACxBC,0BAA0B;QAE1B,iBAAiB;QACjBC,yBACE;QACFC,6BAA6B;QAC7BC,wBAAwB;QACxBC,kBAAkB;QAClBC,4BAA4B;QAC5BC,oBAAoB;QACpBC,mBAAmB;QAEnB,YAAY;QACZC,oBACE;QACFC,qBAAqB;QACrBC,qBACE;QACFC,qBACE;QAEF,WAAW;QACXC,yBAAyB;QACzBC,qBAAqB;QAErB,sBAAsB;QACtBC,4BAA4B;QAE5B,mBAAmB;QACnBC,0BAA0B;QAC1BC,qBAAqB;QACrBC,uBAAuB;QACvBC,2BAA2B;QAC3BC,aAAa;QACbC,eAAe;QACfC,eAAe;QACfC,iBAAiB;QACjBC,iBAAiB;IACnB;AACF,EAAC"}
+{"version":3,"sources":["../../src/translations/en.ts"],"sourcesContent":["import type { GenericTranslationsObject } from './index.js'\n\nexport const en: GenericTranslationsObject = {\n  $schema: './translation-schema.json',\n  '@jhb.software/payload-alt-text-plugin': {\n    // Field labels\n    alternateText: 'Alternate text',\n    keywords: 'Keywords',\n    keywordsDescription: 'Keywords which describe the image. Used when searching for the image.',\n\n    // Button labels\n    generateAltText: 'Generate alt text',\n    generateAltTextFor_one: 'Generate alt text for {{count}} image',\n    generateAltTextFor_other: 'Generate alt text for {{count}} images',\n\n    // Toast messages\n    altTextGeneratedSuccess:\n      'Alt text generated successfully. Please review and save the document.',\n    cannotGenerateMissingFields: 'Cannot generate alt text. Missing required fields.',\n    errorGeneratingAltText: 'Error generating alt text. Please try again.',\n    failedToGenerate: 'Failed to generate alt text. Please try again.',\n    failedToGenerateForXImages_one: 'Failed to generate alt text for {{count}} image.',\n    failedToGenerateForXImages_other: 'Failed to generate alt text for {{count}} images.',\n    noAltTextGenerated: 'No alt text generated. Please try again.',\n    skippedNoAltTextNeeded_one: 'Skipped {{count}} file that does not need alt text.',\n    skippedNoAltTextNeeded_other: 'Skipped {{count}} files that do not need alt text.',\n    skippedUnsupportedFormat_one:\n      'Alt text cannot be generated for {{count}} file. Please write it by hand.',\n    skippedUnsupportedFormat_other:\n      'Alt text cannot be generated for {{count}} files. Please write it by hand.',\n    xOfYImagesUpdated_one: '{{updated}} of {{total}} image updated.',\n    xOfYImagesUpdated_other: '{{updated}} of {{total}} images updated.',\n\n    // Help text\n    altTextDescription:\n      'Alternate text for the image. This will be used for screen readers and SEO. It should meet the following requirements:',\n    altTextRequirement1: 'Describes in 1-2 sentences, what is visible in the image.',\n    altTextRequirement2:\n      'Should convey the same information or purpose as the image, whenever possible.',\n    altTextRequirement3:\n      'Phrases like \"image of\" or \"picture of\" are unnecessary, since screen readers already announce that it\\'s an image.',\n\n    // Tooltips\n    pleaseSaveDocumentFirst: 'Please save the document first',\n    unsupportedMimeType: 'Alt text generation is not supported for {{mimeType}} files',\n\n    // Validation messages\n    theAlternateTextIsRequired: 'An alternate text is required.',\n\n    // Dashboard widget\n    altTextHealthDescription: 'Alt text coverage across upload collections.',\n    altTextHealthWidget: 'Alt Texts',\n    collectionCheckFailed: 'Status unavailable',\n    healthCheckPartialWarning: 'Some collections could not be checked right now.',\n    localeCount_one: '{{count}} locale',\n    localeCount_other: '{{count}} locales',\n    noImagesFound: 'No images found in the configured collections yet.',\n    statusHealthy: 'All set',\n    statusUnhealthy: '{{count}} missing',\n    totalImageCount_one: '{{count}} image',\n    totalImageCount_other: '{{count}} images',\n  },\n}\n"],"names":["en","$schema","alternateText","keywords","keywordsDescription","generateAltText","generateAltTextFor_one","generateAltTextFor_other","altTextGeneratedSuccess","cannotGenerateMissingFields","errorGeneratingAltText","failedToGenerate","failedToGenerateForXImages_one","failedToGenerateForXImages_other","noAltTextGenerated","skippedNoAltTextNeeded_one","skippedNoAltTextNeeded_other","skippedUnsupportedFormat_one","skippedUnsupportedFormat_other","xOfYImagesUpdated_one","xOfYImagesUpdated_other","altTextDescription","altTextRequirement1","altTextRequirement2","altTextRequirement3","pleaseSaveDocumentFirst","unsupportedMimeType","theAlternateTextIsRequired","altTextHealthDescription","altTextHealthWidget","collectionCheckFailed","healthCheckPartialWarning","localeCount_one","localeCount_other","noImagesFound","statusHealthy","statusUnhealthy","totalImageCount_one","totalImageCount_other"],"mappings":"AAEA,OAAO,MAAMA,KAAgC;IAC3CC,SAAS;IACT,yCAAyC;QACvC,eAAe;QACfC,eAAe;QACfC,UAAU;QACVC,qBAAqB;QAErB,gBAAgB;QAChBC,iBAAiB;QACjBC,wBAAwB;QACxBC,0BAA0B;QAE1B,iBAAiB;QACjBC,yBACE;QACFC,6BAA6B;QAC7BC,wBAAwB;QACxBC,kBAAkB;QAClBC,gCAAgC;QAChCC,kCAAkC;QAClCC,oBAAoB;QACpBC,4BAA4B;QAC5BC,8BAA8B;QAC9BC,8BACE;QACFC,gCACE;QACFC,uBAAuB;QACvBC,yBAAyB;QAEzB,YAAY;QACZC,oBACE;QACFC,qBAAqB;QACrBC,qBACE;QACFC,qBACE;QAEF,WAAW;QACXC,yBAAyB;QACzBC,qBAAqB;QAErB,sBAAsB;QACtBC,4BAA4B;QAE5B,mBAAmB;QACnBC,0BAA0B;QAC1BC,qBAAqB;QACrBC,uBAAuB;QACvBC,2BAA2B;QAC3BC,iBAAiB;QACjBC,mBAAmB;QACnBC,eAAe;QACfC,eAAe;QACfC,iBAAiB;QACjBC,qBAAqB;QACrBC,uBAAuB;IACzB;AACF,EAAC"}

package/dist/translations/translation-schema.json

@@ -17,22 +17,30 @@
         "collectionCheckFailed": { "type": "string" },
         "errorGeneratingAltText": { "type": "string" },
         "failedToGenerate": { "type": "string" },
-        "failedToGenerateForXImages": { "type": "string" },
+        "failedToGenerateForXImages_one": { "type": "string" },
+        "failedToGenerateForXImages_other": { "type": "string" },
         "generateAltText": { "type": "string" },
         "generateAltTextFor_one": { "type": "string" },
         "generateAltTextFor_other": { "type": "string" },
         "healthCheckPartialWarning": { "type": "string" },
         "keywords": { "type": "string" },
-        "localeCount": { "type": "string" },
+        "localeCount_one": { "type": "string" },
+        "localeCount_other": { "type": "string" },
         "keywordsDescription": { "type": "string" },
         "noAltTextGenerated": { "type": "string" },
         "noImagesFound": { "type": "string" },
         "pleaseSaveDocumentFirst": { "type": "string" },
+        "skippedNoAltTextNeeded_one": { "type": "string" },
+        "skippedNoAltTextNeeded_other": { "type": "string" },
+        "skippedUnsupportedFormat_one": { "type": "string" },
+        "skippedUnsupportedFormat_other": { "type": "string" },
         "statusHealthy": { "type": "string" },
         "statusUnhealthy": { "type": "string" },
         "theAlternateTextIsRequired": { "type": "string" },
-        "totalImageCount": { "type": "string" },
-        "xOfYImagesUpdated": { "type": "string" }
+        "totalImageCount_one": { "type": "string" },
+        "totalImageCount_other": { "type": "string" },
+        "xOfYImagesUpdated_one": { "type": "string" },
+        "xOfYImagesUpdated_other": { "type": "string" }
       },
       "required": [
         "alternateText",
@@ -47,22 +55,30 @@
         "collectionCheckFailed",
         "errorGeneratingAltText",
         "failedToGenerate",
-        "failedToGenerateForXImages",
+        "failedToGenerateForXImages_one",
+        "failedToGenerateForXImages_other",
         "generateAltText",
         "generateAltTextFor_one",
         "generateAltTextFor_other",
         "healthCheckPartialWarning",
         "keywords",
         "keywordsDescription",
-        "localeCount",
+        "localeCount_one",
+        "localeCount_other",
         "noAltTextGenerated",
         "noImagesFound",
         "pleaseSaveDocumentFirst",
+        "skippedNoAltTextNeeded_one",
+        "skippedNoAltTextNeeded_other",
+        "skippedUnsupportedFormat_one",
+        "skippedUnsupportedFormat_other",
         "statusHealthy",
         "statusUnhealthy",
         "theAlternateTextIsRequired",
-        "totalImageCount",
-        "xOfYImagesUpdated"
+        "totalImageCount_one",
+        "totalImageCount_other",
+        "xOfYImagesUpdated_one",
+        "xOfYImagesUpdated_other"
       ]
     }
   },

package/dist/types/AltTextPluginConfig.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionSlug, Field, PayloadRequest } from 'payload';
+import type { CollectionSlug, Field, PayloadRequest, Where } from 'payload';
 import type { AltTextResolver } from '../resolvers/types.js';
 import type { AltTextCollectionConfig, IncomingCollectionsConfig, NormalizedAltTextCollectionConfig } from '../utilities/mimeTypes.js';
 export type { AltTextCollectionConfig, NormalizedAltTextCollectionConfig };
@@ -18,6 +18,61 @@ export type GetImageThumbnail = (doc: Record<string, unknown>, args: {
     collection: CollectionSlug;
     req: PayloadRequest;
 }) => Promise<string> | string;
+/**
+ * Narrows the health scan of one collection to a subset of its documents — in a
+ * multi-tenant CMS, to the tenant the request is for. The returned constraint is
+ * ANDed onto the scan's MIME type filter.
+ *
+ * Called once per configured collection, so collections that do not carry the
+ * constraining field (a media library shared across tenants, say) can return `{}`
+ * instead of being queried for a field they do not have.
+ *
+ * Return `{}` to scan the collection whole.
+ *
+ * @param args.collection The slug of the collection being scanned.
+ * @param args.req The request the scan runs for.
+ */
+export type AltTextHealthBaseFilter = (args: {
+    collection: CollectionSlug;
+    req: PayloadRequest;
+}) => Promise<Where> | Where;
+/**
+ * Narrows the locales a request generates for and is measured against — in a
+ * multi-tenant CMS, to the locales of the tenant the request is for.
+ *
+ * Must return a non-empty subset of `locales`; anything else ends the operation
+ * with an error rather than writing into a locale the project does not define.
+ *
+ * @param args.locales The locales configured on the Payload config.
+ * @param args.req The request being served.
+ */
+export type FilterLocales = (args: {
+    locales: string[];
+    req: PayloadRequest;
+}) => Promise<string[]> | string[];
+/** Configuration of the alt text health feature. */
+export type AltTextHealthCheckConfig = {
+    /**
+     * Access control for the health report — both the REST endpoint and the dashboard
+     * widget, which hides itself when this denies.
+     *
+     * Use it to restrict the collection-wide report more strictly than the
+     * per-document generate endpoints (e.g. to admins).
+     *
+     * @default the plugin's `access`
+     */
+    access?: (args: {
+        req: PayloadRequest;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Narrows what the report counts. See {@link AltTextHealthBaseFilter}.
+     *
+     * This is not access control: it scopes the aggregate, it does not decide who
+     * may see it. Use `access` for that, and note the report is always filtered to
+     * the collections the requesting user can read.
+     */
+    baseFilter?: AltTextHealthBaseFilter;
+};
 /** Configuration options for the alt text plugin. */
 export type IncomingAltTextPluginConfig = {
     /**
@@ -51,6 +106,13 @@ export type IncomingAltTextPluginConfig = {
     fieldsOverride?: (args: {
         defaultFields: Field[];
     }) => Field[];
+    /**
+     * Narrows the locales this request targets. See {@link FilterLocales}.
+     *
+     * Governs bulk generation, the generate endpoint's locale validation, and the
+     * health report.
+     */
+    filterLocales?: FilterLocales;
     /**
      * Builds the image URL sent to the resolver. See {@link GetImageThumbnail}.
      *
@@ -65,19 +127,12 @@ export type IncomingAltTextPluginConfig = {
      * Controls the alt text health feature (REST endpoint, cache revalidation hooks, and dashboard widget).
      *
      * - `false` disables the entire feature.
-     * - `true` enables it, gated by `access`.
-     * - A function enables it and gates both the endpoint and the dashboard widget
-     *   with that access check — use this to restrict the collection-wide report
-     *   more strictly than the per-document generate endpoints (e.g. to admins).
-     *
-     * Regardless of the gate, the report is always filtered to the collections the
-     * requesting user can read.
+     * - `true` enables it, gated by `access` and covering every document.
+     * - An object enables it and configures it. See {@link AltTextHealthCheckConfig}.
      *
      * @default true
      */
-    healthCheck?: ((args: {
-        req: PayloadRequest;
-    }) => boolean | Promise<boolean>) | boolean;
+    healthCheck?: AltTextHealthCheckConfig | boolean;
     /**
      * The MIME type `getImageThumbnail` delivers, for every configured collection.
      *
@@ -133,6 +188,8 @@ export type AltTextPluginConfig = {
     fieldsOverride?: (args: {
         defaultFields: Field[];
     }) => Field[];
+    /** Narrows the locales one request targets. See {@link FilterLocales}. */
+    filterLocales?: FilterLocales;
     /** Function to get the thumbnail URL of an image document. */
     getImageThumbnail: GetImageThumbnail;
     /** Whether alt text health tracking is enabled. */
@@ -141,9 +198,11 @@ export type AltTextPluginConfig = {
     healthCheckAccess: (args: {
         req: PayloadRequest;
     }) => boolean | Promise<boolean>;
+    /** Narrows what the health report counts. See {@link AltTextHealthBaseFilter}. */
+    healthCheckBaseFilter?: AltTextHealthBaseFilter;
     /** The locale to generate alt texts in when localization is disabled. */
     locale?: string;
-    /** The locales to generate alt texts for. */
+    /** The locales configured on the Payload config. Empty when localization is disabled. */
     locales: string[];
     /** Maximum number of concurrent API requests for bulk generate operations. */
     maxBulkGenerateConcurrency: number;