How I Built an AI Alt Text Generator for WordPress — and What I Learned

A developer built an AI alt text generator for WordPress to automate the creation of descriptive alt text for images, improving accessibility and SEO. The project uses a stack including a WordPress plugin, backend API, Stripe for billing, and PostHog for analytics. The developer learned key lessons about telemetry, including the importance of clear event semantics, deduplication, and privacy safeguards.

Accessibility is one of those areas everyone agrees matters, but it often gets pushed down the development queue. Alt text is a good example. Adding descriptive alt text to every image improves accessibility, helps screen-reader users understand a page, and can support SEO. But for sites with hundreds or thousands of images, writing it manually is repetitive and easy to neglect. That problem led me to build an AI alt text generator for WordPress. WordPress makes it easy to upload images, but maintaining accurate alt text across a large media library is another story. Site owners usually face one of three situations: I wanted a tool that could cut that workload while keeping the site owner in control. The goal isn't to remove human judgment — it's to make the first draft dramatically faster. The project grew into more than a simple WordPress plugin. The current stack: The WordPress plugin sends an authenticated generation request to the backend. The backend validates the user, checks available quota, processes the image, stores the usage result, and returns the generated description. For billing, Stripe webhooks are the authoritative source for subscription status. The frontend never assumes a payment succeeded just because the user returned from checkout. One of the most useful lessons came from telemetry. At one point the analytics showed: That looked like duplicated completion events. The real issue was that the two metrics measured different things: a generation start could represent one bulk job, while completion events represented each image inside that job. Comparing them directly was like comparing shopping trips with items purchased. I replaced the ambiguous lifecycle with explicit events: generation job started generation item completed generation job completed generation job failed Each job now has a generation run id , and each image can have its own generation item id . That makes it possible to answer useful questions: Clear event semantics turned out to be as important as collecting the events. Analytics code can fire more often than expected. Events may be duplicated by: To make events retry-safe, I added stable PostHog $insert id values and defined which system owns each event: This stops the same business action being counted two or three times by different parts of the app. A single checkout can pass through: WordPress → Backend API → Render logs → Stripe Checkout → Stripe webhook → Supabase → PostHog Without a shared identifier, debugging that journey is painful. I introduced: correlation id checkout attempt id generation run id signup attempt id session id site install id These let me trace one action from the plugin through the backend and into external services — especially useful when a checkout is abandoned or a login fails. Instead of searching disconnected systems by timestamp, the same correlation value appears throughout the journey. A generic login failed event isn't very useful. It doesn't tell you whether the cause was incorrect credentials, a disabled account, rate limiting, a network timeout, an unavailable API, token-creation failure, or session-storage failure. I added a controlled internal error taxonomy while keeping public error messages generic — that distinction matters because detailed public messages can reveal whether an account exists. The system now records safe internal codes such as: invalid credentials account disabled rate limited network timeout api unavailable token creation failed session creation failed unknown auth error Passwords, tokens, API keys, and raw server responses are stripped before telemetry is sent. Product analytics can become a privacy problem surprisingly quickly. The telemetry layer now removes fields such as: PostHog session recording is disabled unless explicitly enabled. The analytics should describe what happened without copying the content the user was working with. If I started again, I'd define the analytics contract before building the dashboards, documenting each event with: Retrofitting clean telemetry is possible, but it's much more work than designing it properly up front. I'd also add correlation IDs from day one — they're cheap to implement and hugely valuable once an app spans multiple services. The biggest lesson: building the AI generation feature was only one part of the product. A production-ready plugin also needs: The AI part may be the headline feature, but reliability is what turns it into a usable product. I'm also continuing to improve how generated alt text is reviewed and applied within WordPress. I'd love to hear from other WordPress, accessibility, or SaaS developers: what's been the hardest part of making your plugin production-ready?