=== Altify AI – Auto ALT Text Generator ===
Contributors: ravikhadka
Tags: alt text, ai alt text, image seo, accessibility, woocommerce
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Auto ALT text and AI ALT text plugin for WordPress with bulk image ALT text tools, featured image ALT text, and WooCommerce image ALT.

== Description ==

Altify AI is an auto ALT text and AI ALT text plugin for WordPress images. It helps generate descriptive image ALT text for accessibility and image SEO.

Use bulk image ALT text tools for your Media Library, generate featured image ALT text automatically, and scale WooCommerce image ALT updates with AI or offline mode.

Key features:

* Review & Undo: preview 20 offline suggestions at a time, edit them, and apply selected images only.
* Conflict-aware undo for your latest review batch, preserving later manual ALT edits.
* Improved offline quality: descriptive captions and metadata take priority; insufficient context is left unchanged for review.
* Beginner-friendly Free Offline Mode quick start with one-click `Generate First 10 ALT Texts`.
* Beginner-friendly Automation tab with upload toggle, daily schedule, and one-click `Fix Missing ALT Now`.
* Media Library ALT Assistant with ALT status column, missing ALT filter, row actions, bulk actions, and attachment edit suggestions.
* Automatic ALT generation on new image uploads with selectable mode priority (`Offline first`, `AI first`, `Offline only`, `AI only`).
* Daily background scan for missing ALT (or all images) with mode selection, run limit, and status panel.
* Top-level `Altify AI` admin menu (before Posts) with dedicated `Settings` and `Generate History` pages.
* ALT coverage report with total images, missing ALT count, completed ALT count, coverage percentage, and CSV export.
* AI mode with OpenAI model settings, rate limiting, retry/backoff, and safe fallback behavior.
* Free Offline Mode (no API) that generates ALT from title/caption/description/filename.
* Bulk Media Library processing with filters, batching, and pause/resume/stop controls.
* WooCommerce bulk generation for featured and gallery images with category/date filters.
* Generation history table with source, method (AI/Offline/Cache), ALT preview, and row-level delete controls. Settings page shows the latest 10 rows for quick review.
* Multilingual support: Auto (site locale), many built-in languages, and custom language input.
* Optional vision-based analysis for image-aware ALT suggestions.
* Native WordPress ALT field updates (`_wp_attachment_image_alt`) for SEO plugin compatibility.
* Smart protection for existing ALT text via `Only fill empty ALT` and `Overwrite existing ALT`.

SEO and accessibility benefits:

* Improves image context for screen readers.
* Reduces missing ALT text across large media libraries.
* Keeps ALT text in the native WordPress field (`_wp_attachment_image_alt`) for compatibility with SEO plugins.
* Avoids duplicate custom ALT fields and vendor lock-in.
* Supports content quality workflows with configurable length and overwrite behavior.

How it works:

