=== AI Alt Text Builder – Alt Text Generator for Image SEO & Accessibility ===
Contributors: rankpilotai
Tags: alt text, alt text generator, image seo, accessibility, ai
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.17
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI alt text generator: fix missing image alt text in one click or in bulk, for better image SEO and accessibility. 25 free generations, no API key.

== Description ==
AI Alt Text Builder writes accurate, descriptive alt text for the images in your Media Library, in one click or in bulk.

Images without alt text cost you twice. Search engines cannot tell what the image shows, so it ranks lower in Google Images, and screen reader users hear nothing at all. Accessibility standards such as WCAG 2.1, which both the ADA Title II rule in the US and the European Accessibility Act in the EU build on, require a text alternative for every meaningful image.

**Start free in seconds:** 25 free generations, no sign-up and no API key. Prefer your own OpenAI API key? Then single-image generations are unlimited, and you only pay OpenAI's usage.

**Fixing hundreds of images?** Pro writes alt text for your whole Media Library in bulk and can fill it in automatically on every new upload. Plans start at $2.99/month, billed yearly. [See pricing](https://rankpilotai.com/ai-alt-text-builder-pricing/)

== Highlights ==

- **Works instantly** - no registration required, 25 free tokens on first use
- **BYOK mode** - use your own OpenAI API key for unlimited single image generations
- One-click “Generate with AI” button on Media Library items and the attachment edit screen
- Automatically saves to `_wp_attachment_image_alt`
- Built-in ALT-length score badge (0-100) and a sortable Media Library column, so missing or weak alt text is easy to find
- Works with every image in the Media Library, including WooCommerce product images, and with any theme, page builder or SEO plugin
- **Pro:** Bulk generation, auto-generate on upload, all languages, all models, custom prompts
- Language selector (English, Deutsch, Francais, Espanol, Turkce, or custom)
- Model choice (GPT-4.1 Mini, GPT-4.1, GPT-4o)

== External services ==

This plugin connects to RankPilotAI’s API to generate ALT text and to fetch token status.

=== What is sent and when ===

- **Trial mode:** Site URL is sent to RankPilotAI for registration. Image URL is sent to RankPilotAI for processing.
- **BYOK mode:** Image URL is sent directly to OpenAI's API using your own API key. Nothing is sent to RankPilotAI.
- **Pro mode:** Image URL, file name, current ALT, selected model, language, site URL, domain, plugin slug, and Site Token are sent to RankPilotAI.
- On token-status checks in the settings page (Pro mode only): Site Token, site URL and domain.

=== Why it is sent ===

- To generate the requested ALT text and return it to your Media Library item
- To authorize usage and show your remaining balance (Pro mode)
- To register and track trial token usage (Trial mode)

=== Endpoints ===

- https://rankpilotai.com/wp-json/rankpilotai/v1/alt-text (Pro)
- https://rankpilotai.com/wp-json/rankpilotai/v1/alt-batch (Pro bulk)
- https://rankpilotai.com/wp-json/rankpilotai/v1/token-info (Pro)
- https://rankpilotai.com/wp-json/rankpilotai/v1/trial-register (Trial)
- https://rankpilotai.com/wp-json/rankpilotai/v1/trial-alt (Trial)
- https://api.openai.com/v1/chat/completions (BYOK - direct to OpenAI)

=== Providers ===

- RankPilotAI (Terms: https://rankpilotai.com/terms-and-conditions, Privacy: https://rankpilotai.com/privacy-policy)
- OpenAI (BYOK mode only - Terms: https://openai.com/policies/terms-of-use, Privacy: https://openai.com/policies/privacy-policy)

== Installation ==
1. Upload and activate the plugin.
2. Go to **AI Alt Text Builder** in the admin menu.
3. Choose your mode:
   - **Free Trial** - Click "Start Free Trial" for 25 free tokens (no registration needed)
   - **Own API Key** - Enter your OpenAI API key for unlimited single image generations
   - **Pro** - Enter your RankPilotAI Site Key for full features
4. Open **Media → Library** or an **attachment** and click **Generate with AI**.

== Frequently Asked Questions ==
= Do I need to register or create an account? =
No. The free trial starts instantly with one click. For BYOK mode, just paste your OpenAI API key.

= Is there a free plan? =
Yes. 25 free tokens are included. After that, use your own OpenAI API key (unlimited, free) or upgrade to Pro.

= Does it overwrite my existing ALT texts? =
Only when you click **Generate** for a given image (or run a bulk action). It writes to WordPress’ standard `_wp_attachment_image_alt` field.

= What languages are supported? =
English, German, French, Spanish, Turkish — plus **Other/Custom**. Enter any language name and we’ll pass it to the generator.

= Will it change image file names or titles? =
No. It only sets the ALT text and stores a score `_aatb_score` meta (for the badge/column).

= Does it work with other media/SEO plugins? =
Yes. ALT text is a core WordPress field, so other plugins and themes will read it normally.

= Does alt text help SEO? =
Yes. Search engines read alt text to understand what an image shows, which helps the image appear in Google Images and gives the page more relevant context. Good alt text describes the image in plain words; it is not a place to stuff keywords, and the generator does not do that.

= Does it help with accessibility compliance (WCAG, ADA, European Accessibility Act)? =
It fills the text alternative that WCAG success criterion 1.1.1 asks for on meaningful images, which is one of the most common failures in accessibility audits. It does not make a whole site compliant on its own: other WCAG criteria, such as colour contrast and keyboard access, still apply.

= Can I generate alt text for all my existing images at once? =
Yes, with Pro. Bulk generation works through your Media Library images in batches, and auto-generate fills in alt text for every new upload. The free trial and BYOK mode generate one image at a time.

== Screenshots ==
1. Media modal with **Generate with AI**
2. Attachment edit screen — button + score badge
3. Settings → **Site Key** & **Usage Overview**
4. Settings → **Alt-Text Language** & **Model**

== Changelog ==

= 1.0.17 =
* Fix: when the RankPilotAI API answered with a structured error object (for example `{"error":{"message":"..."}}`) instead of a plain string, generating ALT text ended in a server error and the real reason never reached you. The message inside the object is now shown. This extends the 1.0.16 trial fix to the Site Key path.
* Maintenance: replaced the deprecated `jQuery.trim()` (removed in jQuery 4) in the ALT score badge with the native `String.prototype.trim()`. The score is calculated exactly as before.
* Compatibility: verified on WordPress 7.1.3 with PHP 8.5. The official Plugin Check reports zero errors, and the Media Library (list and grid), the attachment and post editors and the settings screen load without a single PHP notice or deprecation.

= 1.0.16 =
* Fix: removed a PHP warning ("Undefined array key") that the plugin raised every time WordPress built the attachment fields, which is on every media modal open. WordPress does not define an `html` key for the alternative text field, and the plugin appended to it without checking. On sites that display PHP notices, the warning could leak into the media modal response.
* Hardening: if the trial API returns a structured error object instead of a string, the request no longer ends in a fatal error; the message is shown to you instead.
* Maintenance: the plugin now passes the official WordPress Plugin Check with zero errors. This covers output escaping, translator comments on every placeholder string, wp_parse_url(), and prepared uninstall queries. Where a check does not apply, the exemption is documented inline with its reason rather than left silent.
* Compatibility: verified on a real WordPress 7.1 install, including the Media Library list table, the media modal and the post editor.

= 1.0.15 =
* NEW: the Alt Score column in the Media Library is now sortable, as the description has always claimed. Empty ALT text sorts as 0, matching the badge.
* Fix: the "Generate with AI" button inside the media modal no longer appears without the script that powers it. The button used to render on any screen that opens the modal, while its JavaScript only loaded on the Media Library and attachment screens, so clicking it did nothing.
* Fix: files the vision models cannot read (SVG, HEIC, AVIF and similar) are now rejected up front with a clear message instead of consuming a token on a request that was going to fail. WordPress 7.1 lets the browser convert and generate files before upload, so the Media Library can hold more formats than before.
* Hardening: request values are unslashed before sanitizing, and the uninstall cleanup query is now prepared with esc_like().
* Compatibility: tested with WordPress 7.1.

= 1.0.14 =
* Maintenance: added the missing "Plugin URI" header and translated remaining inline code comments to English.
* Compatibility: re-verified with WordPress 7.0.

= 1.0.13 =
* Maintenance: routine housekeeping, minor code cleanup and performance tuning. No functional changes.
* Compatibility: re-verified with WordPress 7.0.

= 1.0.12 =
* Maintenance: minor polish, code cleanup and stability improvements. No functional changes.
* Compatibility: re-verified with WordPress 7.0.

= 1.0.11 =
* Maintenance: internal code cleanup and stability improvements. No functional changes.
* Compatibility: re-verified with WordPress 7.0.

= 1.0.10 =
* Compatibility: tested up to WordPress 7.0.
* Maintenance: minor housekeeping and copy cleanup. No functional changes.

= 1.0.9 =
* NEW: Three-mode system - Trial (25 free tokens), BYOK (your own OpenAI key), Pro (RankPilotAI).
* NEW: Plugin works immediately after install with zero-friction free trial.
* NEW: BYOK mode - unlimited single image generations using your own OpenAI API key.
* NEW: Auto-generate alt text on image upload (Pro feature).
* NEW: Redesigned settings page with mode selection, feature comparison table, and Pro feature indicators.
* Bulk generation and auto-generate are now Pro-only features.
* Score badge and column hidden in BYOK mode.
* Language and model selection locked to English/Mini in Trial and BYOK modes.

= 1.0.8 =
* Updated default AI model from GPT-4o-mini to GPT-4.1 Mini for improved quality and performance.
* Backward compatibility maintained — existing GPT-4o-mini selections are automatically migrated.

= 1.0.7 =
* UI: Redesigned settings page with modern card-based layout, gradient header, improved navigation and responsive design.
* UI: Settings header now displays the official AI Alt Text Builder logo.
* UI: Modernized admin CSS for generate button and score badges.

= 1.0.6 =
* Maintenance: minor version consistency updates and small documentation/copy cleanup. No functional changes.

= 1.0.5 =
* Maintenance: minor version consistency updates and small documentation/copy cleanup. No functional changes.

= 1.0.4 =
* Tested up to WordPress 6.9.

= 1.0.3 =
* New installs start with an empty Site Key field instead of a random generated key.

= 1.0.2 =
* Tweak: removed extra “View details” link on the Plugins screen and synced short description. No functional changes.

= 1.0.1 =
* Tweak: Updated short description and plugin listing copy. No functional changes.

= 1.0.0 =
* Initial public release: one-click ALT generation + “Alt Score” badge.
* Normalized usage overview: Remaining = Plan Limit − Global Usage (matches RankPilotAI account dashboard).
* Language selector and prompt improvements.
* New settings UI, bulk actions polish and sortable “Alt Score” column.
* Stability and compatibility tweaks on admin screens.


