*/ public static function sections(): array { return array( 'basics' => __( 'Basics', 'ai-rank-suite' ), 'title' => __( 'Title & snippet', 'ai-rank-suite' ), 'content' => __( 'Content', 'ai-rank-suite' ), 'readability' => __( 'Readability', 'ai-rank-suite' ), 'links' => __( 'Links & media', 'ai-rank-suite' ), 'ai' => __( 'AI readiness', 'ai-rank-suite' ), 'technical' => __( 'Technical', 'ai-rank-suite' ), ); } /** * Words that carry emotional charge in a headline. * * German first: this plugin is sold into the DACH market, and an English- * only word list would fail every German title and tell its author their * headline was flat when it was not. Filterable so an agency can bring its * own list for another language. * * @return array */ public static function sentiment_words(): array { /** * Filter the sentiment word list the title checks score against — bring your own list for another language. * * @param array $words Lower-case words, German and English by default. */ return (array) apply_filters( 'airanksuite/checks/sentiment_words', array( // German — positive 'beste', 'bester', 'besten', 'einfach', 'schnell', 'sicher', 'kostenlos', 'gratis', 'neu', 'top', 'perfekt', 'ideal', 'wichtig', 'effektiv', 'erfolgreich', 'günstig', 'schön', 'stark', 'clever', 'smart', 'praktisch', 'zuverlässig', 'beliebt', // German — negative / cautionary 'fehler', 'problem', 'gefahr', 'schlecht', 'falsch', 'vermeiden', 'schwierig', 'teuer', 'riskant', 'warnung', 'achtung', 'nie', 'kein', // English — positive 'best', 'easy', 'fast', 'free', 'new', 'top', 'perfect', 'ideal', 'proven', 'essential', 'effective', 'successful', 'cheap', 'great', 'smart', 'simple', // English — negative 'worst', 'mistake', 'error', 'problem', 'danger', 'bad', 'wrong', 'avoid', 'hard', 'expensive', 'risky', 'warning', 'never', 'stop', ) ); } /** * Words that make a reader expect something worth their time. * * @return array */ public static function power_words(): array { /** * Filter the power-word list the title checks score against. * * @param array $words Lower-case words, German and English by default. */ return (array) apply_filters( 'airanksuite/checks/power_words', array( // German 'endlich', 'sofort', 'garantiert', 'exklusiv', 'geheim', 'bewiesen', 'ultimativ', 'komplett', 'vollständig', 'schritt', 'anleitung', 'checkliste', 'ratgeber', 'vergleich', 'test', 'erfahrung', 'wirklich', 'überraschend', 'unglaublich', 'jetzt', 'heute', 'schnellste', 'einfachste', 'wichtigste', 'unverzichtbar', // English 'finally', 'instantly', 'guaranteed', 'exclusive', 'secret', 'proven', 'ultimate', 'complete', 'definitive', 'step', 'guide', 'checklist', 'comparison', 'review', 'surprising', 'incredible', 'now', 'today', 'fastest', 'easiest', 'must', ) ); } /** * Run every check that needs a focus keyword. * * @param array $headings Headings. * @param array $paragraphs Paragraphs. * @return array> */ public static function keyword( WP_Post $post, string $html, int $words, array $headings, array $paragraphs, string $keyword ): array { $out = array(); $text = Html::text( $html ); $low = self::lower( $text ); $kw = self::lower( $keyword ); // --- Basics ------------------------------------------------------- $slug = self::lower( str_replace( array( '-', '_' ), ' ', (string) $post->post_name ) ); $out[] = self::make( 'kw_in_url', 'seo', 'basics', str_contains( $slug, $kw ) ? 'pass' : 'warn', 2, str_contains( $slug, $kw ) ? __( 'The focus keyword is in the URL.', 'ai-rank-suite' ) : __( 'The focus keyword is not in the URL.', 'ai-rank-suite' ), __( 'Edit the permalink so it contains the keyword. Change it before the page has links — a slug change on an established page costs the rankings it already has unless you redirect it.', 'ai-rank-suite' ) ); // The opening is what a reader and an extractive model both weight // heaviest; a keyword that first appears in paragraph nine is a keyword // the page is not really about. $opening = mb_substr( $low, 0, max( 200, (int) ( mb_strlen( $low ) * 0.1 ) ) ); $in_open = str_contains( $opening, $kw ); $out[] = self::make( 'kw_early', 'seo', 'basics', $in_open ? 'pass' : 'warn', 3, $in_open ? __( 'The focus keyword appears in the first 10% of the content.', 'ai-rank-suite' ) : __( 'The focus keyword does not appear in the opening.', 'ai-rank-suite' ), __( 'Work the phrase into the first paragraph. This is the passage an assistant quotes when it answers with your page.', 'ai-rank-suite' ), true ); // --- Content ------------------------------------------------------ $count = self::count_occurrences( $low, $kw ); $density = $words > 0 ? round( $count / $words * 100, 2 ) : 0.0; $ok = $density >= 0.4 && $density <= 2.5; $out[] = self::make( 'kw_density', 'seo', 'content', $count === 0 ? 'fail' : ( $ok ? 'pass' : 'warn' ), 3, sprintf( /* translators: 1: density percentage, 2: occurrence count, 3: word count. */ __( 'Keyword density is %1$s%% — the phrase appears %2$d times in %3$d words.', 'ai-rank-suite' ), number_format_i18n( $density, 2 ), $count, $words ), $density > 2.5 ? __( 'That is high enough to read as repetition. Replace some instances with a synonym or a pronoun — the meaning carries, the padding does not.', 'ai-rank-suite' ) : __( 'Aim for roughly 0.5–2.5%. Below that the page reads as being about something else; the fix is usually one more natural mention in a subheading and one in the body.', 'ai-rank-suite' ), true ); $in_heading = false; foreach ( $headings as $heading ) { // [level, text] as Html::headings() gives; a bare string is accepted too. $text = is_array( $heading ) ? (string) ( $heading[1] ?? '' ) : (string) $heading; if ( str_contains( self::lower( $text ), $kw ) ) { $in_heading = true; break; } } $out[] = self::make( 'kw_subheading', 'seo', 'content', $in_heading ? 'pass' : 'warn', 2, $in_heading ? __( 'The focus keyword is used in a subheading.', 'ai-rank-suite' ) : __( 'The focus keyword is in no subheading.', 'ai-rank-suite' ), __( 'Put it in one H2. Assistants chunk pages by heading, so a heading is the label on the chunk they retrieve.', 'ai-rank-suite' ), true ); // --- Title & snippet --------------------------------------------- $title = self::lower( \AiRankSuite\Modules\Seo\SeoModule::resolve_title( $post ) ); $pos = mb_strpos( $title, $kw ); $out[] = self::make( 'kw_title_start', 'seo', 'title', false === $pos ? 'fail' : ( $pos <= max( 12, (int) ( mb_strlen( $title ) * 0.35 ) ) ? 'pass' : 'warn' ), 3, false === $pos ? __( 'The focus keyword is missing from the SEO title.', 'ai-rank-suite' ) : ( $pos <= max( 12, (int) ( mb_strlen( $title ) * 0.35 ) ) ? __( 'The focus keyword is near the start of the SEO title.', 'ai-rank-suite' ) : __( 'The focus keyword is in the title, but late.', 'ai-rank-suite' ) ), __( 'A title is truncated from the right and read from the left. The earlier the phrase, the more of it survives both.', 'ai-rank-suite' ), true ); // --- Links & media ------------------------------------------------ $alts = Html::images_alt( $html ); $alt_hit = false; foreach ( $alts as $alt ) { if ( is_array( $alt ) ) { $alt = (string) ( $alt['alt'] ?? '' ); } if ( '' !== (string) $alt && str_contains( self::lower( (string) $alt ), $kw ) ) { $alt_hit = true; break; } } $out[] = self::make( 'kw_image_alt', 'seo', 'links', empty( $alts ) ? 'warn' : ( $alt_hit ? 'pass' : 'warn' ), 1, empty( $alts ) ? __( 'No image on the page to carry the keyword in its alt text.', 'ai-rank-suite' ) : ( $alt_hit ? __( 'An image uses the focus keyword in its alt text.', 'ai-rank-suite' ) : __( 'No image alt text contains the focus keyword.', 'ai-rank-suite' ) ), __( 'Alt text is the only description of an image a search engine reads, and image results are a second way onto the page.', 'ai-rank-suite' ) ); // --- Technical ----------------------------------------------------- $used = self::keyword_used_elsewhere( $keyword, $post->ID ); $out[] = self::make( 'kw_unique', 'seo', 'technical', $used > 0 ? 'warn' : 'pass', 2, $used > 0 ? sprintf( /* translators: %d: number of other pages. */ _n( 'This focus keyword is also set on %d other page.', 'This focus keyword is also set on %d other pages.', $used, 'ai-rank-suite' ), $used ) : __( 'This focus keyword is not used on any other page.', 'ai-rank-suite' ), __( 'Two pages aiming at one phrase compete with each other, and the engine picks — usually the weaker one. Give each page its own angle, or merge them.', 'ai-rank-suite' ) ); return $out; } /** * Checks that need no keyword. * * @param array $headings Headings. * @param array $paragraphs Paragraphs. * @return array> */ public static function general( WP_Post $post, string $html, int $words, array $headings, array $paragraphs ): array { $out = self::cornerstone( $post ); // --- Title & snippet --------------------------------------------- $title = \AiRankSuite\Modules\Seo\SeoModule::resolve_title( $post ); $title_low = self::lower( $title ); $has_number = (bool) preg_match( '/\d/', $title ); $out[] = self::make( 'title_number', 'seo', 'title', $has_number ? 'pass' : 'warn', 1, $has_number ? __( 'The SEO title contains a number.', 'ai-rank-suite' ) : __( 'The SEO title contains no number.', 'ai-rank-suite' ), __( 'A number sets an expectation of scope — "7 Schritte", "2026", "in 10 Minuten". It is the cheapest way to make a title concrete.', 'ai-rank-suite' ), true ); $sentiment = self::contains_any( $title_low, self::sentiment_words() ); $out[] = self::make( 'title_sentiment', 'seo', 'title', $sentiment ? 'pass' : 'warn', 1, $sentiment ? __( 'The SEO title carries a positive or negative word.', 'ai-rank-suite' ) : __( 'The SEO title is emotionally flat.', 'ai-rank-suite' ), __( 'A title that promises something good or warns of something bad earns more clicks than one that only describes. This is about the click, not the ranking.', 'ai-rank-suite' ), true ); $power = self::contains_any( $title_low, self::power_words() ); $out[] = self::make( 'title_power', 'seo', 'title', $power ? 'pass' : 'warn', 1, $power ? __( 'The SEO title contains a power word.', 'ai-rank-suite' ) : __( 'The SEO title contains no power word.', 'ai-rank-suite' ), __( 'Words like "Anleitung", "Vergleich", "endlich" or "Checkliste" tell a reader what kind of page this is before they open it.', 'ai-rank-suite' ), true ); $url_len = mb_strlen( (string) wp_parse_url( (string) get_permalink( $post ), PHP_URL_PATH ) ); $out[] = self::make( 'url_length', 'seo', 'technical', $url_len <= 75 ? 'pass' : 'warn', 1, sprintf( /* translators: %d: URL length in characters. */ __( 'The URL path is %d characters long.', 'ai-rank-suite' ), $url_len ), __( 'Under about 75 characters. A long URL is truncated in results, is harder to share, and usually means the slug repeats words the folder already says.', 'ai-rank-suite' ) ); // --- Content ------------------------------------------------------ $long = 0; foreach ( $paragraphs as $paragraph ) { if ( str_word_count( wp_strip_all_tags( (string) $paragraph ) ) > 120 ) { ++$long; } } $out[] = self::make( 'short_paragraphs', 'geo', 'content', 0 === $long ? 'pass' : ( $long > 3 ? 'fail' : 'warn' ), 2, 0 === $long ? __( 'Paragraphs are short enough to scan.', 'ai-rank-suite' ) : sprintf( /* translators: %d: number of long paragraphs. */ _n( '%d paragraph runs past 120 words.', '%d paragraphs run past 120 words.', $long, 'ai-rank-suite' ), $long ), __( 'Break them. A wall of text is skipped by readers and retrieved badly by assistants, which quote in passages rather than in pages.', 'ai-rank-suite' ) ); $has_media = (bool) preg_match( '/<(img|video|iframe|figure)\b/i', $html ); $out[] = self::make( 'has_media', 'geo', 'links', $has_media ? 'pass' : 'warn', 1, $has_media ? __( 'The page contains an image or a video.', 'ai-rank-suite' ) : __( 'The page is text only.', 'ai-rank-suite' ), __( 'One relevant image gives the page a thumbnail in results and a second route in through image search.', 'ai-rank-suite' ) ); // A table of contents is what turns a long page into an answerable one: // it gives every section a stable anchor an assistant can cite. $anchor_count = preg_match_all( '/]*\bid\s*=/i', $html ); $has_toc = $anchor_count >= 3 || (bool) preg_match( '/class="[^"]*\b(toc|table-of-contents|ez-toc)\b/i', $html ); // A three-heading page does not need a table of contents, so the check // passes quietly rather than nagging. The label has to agree with the // status it is shown next to — "no table of contents" beside a green // tick is the kind of thing that makes people distrust every other row. $toc_needed = count( $headings ) >= 5; $out[] = self::make( 'has_toc', 'geo', 'content', $has_toc || ! $toc_needed ? 'pass' : 'warn', 1, $has_toc ? __( 'The page has anchored sections a reader can jump to.', 'ai-rank-suite' ) : ( $toc_needed ? __( 'A long page with no table of contents or heading anchors.', 'ai-rank-suite' ) : __( 'Short enough not to need a table of contents.', 'ai-rank-suite' ) ), __( 'Anchored headings let an assistant link to the exact section that answers a question instead of to the top of the page.', 'ai-rank-suite' ) ); // --- Links -------------------------------------------------------- $anchors = self::anchors( $html ); $home = (string) wp_parse_url( home_url(), PHP_URL_HOST ); $external = 0; $ext_follow = 0; $internal = 0; foreach ( $anchors as $anchor ) { $host = (string) wp_parse_url( $anchor['href'], PHP_URL_HOST ); if ( '' === $host || $host === $home ) { if ( ! str_starts_with( $anchor['href'], '#' ) ) { ++$internal; } continue; } ++$external; if ( ! $anchor['nofollow'] ) { ++$ext_follow; } } $out[] = self::make( 'internal_links', 'seo', 'links', $internal > 0 ? 'pass' : 'warn', 2, $internal > 0 ? sprintf( /* translators: %d: number of internal links. */ _n( '%d internal link in the content.', '%d internal links in the content.', $internal, 'ai-rank-suite' ), $internal ) : __( 'No internal links in the content.', 'ai-rank-suite' ), __( 'Link to your own related pages. It is how a crawler finds them, how a reader stays, and how you tell an engine which of your pages belong together.', 'ai-rank-suite' ) ); $out[] = self::make( 'external_links', 'geo', 'links', $external > 0 ? 'pass' : 'warn', 1, $external > 0 ? sprintf( /* translators: %d: number of outbound links. */ _n( '%d link out to another site.', '%d links out to other sites.', $external, 'ai-rank-suite' ), $external ) : __( 'The page cites no external source.', 'ai-rank-suite' ), __( 'Citing a source is one of the strongest quality signals there is — for Google, and for an assistant deciding whether a page is worth quoting.', 'ai-rank-suite' ) ); if ( $external > 0 ) { $out[] = self::make( 'external_dofollow', 'seo', 'links', $ext_follow > 0 ? 'pass' : 'warn', 1, $ext_follow > 0 ? __( 'At least one outbound link is followed.', 'ai-rank-suite' ) : __( 'Every outbound link on this page is nofollow.', 'ai-rank-suite' ), __( 'Nofollow on every source reads as an attempt to hoard link equity. Follow the sources you actually vouch for.', 'ai-rank-suite' ) ); } return $out; } /** * How many other posts carry this exact focus keyword. * * Reads the flat `_airanksuite_focus_keyword` mirror rather than the serialised * array, which is exactly why that mirror is kept in sync. */ private static function keyword_used_elsewhere( string $keyword, int $post_id ): int { global $wpdb; // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching return (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM {$wpdb->postmeta} pm INNER JOIN {$wpdb->posts} p ON p.ID = pm.post_id WHERE pm.meta_key = '_airanksuite_focus_keyword' AND pm.meta_value = %s AND pm.post_id != %d AND p.post_status = 'publish'", $keyword, $post_id ) ); } /** * @return array */ private static function anchors( string $html ): array { $out = array(); if ( ! preg_match_all( '/]*)>/i', $html, $matches ) ) { return $out; } foreach ( $matches[1] as $attributes ) { if ( ! preg_match( '/href\s*=\s*("([^"]*)"|\'([^\']*)\')/i', (string) $attributes, $href ) ) { continue; } $rel = ''; if ( preg_match( '/rel\s*=\s*("([^"]*)"|\'([^\']*)\')/i', (string) $attributes, $rel_match ) ) { $rel = '' !== ( $rel_match[2] ?? '' ) ? $rel_match[2] : ( $rel_match[3] ?? '' ); } $out[] = array( 'href' => '' !== ( $href[2] ?? '' ) ? $href[2] : ( $href[3] ?? '' ), 'nofollow' => false !== stripos( $rel, 'nofollow' ), ); } return $out; } /** * @param array $needles Words to look for. */ private static function contains_any( string $haystack, array $needles ): bool { foreach ( $needles as $needle ) { // Word boundary on both sides so "neu" does not match "neutral" // and "top" does not match "Optometrist". if ( preg_match( '/(?> */ public static function cornerstone( WP_Post $post ): array { if ( ! get_post_meta( $post->ID, '_airanksuite_cornerstone', true ) ) { return array(); } $in = (int) get_post_meta( $post->ID, '_airanksuite_links_in', true ); $target = (int) apply_filters( 'airanksuite/checks/cornerstone_links', 3, $post ); return array( self::make( 'cornerstone_links', 'seo', 'links', $in >= $target ? 'pass' : ( $in > 0 ? 'warn' : 'fail' ), 3, sprintf( /* translators: 1: number of pages linking here, 2: how many a cornerstone page should have. */ _n( '%1$d page links to this cornerstone page; aim for %2$d.', '%1$d pages link to this cornerstone page; aim for %2$d.', $in, 'ai-rank-suite' ), $in, $target ), $in >= $target ? '' : __( 'Link to it from the posts that cover the same subject in less depth. A page you have called central should be the one the rest of the site points at.', 'ai-rank-suite' ) ), ); } /** * How hard the page is to read — the checks a customer coming from Yoast * or Rank Math looks for first, phrased the way the rest of this catalogue * is: the number, then what to do about it. * * @param WP_Post $post Post. * @param string $html Rendered content. * @return array> */ public static function readability( WP_Post $post, string $html ): array { $language = \AiRankSuite\Support\Multilingual::post_language( (int) $post->ID ); $score = Readability::score( \AiRankSuite\Support\Html::text( $html ), $language ); $out = array(); if ( 0 === $score['sentences'] ) { return array( self::make( 'read_flesch', 'seo', 'readability', 'warn', 2, __( 'There is no prose to measure yet.', 'ai-rank-suite' ), __( 'Readability is scored from sentences. Add the copy and the numbers appear here.', 'ai-rank-suite' ) ), ); } // Reading ease. 60 is the line most style guides draw for the web: // comfortable for a general audience, and a page below 30 is one most // readers give up on rather than argue with. $flesch = (int) $score['flesch']; $out[] = self::make( 'read_flesch', 'seo', 'readability', $flesch >= 60 ? 'pass' : ( $flesch >= 30 ? 'warn' : 'fail' ), 3, sprintf( /* translators: 1: reading-ease score 0-100, 2: word for how hard it reads, 3: school grade level. */ __( 'Reading ease %1$d of 100 — %2$s, about school grade %3$s.', 'ai-rank-suite' ), $flesch, Readability::label( $flesch ), number_format_i18n( (float) $score['grade'], 1 ) ), $flesch >= 60 ? '' : __( 'Shorten the sentences and prefer the shorter of two words. Reading ease rises fastest when a long sentence becomes two.', 'ai-rank-suite' ) ); // Sentence length. $long_share = (int) $score['long_share']; $out[] = self::make( 'read_sentences', 'seo', 'readability', $long_share <= 25 ? 'pass' : ( $long_share <= 40 ? 'warn' : 'fail' ), 2, sprintf( /* translators: 1: number of long sentences, 2: total sentences, 3: percentage, 4: average words per sentence. */ __( '%1$s of %2$s sentences run past 20 words (%3$s%%), averaging %4$s words.', 'ai-rank-suite' ), number_format_i18n( (int) $score['long_sentences'] ), number_format_i18n( (int) $score['sentences'] ), number_format_i18n( $long_share ), number_format_i18n( (float) $score['words_per_sentence'], 1 ) ), $long_share <= 25 ? '' : __( 'Aim for a quarter at most. The usual fix is a full stop where a comma is doing too much work.', 'ai-rank-suite' ) ); // Paragraph length. $out[] = self::make( 'read_paragraphs', 'seo', 'readability', 0 === (int) $score['long_paragraphs'] ? 'pass' : 'warn', 1, sprintf( /* translators: 1: number of long paragraphs, 2: total paragraphs. */ __( '%1$s of %2$s paragraphs run past 150 words.', 'ai-rank-suite' ), number_format_i18n( (int) $score['long_paragraphs'] ), number_format_i18n( (int) $score['paragraphs'] ) ), 0 === (int) $score['long_paragraphs'] ? '' : __( 'Break them where the thought turns. On a phone a 150-word paragraph is most of the screen.', 'ai-rank-suite' ) ); // Passive voice. $passive_share = (int) $score['passive_share']; $out[] = self::make( 'read_passive', 'seo', 'readability', $passive_share <= 10 ? 'pass' : ( $passive_share <= 20 ? 'warn' : 'fail' ), 2, sprintf( /* translators: 1: number of passive sentences, 2: percentage. */ __( '%1$s sentences are passive (%2$s%%).', 'ai-rank-suite' ), number_format_i18n( (int) $score['passive'] ), number_format_i18n( $passive_share ) ), $passive_share <= 10 ? '' : __( 'Name who does the thing: “we roast the beans”, not “the beans are roasted”. Ten per cent is the usual ceiling.', 'ai-rank-suite' ) ); // Transition words. $transition_share = (int) $score['transition_share']; $out[] = self::make( 'read_transitions', 'seo', 'readability', $transition_share >= 30 ? 'pass' : ( $transition_share >= 20 ? 'warn' : 'fail' ), 1, sprintf( /* translators: 1: percentage of sentences with a transition word. */ __( '%1$s%% of sentences use a transition word.', 'ai-rank-suite' ), number_format_i18n( $transition_share ) ), $transition_share >= 30 ? '' : __( 'Words like “however”, “because” and “for example” tell the reader how one sentence follows from the last. Thirty per cent reads as a train of thought rather than a list.', 'ai-rank-suite' ) ); return $out; } /** * @return array */ private static function make( string $id, string $group, string $section, string $status, int $weight, string $label, string $fix = '', bool $ai = false ): array { return compact( 'id', 'group', 'section', 'status', 'weight', 'label', 'fix', 'ai' ); } }