1. Plugin gathers safe text context from attachment metadata (filename, title, caption, description).
2. Optional product context is added for WooCommerce images (product name/category).
3. OpenAI returns a concise ALT suggestion.
4. Result is sanitized and stored in the standard WordPress ALT field.
5. If API fails (or offline mode is used), the plugin uses a descriptive metadata-based fallback when available. Otherwise ALT stays unchanged and the result is marked Needs review.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/altify-ai-auto-alt-text-generator/`.
2. Activate the plugin through the `Plugins` screen in WordPress.
3. Go to `Altify AI > Settings`.
4. Click `Generate First 10 ALT Texts` to test Free Offline Mode without an API key.
5. Add an OpenAI API key later only if you want AI-generated ALT text.

== Frequently Asked Questions ==

= How do I preview a batch without changing my images? =

Open Altify AI > Review & Undo. Review the image thumbnails, current ALT and editable offline suggestions. Nothing is saved until you choose Apply selected. Existing ALT requires an explicit Allow replacing existing ALT selection. Previews expire after one hour. Next 20 images advances by attachment ID so applying missing ALT does not shift subsequent batches.

= What does Needs review mean? =

The available metadata is not descriptive enough, for example IMG_4829 or a generated file hash. Add a meaningful caption or write a suggestion in Review & Undo. Offline mode does not analyze image pixels or translate text; it preserves the language of your source metadata. An empty ALT may also be intentional for a decorative image. Do not select those images for generation.

= Which changes can I undo? =

Each administrator can undo their latest applied Review & Undo batch. Its originals are stored until their next non-empty batch replaces the record. This does not cover the older direct-generation tools, uploads, or scheduled scans. Undo checks the saved metadata row and exact ALT value; later edits, deleted images, and images you can no longer edit are skipped. Missing metadata is restored to missing, and an existing empty field is restored to empty. Interrupted or unconfirmed writes are not automatically undone.

= Does this change ALT already embedded in page content? =

No. This updates the Media Library attachment ALT field. Existing image blocks, page builders, or custom HTML may retain their own ALT values; review those separately.

= Does this overwrite existing ALT text? =

No, not by default. `Only fill empty ALT` is enabled by default and `Overwrite existing ALT` is disabled.

= Is this plugin useful for SEO? =

Yes. It helps maintain descriptive image ALT text, which improves image context for search engines and accessibility tools.

= Where is ALT text stored? =

In the standard WordPress attachment meta key `_wp_attachment_image_alt`, so it remains compatible with SEO plugins.

= Which images are processed for auto ALT text? =

Only new uploads are processed when `Auto-generate ALT on media upload` is enabled. You can turn this on/off in the Automation tab.

= Can it scan my old images every day for missing ALT text? =

Yes. Enable `Auto-fix missing ALT daily` in the Automation tab, choose time/scope/mode, and the plugin will process up to your daily max image limit.

= Can I run the daily scan immediately? =

Yes. Use `Fix Missing ALT Now` in the Automation tab to trigger the same scan logic instantly and refresh status counters.

= Where can I find Generate History? =

Go to `Altify AI > Generate History` in WP Admin. The `Settings` page also includes a quick history table showing the latest 10 rows.

= Can I export images that still have missing ALT text? =

Yes. Go to `Altify AI > Generate History` and use `Export Missing ALT CSV` in the ALT Coverage Report.

= Can I process only images with missing ALT text? =

Yes. Bulk mode defaults to `Only missing ALT`, and you can switch to all images if needed.

= Can I fix ALT text directly from the Media Library? =

Yes. Version 1.1.0 adds a Media Library ALT Assistant with an ALT status column, Missing ALT filter, row actions, and bulk actions for selected images.

= Can I review a suggested ALT before saving it? =

Yes. Open an image attachment edit screen and use the Altify AI ALT Assistant box to generate a Free Offline Mode suggestion, review it, and apply it.

= Does this plugin support bulk image ALT text generation? =

Yes. The `Fix Existing Images` tab processes existing Media Library images in batches with pause/resume controls.

= What happens if OpenAI API fails or rate limits? =

The plugin retries with exponential backoff for temporary API errors and uses a clean metadata-based fallback ALT text if needed.

= Can I generate ALT text without OpenAI? =

Yes. Free Offline Mode works without OpenAI. Click `Generate First 10 ALT Texts` on the Settings page or use the `Free Offline Mode` tab to run metadata-only generation with zero API calls.

= What should I do first after activating the plugin? =

Go to `Altify AI > Settings` and click `Generate First 10 ALT Texts`. This runs a small Free Offline Mode test so you can confirm the plugin is working before changing advanced settings.

= Can AI analyze the actual image (not only filename/title)? =

Yes, when `Analyze actual image (Vision)` is enabled in settings.  
When disabled (default), generation is metadata-only (filename/title/caption/description).

= Does the plugin upload image files to OpenAI? =

By default, no.  
If `Analyze actual image (Vision)` is enabled, the plugin sends a resized image preview to OpenAI for analysis.

= Can it generate featured image ALT text automatically? =

Yes. Upload automation covers regular WordPress images, including featured images when they are image attachments in your library.

= Does it support WooCommerce image ALT updates? =

Yes. It can process product featured images and gallery images when WooCommerce support is enabled.

= Can I run this on multilingual sites? =

Yes. Choose `Auto` (site locale), select from many built-in languages, or use `Custom` to enter any language name.

= Can I control cost and API usage? =

Yes. You can configure model, max tokens, temperature, batch size, and requests-per-minute limit.

= Can I delete history rows? =

Yes. History is shown in a table with `Select all`, `Remove Selected`, and `Clear All` actions.

= How do I create an OpenAI API key? =

Create one in your OpenAI account here: https://platform.openai.com/api-keys  
Quickstart guide: https://platform.openai.com/docs/quickstart

== Screenshots ==

= 1. Settings tab =
Configure auto ALT text and AI ALT text behavior, including upload automation toggle, daily missing-ALT scan, and generation modes.

= 2. Fix Existing Images tab =
Run bulk image ALT text generation for Media Library items with progress counters and history.

= 3. WooCommerce tab =
Generate WooCommerce image ALT text for product featured and gallery images with category/date filtering.

= 4. Generate History page =
Review ALT coverage totals, export missing ALT rows as CSV, manage generation logs, and trigger `Run AI Bulk Generator Now` from history tools.

== Roadmap ==

Planned improvements for upcoming releases:
Roadmap items are planned and may change based on user feedback and compatibility requirements.

= 1.0.1 (Quality + Workflow) =

* Better admin insights: per-run summaries and clearer error diagnostics.
* Stronger ALT cleanup rules for edge-case filenames and punctuation.
* Improved WooCommerce bulk UX for large product catalogs.
* Dedicated Offline Mode tab and improved generation history management.

= 1.2.0 (Performance + Control) =

* Enhanced queue reliability for high-volume media sites.
* More granular include/exclude filters for bulk processing.
* Optional CLI command for large-scale ALT generation runs.

= 1.3.0 (Localization + Integrations) =

* Additional language options based on user demand.
* Extended compatibility checks for popular SEO/workflow plugins.
* Additional reporting filters based on user feedback.

== External services ==

This plugin connects to the OpenAI API to generate ALT text suggestions for image attachments.
It is required for AI-based ALT text generation features (single upload automation, media bulk generation, and WooCommerce image bulk generation), unless Offline mode is enabled.

Service used:

* OpenAI API (`https://api.openai.com/v1/chat/completions`)

