← Back to Accessalyze

How to Fix Missing Alt Text at Scale

Step 1: Find All Images Missing Alt Text

Start with an automated scan to generate a complete list of violations:

1. Run Accessalyze on your key pages to see the scope of the problem
2. For site-wide coverage, use a crawler like Screaming Frog, Sitebulb, or pa11y-ci to scan all pages
3. Export results to a spreadsheet with: URL, image src, current alt (if any), priority

# Using pa11y-ci to crawl a sitemap
pa11y-ci --sitemap https://yoursite.com/sitemap.xml \
         --reporter json \
         | jq '[.[] | select(.issues[].code == "WCAG2AA.Principle1.Guideline1_1.1_1_1.H37")]'

Step 2: Prioritize the Fixes

You can't fix everything at once. Prioritize images in this order:

1. Images in primary user flows — product photos, hero images, navigation icons
2. Images conveying essential information — charts, diagrams, infographics
3. Images on high-traffic pages — homepage, top 10 landing pages
4. Images in linked contexts — images inside links that need destination alt text
5. Decorative images — these get alt="" and are quick to mark

CMS-Specific Workflows

-- Find all images with empty or missing alt text in WordPress
SELECT ID, post_content
FROM wp_posts
WHERE post_type = 'attachment'
  AND post_mime_type LIKE 'image/%'
  AND (post_excerpt = '' OR post_excerpt IS NULL)
LIMIT 100;

# Shopify Admin API — update product image alt text
curl -X PUT \
  "https://YOUR-STORE.myshopify.com/admin/api/2024-01/products/PRODUCT_ID/images/IMAGE_ID.json" \
  -H "X-Shopify-Access-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"image": {"alt": "Blue cotton t-shirt in size medium"}}'

Writing Alt Text at Scale: AI-Assisted Workflow

For sites with hundreds or thousands of product images, manually writing alt text is impractical. Options:

Use AI to Generate First-Draft Alt Text

// Example: batch generate alt text using the Gemini API
const { GoogleGenerativeAI } = require('@google/generative-ai');
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: 'gemini-pro-vision' });

async function generateAltText(imageUrl) {
  const response = await model.generateContent([
    'Write a concise alt text description for this product image. ' +
    'Focus on what the product looks like, key features visible, and ' +
    'any text in the image. Under 125 characters. No "image of" prefix.',
    { inlineData: { mimeType: 'image/jpeg', data: await fetchBase64(imageUrl) } }
  ]);
  return response.response.text().trim();
}

Always review AI-generated alt text before publishing. AI can miss product names, colors, or key details.

Preventing Future Alt Text Issues

• CMS validation: Add required alt text fields to content entry forms
• CI/CD checks: Add axe-core to your test suite to catch alt text issues in PRs
• Content guidelines: Document alt text standards in your editorial style guide
• Editor training: Brief content editors on alt text requirements when they onboard

// CI check: fail build if new images lack alt text
const { axe } = require('axe-core');
const violations = results.violations.filter(v => v.id === 'image-alt');
if (violations.length > 0) {
  console.error('FAIL: Images missing alt text:', violations[0].nodes.length);
  process.exit(1);
}

← Back to Accessalyze · ← How to Write Alt Text