=== Altlumen – AI Alt Text & Image Accessibility ===
Contributors: formlivodev
Tags: alt text, accessibility, ai, images, seo
Requires at least: 6.9
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate image alt text with your own AI provider, review suggestions, and fix missing alt text in WordPress content.

== Description ==

Altlumen helps you prepare and review image alternative text. Connect your own AI provider, generate suggestions, and decide what to keep. Review first is the default. Uses the WordPress AI Client on WordPress 7.0+; direct provider connections are optional.

Updating a Media Library alt field does not automatically update images already inserted into posts. Altlumen can scan supported content for missing alt text and copy an approved library description into one image at a time. A WordPress revision preserves the content before each correction.

= Published audit =

Compare the published server HTML, saved editor alt text and Media Library value for each image usage in published posts and pages. Review filled values as well as missing attributes, empty text and possible stale output. Choose a role for each usage, submit a manual or optional AI suggestion to Review, approve with a revision backup, undo, and recheck the same permalink. Library changes require a separate choice. A library difference is a review signal, not an accessibility verdict.

The first version covers Image and Gallery blocks and classic image HTML. Draft, private, password-protected and page-builder content is excluded. Only anonymous server HTML from your site's own permalink is checked; JavaScript output requires manual inspection. No site-wide cache is cleared. Local quality warnings explain possible filename text, redundant prefixes, repetition, length, keyword lists and undecided decorative roles; context and human judgment decide what is appropriate. Developers can adjust the default 150-character warning threshold with the altlumen_audit_length_limit filter.

= What you can do =

* Generate a suggestion from the Media Library, attachment details or the Image block inspector.
* Preview a suggestion before explicitly applying it. A block preview can stay in the block without changing the library.
* Approve, edit, reject, regenerate, mark decorative or undo the last saved library change.
* Queue background generation for images missing alt text, with pause, resume and cancel controls.
* Track library coverage, scanned-content coverage and suggestions waiting for review on the Dashboard.
* Scan published, draft and private posts, pages and public custom post types; fix one linked image per action.
* Use WP-CLI for generation, scanning, coverage and review of suggestions with confidence above 0.8.
* Get interface translations through translate.wordpress.org.

All these features work in this plugin. No trial period or Altlumen service account is required. Provider usage charges may apply.

= Your provider and your approval =

Bring an OpenAI, Anthropic or Google Gemini API key. On WordPress 7.0 or later, the WordPress AI provider is also available when the site's AI Client and connectors support it. Choose an image-capable model with structured text output. You can enter a custom model ID.

Existing human-written alt text is protected by default, including later manual edits to text previously written by Altlumen. Explicitly enabling overwrite changes this behavior. Quality rules clean suggestions, apply the configured length limit and keep low-confidence suggestions in the review queue. A confidence score is not a guarantee of accuracy.

Coverage counts show where alt text is present, not whether every description is correct or every accessibility requirement is met. Review descriptions in their context. The plugin provides no accessibility or legal compliance guarantee.

= Privacy and control =

Images are sent only after an explicit generation action and consent for the selected provider. An explicitly queued bulk or CLI job continues in the background after you leave the page until it finishes, is paused or is canceled. Local scans do not send images. There is no Formlivo relay or telemetry.

Saved keys use authenticated encryption derived from your WordPress authentication salts. Changing those salts can require entering the keys again. You may alternatively define ALTLUMEN_OPENAI_KEY, ALTLUMEN_ANTHROPIC_KEY or ALTLUMEN_GEMINI_KEY in wp-config.php. Keys are not placed in page HTML, JavaScript, REST responses or logs.

Known page-builder content is reported as builder-managed and is not rewritten. Unlinked external images are reported but cannot be fixed automatically. Content fixes require revisions to be enabled for that post type. Restricted editors are asked to involve an administrator if saving would strip unrelated HTML.

== Installation ==

1. In WordPress, open Plugins > Add New Plugin > Upload Plugin and select the Altlumen ZIP. Install and activate it.
2. Open Media > Altlumen > Settings. Choose a provider and enter its key, or configure the site's supported WordPress AI connectors.
3. Read the provider's terms and privacy information and give the separate image-processing consent. A connection test does not grant consent.
4. Keep Review first selected to start. Generate a suggestion, inspect it under Review and approve or edit it.
5. Use Dashboard to scan content or explicitly queue background generation.