Data sent and when:

* Sent only when an admin-triggered or configured ALT generation request is executed.
* Sent data includes metadata/context built from WordPress attachment fields:
  * Attachment filename (cleaned)
  * Attachment title/caption/description
  * Optional WooCommerce product name/categories when available
  * Generation settings such as requested language and max length
* If `Analyze actual image (Vision)` is enabled, a resized image preview may also be sent.
* If `Offline mode` is enabled, no OpenAI request is sent.

Service provider legal links:

* Terms of Use: https://openai.com/policies/terms-of-use/
* Privacy Policy: https://openai.com/policies/privacy-policy/

== Upgrade Notice ==

= 1.2.0 =
Adds offline bulk preview, selected apply and conflict-aware undo. Low-context offline results are now skipped for review instead of saving generic ALT. Existing settings are preserved.

= 1.1.0 =
Adds Media Library ALT Assistant with ALT status column, missing ALT filter, row actions, bulk actions, and attachment edit review controls.

= 1.0.5 =
Adds a Free Offline Mode Quick Start, one-click first 10 ALT generation, setup checklist, clearer beginner labels, and improved empty history guidance.

= 1.0.4 =
Adds ALT Coverage Report with Media Library coverage totals and CSV export for images missing ALT text.

= 1.0.3 =
Major admin UX refresh with beginner-friendly automation controls, top-level `Altify AI` menu with `Generate History` page, and AJAX-based save/actions (no page reload).

= 1.0.2 =
Adds Offline Mode bulk tab, history table with selection/delete controls, improved logging context, and listing/readme enhancements.

= 1.0.1 =
Quality + workflow update with clearer diagnostics, stronger ALT cleanup, smarter presets, and better bulk run insights.

