Rustamjon Akhmedov

Posted on Jan 18 • Originally published at altaudit.com

Automating Alt Text in WordPress: What Works, What Breaks, and What Developers Should Know

#wordpress #webdev #seo #a11y

The alt text problem WordPress doesn’t really solve

WordPress technically supports alt text — but in real projects, it usually fails.

Common outcomes:

empty alt attributes
filenames like IMG_2849.jpg
copied titles that add zero semantic value

At scale, this becomes a serious issue:

accessibility audits fail
Lighthouse scores drop
image SEO brings no traffic

Manually fixing hundreds of images is not realistic.

So the real question is:

Can alt text be automated safely?

Yes — but only with constraints.

Option 1: REST API (works, but incomplete)

WordPress exposes alt text through the media endpoint:

POST /wp-json/wp/v2/media/{id}

Example:

await fetch(`/wp-json/wp/v2/media/${id}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer TOKEN"
  },
  body: JSON.stringify({
    alt_text: "Product dashboard showing analytics charts"
  })
});

This is reliable for:

bulk migrations
headless setups
external tooling

But the API doesn’t help you generate meaningful descriptions.

Option 2: Custom media fields

Some teams add their own alt field to improve editor behavior:

add_filter('attachment_fields_to_edit', function ($fields, $post) {
    $fields['seo_alt'] = [
        'label' => 'SEO Alt Text',
        'input' => 'text',
        'value' => get_post_meta($post->ID, '_seo_alt', true),
    ];
    return $fields;
}, 10, 2);

This improves structure — not scale.

Editors still skip it.

Option 3: AI-generated alt text (use carefully)

AI can generate alt text fast — but it is not context-aware by default.

Common failures:

wrong object detection
hallucinated details
incorrect assumptions about people
repeating generic phrases

Because of this, fully automatic replacement is dangerous.

What AI does well

UI screenshots
product images
icons
simple visuals

What must be reviewed

people
emotional scenes
medical or legal content

What should stay empty

Decorative images should use:

alt=""

Anything else hurts screen readers.

A safer automation model

The only approach that works in production:

scan media library
detect missing or low-quality alt text
generate suggestions (not overwrite)
preserve existing good alt text
allow selective application

Automation should assist — not silently replace.

Why this matters now

Alt text affects more than SEO:

WCAG compliance
accessibility lawsuits
Core Web Vitals audits
image discoverability

Ignoring it is becoming expensive.

What I’m working on

I’m building Alt Audit, a tool focused specifically on this workflow:

WordPress media scanning
detection of missing alt text
AI-generated suggestions
full developer control

No blind automation. No destructive updates.

Final thought

Alt text is not “content”.

It’s infrastructure for accessibility.

If it’s automated without guardrails, it breaks silently.

How do you handle alt text in your WordPress projects — scripts, plugins, or manual review?

DEV Community