HW SEO Autopilot for Rank Math (AI)

Bulk, AI-assisted SEO optimization for WordPress content — with first-class support for Elementor pages — that writes Focus Keyword, SEO Title and Meta Description straight into Rank Math, with an editable preview before anything is applied.

Note: the plugin's admin UI and messages are in Italian (author: HARDWEB). This README is bilingual — English first, Italiano below.

---

English

Overview

HW SEO Autopilot analyzes your content in bulk (posts, pages and custom post types), giving priority to pages built with Elementor, and uses OpenAI to automatically generate, for each page:

• the best Focus Keyword;
• an optimized SEO Title (within Rank Math's length limits);
• an optimized Snippet / Meta Description (within Rank Math's length limits).

The generated values are written into Rank Math's meta fields (rank_math_title, rank_math_description, rank_math_focus_keyword). You review and can edit every result before it is applied.

Features

• Elementor text extraction — reads content directly from _elementor_data (fast, no CSS regeneration), with automatic fallback to classic/Gutenberg post_content for non-Elementor posts.
• Selectable model — the list of OpenAI models is loaded dynamically from your API key (chat-capable models only), with a manual override field.
• Structured Outputs — requests use a strict JSON schema, with graceful degradation across model variants (temperature, token-limit parameter and JSON mode are adapted automatically, with retries).
• Editable preview — review and fix keyword/title/snippet with live character counters before applying.
• Controlled overwrite — per run, choose to fill only empty fields or overwrite everything.
• Language handling — the AI writes in the content's own language (auto-detected), or a forced locale, or the site locale.
• Robust bulk processing — batch processing with a progress bar, rate-limit (429) handling, and background execution for large volumes (Action Scheduler when available, otherwise WP-Cron) so big jobs survive closing the browser.
• Safety & undo — a backup of previous values is saved before overwriting, restorable with one click; dry-run lets you test without writing anything.
• Cost estimate — token/cost estimation based on configurable input/output prices.

Requirements

• WordPress 6.0 or higher
• PHP 7.4 or higher
• Rank Math — required (it is the write target for the SEO meta)
• Elementor — optional, enables the best text extraction
• an OpenAI API key — required for generation

Installation

1. Download or clone this repository into /wp-content/plugins/hw-autopilot-rankmath-with-AI (or upload the plugin ZIP via Plugins → Add New → Upload).
2. Activate the plugin from the WordPress Plugins menu.
3. Go to SEO Autopilot → Impostazioni (Settings), enter your OpenAI API key and validate it to populate the model list.
4. Go to SEO Autopilot → Ottimizzazione Bulk (Bulk optimization), select the posts and start the generation.

Configuration

The Settings page exposes:

Setting	Default	Notes
OpenAI API key	(empty)	Stored in the WP options table; never committed to code. Validate to load models.
Model	gpt-4o-mini	Chosen from the dynamic list or typed manually.
Language mode	auto	auto (detect) · forced (chosen locale) · site (WP locale).
SEO title length	50–60	Min/max; a title suffix budget is subtracted from the max.
Meta description length	150–160	Min/max.
Title suffix	none	none · site name · custom.
Batch size	5	Posts processed per batch.
Background threshold	50	Jobs above this run in the background.
Post types	post, page	Which post types are eligible.
Pricing (input/output per 1K tokens)	—	Used for cost estimation only.

How it works

Content extraction        → Elementor (_elementor_data) or Gutenberg/classic fallback
        │
Prompt building           → SEO rules for Rank Math (keyword 1–4 words, title/description limits, language)
        │
OpenAI (Structured Output)→ strict JSON schema, graceful degradation + retries
        │
Validation                → keyword/title/description checked against the limits
        │
Editable preview          → you review/edit with character counters
        │
Rank Math write           → rank_math_title / rank_math_description / rank_math_focus_keyword
        │                    (overwrite policy: fill-empty vs overwrite-all)
Backup + undo             → previous values stored for one-click restore

Note on the SEO score

Writing the meta fields directly does not automatically recompute Rank Math's SEO score. The score updates when the post is opened/saved in the editor, or via Rank Math's "Update SEO Score" tool. Title, keyword and description are saved and displayed correctly regardless.

FAQ

• Is Rank Math required? Yes — it is the write target. The plugin works best with Rank Math and Elementor both active.
• Does it work without Elementor? Yes. For non-Elementor content it falls back to the classic/Gutenberg content.
• Will my existing SEO data be overwritten? Only if you choose "overwrite all". By default only empty fields are filled, and a restorable backup is always saved first.

Changelog

See readme.txt for the full changelog. Current version: 1.0.2.

License

Released under the GNU General Public License v2.0 or later (GPL-2.0-or-later). See LICENSE.

Author

HARDWEB — https://hardweb.it/ · support: assistenza@hardweb.it

---

Italiano

Panoramica

HW SEO Autopilot analizza in massa i tuoi contenuti (post, pagine e CPT), con priorità a quelli costruiti con Elementor, e usa l'AI di OpenAI per generare automaticamente, per ogni pagina:

• la Focus Keyword migliore;
• un Titolo SEO ottimizzato (entro i limiti di lunghezza di Rank Math);
• uno Snippet / Meta Description ottimizzato (entro i limiti di lunghezza di Rank Math).

I valori generati vengono scritti nei campi di Rank Math (rank_math_title, rank_math_description, rank_math_focus_keyword). Puoi rivedere e correggere ogni risultato prima di applicarlo.

Caratteristiche principali

• Estrazione testo Elementor — legge il contenuto direttamente da _elementor_data (veloce, senza rigenerare CSS); fallback automatico al contenuto classico/Gutenberg per i post non-Elementor.
• Modello selezionabile — l'elenco dei modelli OpenAI è caricato dinamicamente dalla tua API key, con campo di override manuale.
• Structured Outputs — le richieste usano uno schema JSON rigoroso, con degrado graduale tra le varianti di modello (temperature, parametro sul limite di token e modalità JSON adattati in automatico, con retry).
• Anteprima editabile — rivedi e correggi keyword/titolo/snippet (con contatori di caratteri) prima di applicare.
• Sovrascrittura controllata — per ogni run scegli se compilare solo i campi vuoti o sovrascrivere tutto.
• Lingua — l'AI scrive nella stessa lingua del contenuto (rilevata automaticamente), oppure forzata, oppure quella del sito.
• Bulk robusto — elaborazione a batch con barra di progresso, gestione dei rate limit (429) ed esecuzione in background per grandi volumi (Action Scheduler se disponibile, altrimenti WP-Cron): i job grandi sopravvivono alla chiusura del browser.
• Sicurezza & undo — backup dei valori precedenti prima di sovrascrivere, con ripristino con un clic; dry-run per provare senza scrivere.
• Stima costi — stima di token/costo in base ai prezzi input/output configurabili.

Requisiti

• WordPress 6.0 o superiore
• PHP 7.4 o superiore
• Rank Math — richiesto (è il target di scrittura dei meta SEO)
• Elementor — opzionale, abilita l'estrazione ottimale del testo
• una API key OpenAI — richiesta per la generazione

Installazione

1. Scarica o clona questa repository in /wp-content/plugins/hw-autopilot-rankmath-with-AI (oppure carica lo ZIP del plugin da Plugin → Aggiungi nuovo → Carica).
2. Attiva il plugin dal menu Plugin di WordPress.
3. Vai in SEO Autopilot → Impostazioni, inserisci la tua API key OpenAI e validala per popolare l'elenco dei modelli.
4. Vai in SEO Autopilot → Ottimizzazione Bulk, seleziona i post e avvia la generazione.

Configurazione

La pagina Impostazioni espone:

Impostazione	Default	Note
API key OpenAI	(vuota)	Salvata nelle options di WP; mai inclusa nel codice. Validala per caricare i modelli.
Modello	gpt-4o-mini	Scelto dalla lista dinamica o digitato manualmente.
Modalità lingua	auto	auto (rileva) · forced (locale scelto) · site (locale WP).
Lunghezza titolo SEO	50–60	Min/max; dal max viene sottratto il budget dell'eventuale suffisso.
Lunghezza meta description	150–160	Min/max.
Suffisso titolo	none	none · nome del sito · personalizzato.
Dimensione batch	5	Post elaborati per batch.
Soglia background	50	I job oltre questa soglia girano in background.
Post types	post, page	Tipi di contenuto ammessi.
Prezzi (input/output per 1K token)	—	Usati solo per la stima costi.

Come funziona

Estrazione contenuto      → Elementor (_elementor_data) o fallback Gutenberg/classico
        │
Costruzione prompt        → regole SEO per Rank Math (keyword 1–4 parole, limiti titolo/descrizione, lingua)
        │
OpenAI (Structured Output)→ schema JSON rigoroso, degrado graduale + retry
        │
Validazione               → keyword/titolo/descrizione verificati sui limiti
        │
Anteprima editabile       → rivedi/correggi con i contatori di caratteri
        │
Scrittura Rank Math       → rank_math_title / rank_math_description / rank_math_focus_keyword
        │                    (policy: solo campi vuoti vs sovrascrivi tutto)
Backup + undo             → valori precedenti salvati per il ripristino con un clic

Nota sul punteggio SEO

La scrittura diretta dei meta non ricalcola automaticamente il punteggio SEO di Rank Math: il punteggio si aggiorna aprendo/salvando il post nell'editor oppure tramite il tool "Update SEO Score" di Rank Math. Titolo, keyword e descrizione vengono comunque salvati e mostrati correttamente.

Domande frequenti

• Serve Rank Math? Sì, è il target di scrittura. Il plugin funziona al meglio con Rank Math ed Elementor attivi.
• Funziona anche senza Elementor? Sì: per i contenuti non-Elementor usa il contenuto classico/Gutenberg come fallback.
• I miei dati SEO esistenti vengono sovrascritti? Solo se scegli "Sovrascrivi tutto". Di default vengono compilati solo i campi vuoti e viene comunque salvato prima un backup ripristinabile.

Changelog

Il changelog completo è in readme.txt. Versione attuale: 1.0.2.

Licenza

Distribuito con licenza GNU General Public License v2.0 o successiva (GPL-2.0-or-later). Vedi LICENSE.

Autore

HARDWEB — https://hardweb.it/ · supporto: assistenza@hardweb.it