= 1.0.0 =
Initial stable release with auto ALT generation, bulk tools, and WooCommerce support.

== Changelog ==

= 1.2.0 =
* Added Review & Undo admin screen with 20-image previews, thumbnails, editable suggestions, and selected apply.
* Added explicit opt-in before replacing existing ALT and conflict checks against preview snapshots.
* Added per-administrator latest-batch undo with exact-value checks that preserve subsequent changes.
* Improved offline candidate priority and preserved names and descriptive wording.
* Preserved Unicode combining marks in Nepali and other languages during ALT sanitization.
* Left low-context images unchanged and marked them Needs review instead of using generic Image text.
* Invalidated older generation caches for the updated offline quality rules.
* Fixed missing-ALT bulk and daily scan pagination so skipped images do not block subsequent images.
* Added nonce checks, per-image permissions, one-use preview tokens, bounded batches, and apply/undo operation locks.

= 1.1.0 =
* Added Media Library ALT status column for image attachments.
* Added Media Library filters for Missing ALT, Has ALT, and Generated by Altify.
* Added row actions to generate Offline or AI ALT text directly from Media Library list view.
* Added Media Library bulk actions for Free Offline Mode and AI ALT generation.
* Added attachment edit screen ALT Assistant with offline suggestion preview and Apply ALT controls.
* Added admin result notices for Media Library row and bulk actions.

= 1.0.5 =
* Added Free Offline Mode Quick Start card on the Settings page.
* Added one-click `Generate First 10 ALT Texts` action for a small no-API starter run.
* Added setup checklist showing Offline Mode, new upload automation, first test run, and ALT coverage status.
* Made Free Offline Mode enabled by default for new installs.
* Improved beginner-facing labels and empty history guidance so users know what to do next.

= 1.0.4 =
* Added ALT Coverage Report on the Generate History page.
* Added total images, missing ALT, with ALT, and coverage percentage counters.
* Added secure CSV export for images missing ALT text, including attachment ID, title, filename, upload date, edit URL, and current ALT.
* Kept the report read-only so existing ALT generation behavior is unchanged.

= 1.0.3 =
* Added new Automation tab with beginner-friendly settings and helper text.
* Added upload automation toggle and upload generation mode (`Offline first`, `AI first`, `Offline only`, `AI only`).
* Added daily scan automation with schedule time, scope, mode, and max images per run.
* Added secure `Run scan now` AJAX action with nonce and capability checks.
* Added daily scan status panel (last run, next run, counters, mode/scope).
* Added daily WP-Cron scheduling/rescheduling logic and stored run summaries for UI.
* Added top-level `Altify AI` admin menu (before Posts) plus dedicated `Generate History` submenu page.
* Moved quick `Run AI Bulk Generator Now` action to `Generation History` tools and removed duplicate run buttons from AI/Offline settings sections.
* Added AJAX settings save flow and AJAX quick actions to prevent admin page reloads.
* Limited `6. Generation History` in Settings to latest 10 rows for faster review on large sites.
* Updated admin CSS with prefixed UI classes to avoid WordPress core style collisions.

= 1.0.2 =
* Added dedicated Offline Mode tab for no-API ALT generation runs.
* Replaced history log list with readable table format for non-technical users.
* Added history selection controls: Select all, Remove Selected, Clear All.
* Added persistent history IDs and server-side delete support for selected rows.
* Increased stored history capacity for better auditing.
* Refined readme descriptions/FAQ/screenshots for latest features.

= 1.0.1 =
* Better admin insights with per-run summaries (elapsed time, speed, fallback/cache counters, last error).
* Clearer OpenAI diagnostics, including detailed 429 error reasons when available.
* Stronger ALT cleanup for edge-case filenames and punctuation handling.
* Improved WooCommerce bulk UX for large catalogs (resume offset + guidance).
* Added Offline Mode tab (no API) for metadata-based ALT generation.
* Added generation history table with method/source/ALT preview and selective row removal.
* Added quick presets in Settings (Budget, Balanced, Quality).
* Added plugin list links: Settings and Donate.

= 1.0.0 =
* Initial public release.