WordPress 6.9 or later and PHP 7.4 or later are required. A current supported PHP release is recommended. Background processing needs working WordPress cron/loopback requests or a server-side Action Scheduler runner.

== Frequently Asked Questions ==

= Why does my page still show the old alt text after I changed it in the Media Library? =

Inserted image blocks can store their own alt attribute. Changing the Media Library does not replace that saved value. Use Media > Altlumen > Published audit to compare the three values, propose a correction for that usage, and approve it under Review. Revisions preserve the previous content. If the page still returns old HTML after saving, the audit reports that publication has not yet been verified; check your cache and use Recheck. Other usages and the library stay unchanged unless you explicitly choose otherwise.

= What does it cost? =

Altlumen does not include an API key or provider credits. You use your own provider account, whose usage charges and limits apply. The Dashboard shows a rough token estimate before a bulk action, not a price or billing guarantee.

= What data leaves my site? =

For generation, the selected provider receives a prepared image plus bounded context: the related post title, caption, cleaned filename, site name and target language. A content correction may also include its post title and nearby paragraph text. The image is sent as data rather than a public image URL. The provider also receives ordinary connection metadata. Local content scans do not send images.

= Which providers can I use? =

OpenAI, Anthropic and Google Gemini are supported with your own key. WordPress AI site connectors are supported on WordPress 7.0 or later when the site's AI Client supports the requested image-to-text operation. Older WordPress versions do not show that provider.

= Does a connection test send an image? =

No. The three direct providers receive an authenticated model-list GET request. The WordPress AI connection test checks local support without generating content. Image-processing consent is separate.

= Will my existing alt text be overwritten? =

By default, nonempty text that Altlumen does not own, or that a person changed after Altlumen last wrote it, is preserved. Review the overwrite setting before deliberately replacing existing text. The same guard applies to review, bulk work and CLI generation.

= How are decorative images handled? =

Mark an image decorative when an empty alt attribute is intentional. Decorative suggestions are labeled for review and approval keeps the alt text empty. A deliberately empty alt attribute is different from an absent attribute.

= Does Altlumen edit page-builder content? =

Known builder-managed content is detected and skipped. The content fixer handles supported WordPress blocks and ordinary image HTML. It does not claim page-builder synchronization.

= How fast does a bulk job run? =

Choose a maximum of 10, 30 or 60 requests per minute. Scheduling applies the limit without sleeping inside a worker. Provider retries, cron availability and server load can make a job slower. Each action processes one image. Three consecutive key or quota errors stop the job until you check the settings and resume.

= Why did a content correction stop? =

Revisions must be enabled for the post type so the previous content can be recovered. A restricted editor also cannot save a correction if WordPress would remove unrelated HTML. In that case, ask an administrator with full HTML rights. Rescan content that changed after an issue was listed.

= What happens when I delete the plugin? =

Saved provider keys are always removed. Other explicitly listed Altlumen data is removed only if you enabled the removal preference. Native image alt text, corrected post content, unknown data keys and data belonging to other plugins remain. Content revisions stay part of WordPress.

= Which image formats are supported? =

JPEG, PNG, WebP and the first frame of GIF are supported. SVG and PDF are skipped. A prepared image that remains too large is also skipped.

= Can I change the language of generated text? =

Yes. Use the site language or set a fixed locale in Settings. The English interface uses language packs from translate.wordpress.org. Generated descriptions still need human review.

= Is every missing image fixed automatically? =

No. You explicitly fix one content image at a time. If its library alt is empty, generation follows the normal review flow. An image without a matching library item remains in the report for manual attention.

== External services ==

Generation requires an explicit user action and provider-specific consent. An explicitly queued background job may continue after the page is closed. The selected provider receives a prepared image and the context described above. There is no intermediary Altlumen service. Review the current terms and privacy policy of the provider you choose.

= OpenAI =

Test connection sends an authenticated GET request to api.openai.com/v1/models, with the API key in an Authorization header and no image. Explicit generation sends the prepared image and context to api.openai.com/v1/responses. OpenAI also receives ordinary connection metadata such as the server IP.

Terms: https://openai.com/policies/services-agreement/
Privacy: https://openai.com/policies/privacy-policy/

