Add bulk "Generate Alt Text" action to Media Library

[zeus2611]

What?

Closes #239

Adds a "Generate Alt Text" bulk action to the WordPress Media Library (list view). When one or more images are selected and the action is applied, alt text is generated sequentially for each image using the existing ai/alt-text-generation ability and saved directly to each attachment via the REST API. A live progress notice is shown while processing and replaced with a summary on completion.

Why?

Alt text generation for individual images already existed in the media modal and attachment edit screen, but there was no way to process multiple images at once. This extends the feature to support bulk workflows, addressing the remaining item from issue #239.

How?

PHP (includes/Experiments/Alt_Text_Generation/Alt_Text_Generation.php):

• Registers "Generate Alt Text" in the Media Library bulk actions dropdown via the bulk_actions-upload filter.
• Handles the action via handle_bulk_actions-upload: filters selected IDs to image attachments only, then appends ai_bulk_alt_text=1 and ai_attachment_ids=<ids> to the redirect URL.
• Detects the redirect params on page load and enqueues/localizes a new alt-text-generation-bulk script with the attachment IDs and a wp_rest nonce.

JavaScript (src/experiments/alt-text-generation/bulk.ts):

• On DOMContentLoaded, reads localized data and injects a dismissible WP admin notice.
• Loops through attachment IDs sequentially, calling the existing runAbility('ai/alt-text-generation', { attachment_id }) utility for each.
• Saves each generated alt text via apiFetch to /wp/v2/media/:id.
• Updates progress count in the notice after each item; per-item errors are counted but never abort the batch.
• Replaces the notice with a completion summary on finish.

Build (webpack.config.js):

• Adds experiments/alt-text-generation-bulk entry point.

Tests (tests/Integration/Includes/Experiments/Alt_Text_Generation/Alt_Text_GenerationTest.php):

• 5 new integration tests covering: bulk action registration (enabled/disabled), redirect URL query args for image attachments, non-image filtering, and unrelated action passthrough.

Use of AI Tools

Implementation was planned with assistance from Claude Code (Anthropic). All code was reviewed, tested, and validated.

Testing Instructions

1. Activate the plugin locally and ensure the Alt Text Generation experiment is enabled.
2. Upload at least 2–3 images to the Media Library.
3. Switch to List View in the Media Library (upload.php).
4. Select 2 or more images using the checkboxes.
5. Open the Bulk actions dropdown — verify "Generate Alt Text" appears.
6. Select it and click Apply.
7. Confirm the page redirects back to upload.php and a progress notice appears: "Generating alt text: 0 / N…".
8. Watch the counter increment as each image is processed.
9. On completion, verify the notice shows a summary: "Alt text generated for all N images.".
10. Open each processed image's Edit Media screen and confirm the Alt Text field is populated.

Testing Instructions for Keyboard

1. Tab to the Media Library list view and use Space to check image rows.
2. Tab to the Bulk actions dropdown and use arrow keys to select "Generate Alt Text".
3. Tab to the Apply button and press Enter.
4. Verify the progress notice is injected and focusable; the dismiss button (×) is reachable by keyboard.

Screenshots or screencast

Screen.Recording.2026-03-20.at.10.59.33.PM.mov

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.56%. Comparing base (cde564d) to head (f1ce5a9).

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #330      +/-   ##
=============================================
+ Coverage      57.70%   59.56%   +1.85%     
- Complexity       617      627      +10     
=============================================
  Files             46       46              
  Lines           3173     3205      +32     
=============================================
+ Hits            1831     1909      +78     
+ Misses          1342     1296      -46     

Flag	Coverage Δ
unit	59.56% <100.00%> (+1.85%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: zeus2611 <n1schay@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[jeffpaul]

Looks like there must be a character limit being enforced somewhere as this one (of two sample images used for testing) had an ellipses (...) added to the end of the Alt Text field:

I would say we either should render the entire alt text provided or enforce a character limit in the alt text generation prompt?

[zeus2611]

Thanks for catching this @jeffpaul — the truncation comes from a hard limit in the Ability class (Alt_Text_Generation.php:207-209).

This affects all alt text generation (individual + bulk). The ... gets stored literally in the alt text field, which means screen readers will read it aloud as "dot dot dot" — cutting off meaning and hurting the accessibility we're trying to improve.

The system instruction already soft-limits output to 125 characters ("when possible"). Per WCAG image alt text guidelines, alt text should be "succinct", not artificially truncated. A full 150-character description serves users better than one cut at 122 characters with ... appended.

Should we remove the hard truncation and rely on the prompt guidance?

[dkotter]

Thanks for catching this @jeffpaul — the truncation comes from a hard limit in the Ability class (Alt_Text_Generation.php:207-209).

This affects all alt text generation (individual + bulk). The ... gets stored literally in the alt text field, which means screen readers will read it aloud as "dot dot dot" — cutting off meaning and hurting the accessibility we're trying to improve.

The system instruction already soft-limits output to 125 characters ("when possible"). Per WCAG image alt text guidelines, alt text should be "succinct", not artificially truncated. A full 150-character description serves users better than one cut at 122 characters with ... appended.

Should we remove the hard truncation and rely on the prompt guidance?

Yeah, this limit has been in place since the original PR (see here). I'm not sure on the "why" here though I'd suggest we just remove that limit. I think it's fine to suggest a limit in our system instructions (though LLM's are notorious for not following length requirements) but I don't think we should truncate ourselves

[zeus2611]

Removed the hard 125-character truncation in includes/Abilities/Image/Alt_Text_Generation.php per @dkotter's feedback. The system instruction's soft limit ("Keep it under 125 characters when possible") remains as guidance for the AI. No tests were affected — no existing tests asserted truncation behavior.

[dkotter]

Tested and overall works good, left a handful of comments. Also would be great to get E2E tests here to cover these changes

[dkotter]

We could add a user check here as well. The alt text Ability does already check if the user has edit permissions on the attachment before generating alt text so we don't need that check here but could be nice to add a similar user check just to be safe

[zeus2611]

Added current_user_can( 'upload_files' ) check alongside the $doaction guard in handle_bulk_action(). The ability's own permission callback still runs per-attachment, but this provides an early exit at the bulk action level.