# WooCommerce Alt Text Generator & WordPress Image SEO Fixer (`j0l30/woocommerce-seo-alt-text-fixer`) Actor

Audit and fix WooCommerce image SEO: generate alt text for product images and WordPress media in English, French or Arabic, write it safely (dry run, rollback) and flag heavy, non-WebP images. Outputs image issues with fixes, a CSV and a WP-CLI script. Works as an AI agent / MCP tool.

- **URL**: https://apify.com/j0l30/woocommerce-seo-alt-text-fixer.md
- **Developed by:** [Youssef ferri](https://apify.com/j0l30) (community)
- **Categories:** SEO tools, E-commerce, AI
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 image audited with fixes

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**WooCommerce Alt Text Generator & WordPress Image SEO Fixer** audits and fixes image SEO on WooCommerce stores and WordPress sites. It writes alt text for every product image and media library image that needs it, in **English, French or Arabic**, and can write it into your site for you (dry run first, full rollback).

Made for e-commerce and content sites on WooCommerce and WordPress. Output: a dataset of image issues with a suggested fix for each, page SEO and image-speed results, a site report, a CSV and a WP-CLI script. Run it in Apify Console, through the API, or as a tool for AI agents through the Apify MCP server. It also runs a **WordPress image SEO** and page-speed check: heavy images, no WebP/AVIF, missing width/height, no lazy loading. No AI keys, no paid APIs.

### Use with AI agents (MCP)

This Actor is an AI agent / MCP tool. Through the hosted [Apify MCP server](https://docs.apify.com/platform/integrations/mcp), Claude, Cursor, VS Code, ChatGPT or any MCP client can call it, read the input fields below as the tool's docs, and get the results as JSON.

- **This tool only:** `https://mcp.apify.com/?tools=j0l30/woocommerce-seo-alt-text-fixer`
- **All 5 Lycorax tools:** `https://mcp.apify.com/?tools=j0l30/shopify-seo-alt-text-fixer,j0l30/woocommerce-seo-alt-text-fixer,j0l30/website-image-seo-audit,j0l30/domain-rdap-dns-reputation-checker,j0l30/website-exposure-defense-knowledge`

Sign in with Apify (OAuth) when your client asks, or send the header `Authorization: Bearer <APIFY_TOKEN>`. Runs are billed to your Apify account at the prices in "How much does it cost?". The tool returns the run and its `datasetId`; the agent then reads the rows with `get-dataset-items`, which the server adds for you.

**Claude Desktop / claude.ai:** Settings → Connectors → Add custom connector → paste the URL as *Remote MCP server URL*.

**Claude Code:**

```bash
claude mcp add --transport http lycorax "https://mcp.apify.com/?tools=j0l30/woocommerce-seo-alt-text-fixer"
```

**Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in your project):

```json
{ "mcpServers": { "lycorax": { "url": "https://mcp.apify.com/?tools=j0l30/woocommerce-seo-alt-text-fixer" } } }
```

**VS Code** (`.vscode/mcp.json`):

```json
{ "servers": { "lycorax": { "type": "http", "url": "https://mcp.apify.com/?tools=j0l30/woocommerce-seo-alt-text-fixer" } } }
```

**ChatGPT** (Developer mode on): Settings → Apps & Connectors → Create → *MCP Server URL* = the URL, *Authentication* = OAuth. ChatGPT can't change a connector's tools later, so pick the one-tool or the all-tools URL first.

Swap in the all-tools URL to give your agent every Lycorax tool at once.

**Example prompts**

1. *"Audit the WooCommerce product images on https://nalgene.com (first 50 products) and tell me which ones have missing or filename alt text, with a suggested fix for each."*
2. *"Check https://my-shop.ma in Arabic (altLanguage ar), include 200 media library images, and list the images over 200 KB or not in WebP/AVIF."*
3. *"I own https://my-shop.com. Do a dry-run auto-fix with my WordPress Application Password and show me what would change before anything is written."*

Auto-fix changes a live site: agents should run with `dryRun: true` first and set `confirmAuthorized` only after the site owner says yes.

**Output sample.** Two items from a real run on the public store nalgene.com (shortened). Rows have `type` `image`, `page`, `fix`, `rollback` or `report`.

```json
[
  {"type": "image", "source": "product", "product_title": "32oz Wide Mouth Mythical Creatures Bottle", "image_src": "https://nalgene.com/wp-content/uploads/2026/10/Mothman_Front.avif", "current_alt": "Mothman Front", "issues": ["filename"], "suggested_alt": "32oz Wide Mouth Mythical Creatures Bottle - Water Bottles, front view", "alt_language": "en", "file_size_kb": 17, "mime_type": "image/avif", "speed_issues": []},
  {"type": "page", "url": "https://nalgene.com/", "score": 80, "speed_score": 50, "issues": ["images_without_alt", "images_missing_width_height", "images_not_lazy_loaded", "images_not_webp_avif"], "images_total": 160, "images_without_alt": 20, "images_missing_dimensions": 39, "images_not_webp_avif": 80}
]
```

Other Lycorax tools: [Shopify Alt Text Generator](https://apify.com/j0l30/shopify-seo-alt-text-fixer) · [Image SEO Checker for Any Website](https://apify.com/j0l30/website-image-seo-audit) · [Domain Reputation Checker](https://apify.com/j0l30/domain-rdap-dns-reputation-checker) · [Website Exposure Audit & Dorks List for Defense](https://apify.com/j0l30/website-exposure-defense-knowledge).

### What does it do?

- **Alt text audit.** It flags images whose alt text is `missing`, `generic` ("image", "photo", "صورة"), a `filename` (WordPress often copies "Mothman_Front.avif" into the alt as "Mothman Front"), a `duplicate`, `too_long` (over 125 characters) or uses a `redundant_prefix` ("image of...", "photo de...").
- **Alt text generator, in your site's language.** It writes a unique, descriptive alt from the product name, category and brand, and reads the angle from the file name. English: "back view". French: "vue de dos". Arabic: "منظر خلفي". Every alt is 125 characters or less, in line with WCAG. The rules are fixed, so the same product always gets the same alt: no AI guesswork and no AI bill.
- **Language detection.** Auto mode reads the WordPress Site Language (when you give an admin login for auto-fix), then the page's `<html lang>`, then the script of your product names. Set `altLanguage` to `en`, `fr` or `ar` to choose yourself. On a French site with Arabic product names, the angle words follow the name, so Arabic and French are never mixed in one alt.
- **Image page-speed checks.** Per image: over 200 KB, not WebP/AVIF. Per page: images without `width`/`height` (layout shift, CLS), images below the fold without `loading="lazy"` (the first two are left alone, since your main image should load fast), and heavy or old-format images. Sizes come from the WordPress media API (`media_details.filesize`). Only when WordPress doesn't say, it sends a few HEAD requests: capped by `maxHeadRequests`, checked against robots.txt and at least 1 second apart.
- **Apply in one command.** `alt-text-fixes.sh` holds one `wp post meta update <id> _wp_attachment_image_alt "..."` line per image. Review it, then run it on your server. Or use auto-fix below.
- **Media library too.** Turn on `maxMediaImages` to audit blog and page images, not just products.
- **On-page SEO audit.** Title length, meta description, H1 count, canonical tag, Product schema, Open Graph image and images without alt, with a 0 to 100 SEO score and an image speed score per page.
- **Fix-first list.** The 5 most common problems on the site.

### Why fix WooCommerce alt text and image weight?

Google Images reads alt text to understand product photos, and screen reader users depend on it. WooCommerce leaves alt text empty, or copies in the file name, unless someone fills it by hand. On a large catalog that takes hours, and the gap breaks WCAG 2.2. Heavy JPGs and images without width and height slow pages down and make them jump while loading, which hurts Core Web Vitals and sales.

Arabic and French stores are usually left out: most alt text tools write English only. This one writes proper Arabic (right to left, Arabic comma) and French for stores in Morocco, the Gulf, France, Belgium, Canada and beyond.

Better alt text and lighter images help search engines and shoppers. No tool can promise a ranking or traffic: that depends on Google and on your whole site.

### Who is it for?

- **WooCommerce and WordPress site owners** who want image SEO and accessibility fixed fast
- **Arabic and French stores** that need alt text in their own language
- **Agencies and freelancers** who audit client or prospect sites, since it works on any public WooCommerce site
- **AI agents and MCP clients** that need clean JSON

### How much does it cost?

Pay per result, and platform usage is included.

| Event | Price |
|---|---|
| Image audited, with a suggested fix | $0.004 per image ($4 per 1,000) |
| Page SEO audit | $0.02 per page |
| Site report + CSV + WP-CLI script | $0.10 per run |
| Image fixed (auto-fix) | $0.01 per image written to your site |

Language detection and the page-speed checks are included at no extra cost. With "Only images that need fixing" on, an image is returned (and counted) when it has an alt text problem or a speed problem.

### Input

```json
{ "siteUrl": "https://your-site.com", "maxProducts": 250, "maxMediaImages": 0, "maxAuditPages": 20, "onlyImagesWithIssues": true, "altLanguage": "auto", "checkPageSpeed": true, "maxHeadRequests": 50 }
```

### Output

```json
{ "type": "image", "source": "product", "product_title": "32oz Wide Mouth Mythical Creatures Bottle", "image_id": 123, "current_alt": "Mothman Front", "issues": ["filename"], "suggested_alt": "32oz Wide Mouth Mythical Creatures Bottle - Water Bottles, front view", "alt_language": "en", "file_size_kb": 342, "mime_type": "image/jpeg", "speed_issues": ["over_200kb", "not_webp_avif"] }
```

Arabic store example: `"suggested_alt": "حقيبة جلدية يدوية الصنع - حقائب، منظر خلفي"`. French: `"Sac en cuir - Sacs, vue de dos"`.

Items of `type` `page` hold the SEO `score`, `speed_score` and counts (`images_over_200kb`, `images_missing_dimensions`, `images_not_lazy`, `images_not_webp_avif`). The `report` item holds totals, `alt_language` and where it came from, `image_speed_issue_counts`, `page_speed_issue_counts`, `average_image_speed_score`, a `fix_first` list, `csv_url` and `wp_cli_script_url`. The **Page speed (images)** dataset view shows only the speed columns.

### AI agents can pay here (x402, USDC)

Agents can pay with [x402](https://docs.apify.com/integrations/x402) in USDC on Base and call `https://api.apify.com/v2/acts/j0l30~woocommerce-seo-alt-text-fixer/run-sync-get-dataset-items`.

### FAQ

#### Do I need WooCommerce API keys?

No. It uses the public WooCommerce Store API and WordPress REST API, the same data your shop pages show.

#### Does it change my site?

Not unless you turn on auto-fix with your own Application Password and turn off dry run. By default it only reads, and you decide whether to run the WP-CLI script.

#### Can it write alt text in Arabic or French?

Yes. Leave `altLanguage` on auto, or pick `ar` or `fr`. Auto-fix writes the alt in that language.

#### Does it compress or convert my images?

No. It finds the heavy and old-format images so you can convert them to WebP or AVIF with your usual plugin or tool. It never uploads or changes image files.

#### What if the REST API is disabled?

The run stops with a clear message, and you're charged nothing.

#### Does it work on a WordPress site without WooCommerce?

Yes, for the media library. Set **Media library images** (`maxMediaImages`) above 0 and it audits blog and page images through the WordPress REST API, even with no shop. With no products and the media audit off, there's nothing to audit, so the run stops without charging.

#### Shopify store?

Use the [Shopify Alt Text Generator](https://apify.com/j0l30/shopify-seo-alt-text-fixer). For a site on another CMS, use the [Image SEO Checker](https://apify.com/j0l30/website-image-seo-audit).

### How it compares (honestly)

- **WordPress SEO and alt text plugins:** a plugin runs inside your site and can fill alt text as you upload. This Actor runs outside your site, so there's nothing to install, and it can audit any public WooCommerce site. It doesn't hook into new uploads: run it again or schedule it in Apify.
- **AI vision alt text tools:** they can describe what's in a photo beyond your product data. This one doesn't look at the photo; it writes from the product name, category, brand and file-name angle, so it never invents details and needs no AI keys. For scene descriptions, a vision tool fits better.
- **Image optimization plugins:** they compress and convert images. This Actor only finds the heavy and old-format ones; it never changes image files.

### Real case study (anonymized)

**Outdoor gear brand on WooCommerce, audited 17 Oct 2026.** 18 of 21 product and media images needed fixes: 17 had no alt text, and 1 just repeated its file name ("Mothman Front"). Fixes like "32oz Wide Mouth ... Bottle - Water Bottles, front view" were written to a CSV and a one-command WP-CLI script. Pages scored 85/100 on average.

### Auto-fix (premium): write the fixes into WordPress for you

Turn on **Fix alt text automatically** and the Actor writes the suggested alt text straight into your media library through the official WordPress REST API.

- **Dry run first (on by default).** See every planned change (before → after) without touching anything.
- **Safe.** It re-reads each image right before writing, and skips any alt text someone has changed since the audit. It never overwrites a good human-written alt.
- **Logged and reversible.** Every change is a `fix` record. You also get `rollback.json` and `rollback.sh`. Paste `rollback.json` into the **Rollback** field to restore everything, free of charge.
- **Your login stays yours.** Use a WordPress **Application Password** (Users → Profile → Application Passwords), never your main password. It's stored as an Apify secret and sent only over HTTPS, and you can revoke it any time. You must confirm you own or are authorized to change the site.
- **In your language.** It writes English, French or Arabic alt text, following `altLanguage` or the detected site language.
- **$0.01 per image actually fixed.** Dry runs, skips, failures and rollbacks are free.

### More tools from the same publisher

- [Shopify Alt Text Generator](https://apify.com/j0l30/shopify-seo-alt-text-fixer): bulk alt text audit and auto-fix for Shopify product images.
- [Image SEO Checker for Any Website](https://apify.com/j0l30/website-image-seo-audit): image SEO and alt text checks on any CMS, with white-label PDF reports.
- [Domain Reputation Checker](https://apify.com/j0l30/domain-rdap-dns-reputation-checker): bulk RDAP lookup, DNS, SPF and DMARC checks and a risk score.
- [Website Exposure Audit & Dorks List for Defense](https://apify.com/j0l30/website-exposure-defense-knowledge): playbooks to find and fix leaked files on sites you own.

### Legal and responsible use

- **Public pages only.** It reads what any browser or search engine can see. No login, and it never bypasses paywalls, captchas or blocks.
- **Respects robots.txt.** It follows the rules for `User-agent: *` and `LycoraxSEOAudit`, honors `Crawl-delay`, and waits at least 1 second between requests. Every skipped URL is counted in `skipped_by_robots_txt`.
- **No personal data.** It collects only page URLs, image URLs, alt text and SEO tags. Nothing is stored after your run except your own results.
- **Read-only by default.** It changes a site only in premium auto-fix mode, with the owner's own credentials or Cloudflare account and explicit authorization.
- **Your responsibility.** Audit sites you own or are authorized to audit, or use the data for public research, and follow the target site's terms.
- **Anonymized case studies.** We don't name any brand without its permission.
- **Polite page-speed checks.** File sizes come from your WordPress media API first. HEAD requests are capped, follow each host's robots.txt and wait at least 1 second. No paid APIs and no third-party services.
- **No ranking guarantees.** It reports facts about your images and pages. Rankings depend on Google.
- Not affiliated with or endorsed by Shopify, WooCommerce, WordPress or Google. Trademarks belong to their owners.

### Privacy

No tracking, and no calls beyond the site you name (and, for size checks only, the host that serves its images). By Youssef Ferri / [Lycorax Technologies](https://ko-fi.com/lycorax).

# Actor input Schema

## `siteUrl` (type: `string`):

Public URL of the WooCommerce store or WordPress site to audit. No login or API keys needed for the audit. Example: https://nalgene.com

## `maxProducts` (type: `integer`):

Maximum number of products to scan (up to 5,000). Example: 250

## `maxMediaImages` (type: `integer`):

Also audit this many images from the WordPress media library (blog posts, pages). 0 skips it. Example: 200

## `maxAuditPages` (type: `integer`):

Home page plus product pages to audit for title, meta description, H1, canonical and schema. 0 skips the page audit. Example: 20

## `onlyImagesWithIssues` (type: `boolean`):

true = return (and charge for) only images with alt text or page-speed problems. false = return every image. Example: true

## `altLanguage` (type: `string`):

Language of the suggested alt text: auto, en, fr or ar. Auto reads the WordPress site language (with an admin login), the page's html lang, or the script of your product names. Auto-fix writes alt text in this language. Example: ar

## `checkPageSpeed` (type: `boolean`):

true = flag images over 200 KB, not WebP/AVIF, missing width/height (layout shift) and not lazy-loaded. Sizes come from the WordPress media API, with a few polite HEAD requests as backup. Example: true

## `maxHeadRequests` (type: `integer`):

Only used when WordPress doesn't report a file size: upper limit of HEAD requests, each robots.txt-aware and at least 1 second apart. 0 turns them off. Example: 50

## `autoFix` (type: `boolean`):

Premium. true = write the suggested alt text into your WordPress media library through the REST API. Needs wpUsername, wpAppPassword and confirmAuthorized. Every change is logged and can be rolled back. Example: false

## `dryRun` (type: `boolean`):

For autoFix. true = show exactly what would change without touching your site. false = apply the changes. Run with true first. Example: true

## `confirmAuthorized` (type: `boolean`):

Set to true only if you own this site or are authorized to change it. Required for autoFix and rollback. AI agents: ask the site owner before setting it. Example: true

## `wpUsername` (type: `string`):

For autoFix and rollback: the WordPress user that owns the Application Password (Editor or Administrator). Example: shop-admin

## `wpAppPassword` (type: `string`):

Secret, for autoFix and rollback. Create one in WordPress: Users → Profile → Application Passwords. Revoke it any time. Never use your main password. Example format: abcd efgh ijkl mnop qrst uvwx

## `maxFixes` (type: `integer`):

Upper limit of images changed in one autoFix run. Example: 500

## `rollback` (type: `array`):

Free undo. Paste the array from rollback.json of an earlier applied fix run. Restores the original alt text of each image. Needs wpUsername, wpAppPassword and confirmAuthorized. Example: \[{"id": 1234, "alt_text": ""}]

## Actor input object example

```json
{
  "siteUrl": "https://nalgene.com",
  "maxProducts": 20,
  "maxMediaImages": 0,
  "maxAuditPages": 3,
  "onlyImagesWithIssues": true,
  "altLanguage": "auto",
  "checkPageSpeed": true,
  "maxHeadRequests": 5,
  "autoFix": false,
  "dryRun": true,
  "confirmAuthorized": false,
  "maxFixes": 500
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `csv` (type: `string`):

No description

## `report` (type: `string`):

No description

## `script` (type: `string`):

No description

## `speed` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "siteUrl": "https://nalgene.com",
    "maxProducts": 20,
    "maxAuditPages": 3,
    "maxHeadRequests": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("j0l30/woocommerce-seo-alt-text-fixer").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "siteUrl": "https://nalgene.com",
    "maxProducts": 20,
    "maxAuditPages": 3,
    "maxHeadRequests": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("j0l30/woocommerce-seo-alt-text-fixer").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "siteUrl": "https://nalgene.com",
  "maxProducts": 20,
  "maxAuditPages": 3,
  "maxHeadRequests": 5
}' |
apify call j0l30/woocommerce-seo-alt-text-fixer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,j0l30/woocommerce-seo-alt-text-fixer"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/974C8bjiEqIDw2a8u/builds/OyayTRF6ucbXHH5Mt/openapi.json