= Anthropic =

Test connection sends an authenticated GET request to api.anthropic.com/v1/models, with the API key in an x-api-key header and the API version header, and no image. Explicit generation sends the prepared image and context to api.anthropic.com/v1/messages. Anthropic also receives ordinary connection metadata.

Terms: https://www.anthropic.com/legal/commercial-terms
Privacy: https://www.anthropic.com/legal/privacy

= Google Gemini =

Test connection sends an authenticated GET request to generativelanguage.googleapis.com/v1beta/models, with the API key in an x-goog-api-key header and no image. Explicit generation sends the prepared image and context to the selected model's generateContent endpoint on generativelanguage.googleapis.com. Google also receives ordinary connection metadata.

Terms: https://ai.google.dev/gemini-api/terms
Privacy: https://policies.google.com/privacy

= WordPress AI Client =

On supported WordPress 7.0 or later sites, the configured AI connector handles explicit generation after consent. It receives the prepared image and supporting context. The chosen connector/provider's terms and privacy policy apply; manage them under Settings > Connectors. The connection test checks local support without sending an image or generating content.

WordPress privacy: https://wordpress.org/about/privacy/
WordPress software license: https://wordpress.org/about/license/

== Security ==

Please report security issues with Altlumen privately to security@formlivo.com. See the [Formlivo security policy](https://formlivo.com/security/) for what to include and how we coordinate disclosure. Please keep vulnerability details out of public support threads until a fix is available.

== Screenshots ==

1. Dashboard with library coverage, scanned-content coverage and background job controls.
2. Review queue with editable suggestions, confidence and explicit approval actions.
3. Settings with an open first-key field and provider-specific consent.
4. Generate a suggestion in the Media Library attachment window before explicitly applying it.
5. Generate alt text in the Image block inspector, with an optional library save.
6. Published audit compares live, editor and library values for each usage, with local warnings and explicit Review proposals.

== Developers ==

The filter `altlumen_target_language( string $locale, int $attachment_id )` (since 1.0.3) selects the target locale once per generation. It receives the configured locale (or site locale) and attachment ID. Return a string matching `^[a-z]{2,3}(_[A-Z]{2})?$`, for example `de_DE`; invalid values fall back to the original locale. Single-image and bulk generation use it for provider context, quality rules and language metadata used by the review queue. Example:

    add_filter( 'altlumen_target_language', function ( $locale, $attachment_id ) {
        return 'de_DE';
    }, 10, 2 );

The existing `altlumen_prompt_context` filter still runs afterward and can change provider context. Use `altlumen_target_language` for language changes that must also affect quality rules and metadata.

== Changelog ==

= 1.0.3 =
* Add a generic target language filter shared by provider context, quality rules and language metadata in single-image and bulk generation.
* Include featured_image in the Published audit status filter.
* Exclude theme featured images from content matching and reduce keyword warnings for natural list sentences.

= 1.0.2 =
* Add Published audit for per-usage server HTML comparison, revision-backed Review proposals, undo and publication rechecks.
* Explain local alt text quality warnings, including filled values, without scores or compliance labels.
* Add read-only wp altlumen audit output in table, CSV or JSON format.
* Require WordPress 6.9 and update Action Scheduler to 4.2.0.
* Prefer the configured WordPress AI Client on WordPress 7.0+ for new installations.
* Load translations through translate.wordpress.org language packs.
* Add a generic bulk-error filter for stopping without advancing the pending image.

= 1.0.1 =
* Restore the approved Turkish copy and contributor name from the submitted package.
* Include Composer metadata and documented companion extension hooks.
* Add a Security section with the private vulnerability reporting address.

= 1.0.0 =
* Initial public release: provider connections, image suggestions, review and undo.
* Scheduled bulk generation, coverage Dashboard, individual content correction and WP-CLI.
* Human-edit protection, safe public revision handling and restricted-editor HTML protection.
* German and Turkish interface translations.

== Upgrade Notice ==

= 1.0.2 =
Requires WordPress 6.9; existing provider settings are retained. Translations use WordPress language packs.

= 1.0.1 =
Back up your site before upgrading. Existing settings and image alt text are retained. Enable revisions for content types you want to correct. Language metadata upgrades run in bounded background pages.
