post_content, $post ); $excerpt = wp_trim_words( wp_strip_all_tags( $content ), 150 ); switch ( $field ) { case 'title': $prompt = sprintf( /* translators: 1: post title, 2: site name, 3: post content excerpt */ __( 'Write a concise, compelling SEO title (max 60 characters) for the article titled "%1$s" on the site "%2$s". Article content: %3$s. Return only the title, with no quotation marks or extra commentary.', 'acez-seo' ), $title, $site_name, $excerpt ); break; case 'description': $prompt = sprintf( /* translators: 1: post title, 2: post content excerpt */ __( 'Write a concise, engaging SEO meta description (max 155 characters) for the article titled "%1$s". Article content: %2$s. Return only the description, with no quotation marks or extra commentary.', 'acez-seo' ), $title, $excerpt ); break; case 'product_description': $prompt = sprintf( /* translators: 1: product title, 2: site name, 3: product content excerpt */ __( 'Write a concise, sales-oriented description of the product "%1$s" from the shop "%2$s" (max 155 characters), suitable as a meta description and the schema.org description property. Product copy from the page: %3$s. Return only the description, with no quotation marks or extra commentary.', 'acez-seo' ), $title, $site_name, $excerpt ); break; case 'keyword': $prompt = sprintf( /* translators: 1: post title, 2: post content excerpt */ __( 'Based on the article titled "%1$s", suggest ONE single, best-fitting SEO keyphrase (2-4 words) this article should rank for. Article content: %2$s. Return ONLY the keyphrase itself, in lowercase, with no quotation marks, no trailing period, and no additional commentary.', 'acez-seo' ), $title, $excerpt ); break; case 'schema_faq': $prompt = sprintf( /* translators: 1: post title, 2: post content excerpt */ __( 'Based on the article titled "%1$s", propose 3-5 question-and-answer pairs a reader might ask. Article content: %2$s. Return ONLY a valid schema.org FAQPage JSON node, in the language of the article, exactly in the format: {"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"question","acceptedAnswer":{"@type":"Answer","text":"answer"}}]} — no markdown blocks, no comments, no text before or after the JSON.', 'acez-seo' ), $title, $excerpt ); break; case 'schema_howto': $prompt = sprintf( /* translators: 1: post title, 2: post content excerpt */ __( 'Based on the article titled "%1$s", describe a step-by-step guide. Article content: %2$s. Return ONLY a valid schema.org HowTo JSON node, in the language of the article, exactly in the format: {"@type":"HowTo","name":"guide name","step":[{"@type":"HowToStep","text":"step text"}]} — no markdown blocks, no comments, no text before or after the JSON.', 'acez-seo' ), $title, $excerpt ); break; default: $prompt = sprintf( /* translators: %s: post title */ __( 'Write a short SEO text for the article titled "%s".', 'acez-seo' ), $title ); } $prompt = self::append_user_context( $prompt, self::user_context_for_field( $field, $post ) ); $prompt = self::append_search_intent( $prompt, $field, $post ); /** * Filters the prompt sent to the AI provider for a given field. * * @param string $prompt * @param string $field 'title', 'description', or a custom key. * @param \WP_Post $post */ return (string) apply_filters( 'acez_seo_ai_prompt', $prompt, $field, $post ); } /** * Optional user-supplied extra instructions (own meta fields, one for * schema nodes and one shared by title/description/product_description/ * keyword — user decision 2026-07-14: broadened from "keyword only" to * a general text-fields context field, positioned above the Title field * in both editors) — empty by default, never changes the prompt when * left blank. */ private static function user_context_for_field( string $field, \WP_Post $post ): string { if ( in_array( $field, array( 'schema_faq', 'schema_howto' ), true ) ) { $meta_key = \AcezSeo\Data\MetaFields::AI_CONTEXT_SCHEMA; } elseif ( in_array( $field, array( 'title', 'description', 'product_description', 'keyword' ), true ) ) { $meta_key = \AcezSeo\Data\MetaFields::AI_CONTEXT_KEYWORD; } else { return ''; } return trim( (string) get_post_meta( $post->ID, $meta_key, true ) ); } private static function append_user_context( string $prompt, string $context ): string { if ( '' === $context ) { return $prompt; } return $prompt . ' ' . sprintf( /* translators: %s: user-provided extra instructions */ __( 'Additional instructions from the user (treat as priority): %s', 'acez-seo' ), $context ); } /** * M64 — user-DECLARED search intent (never auto-detected from the * keyword — that's what a paid, external analysis service would do; * this costs nothing because the human already knows why they're * writing the piece). Empty/unset = prompt unchanged, exactly like * append_user_context() above. */ private static function append_search_intent( string $prompt, string $field, \WP_Post $post ): string { if ( ! in_array( $field, array( 'title', 'description', 'product_description', 'keyword', 'article' ), true ) ) { return $prompt; } $intent = (string) get_post_meta( $post->ID, \AcezSeo\Data\MetaFields::SEARCH_INTENT, true ); $guidance = self::search_intent_guidance( $intent ); return '' === $guidance ? $prompt : $prompt . ' ' . $guidance; } private static function search_intent_guidance( string $intent ): string { switch ( $intent ) { case 'informational': return __( 'Declared search intent: informational — the user wants to learn something. Write in an educational, explanatory style, answering the "what/how/why" question thoroughly.', 'acez-seo' ); case 'navigational': return __( 'Declared search intent: navigational — the user is looking for a specific brand/page. Emphasize the brand/company name and that this is the official, trustworthy source.', 'acez-seo' ); case 'commercial': return __( 'Declared search intent: commercial (comparison) — the user is comparing options before buying. Emphasize concrete advantages and arguments for why this is a good choice compared to alternatives.', 'acez-seo' ); case 'transactional': return __( 'Declared search intent: transactional — the user is ready to buy/act. Use action-oriented language (a call to action), emphasize ease, price, or availability.', 'acez-seo' ); default: return ''; } } /** * Full article generation (M62). Output is requested in Markdown — the * caller converts it to HTML (Classic Editor) or Gutenberg blocks * (Support\MarkdownConverter is the single choke point for that, same * "one place resolves it" doctrine as SchemaGraphBuilder's shortcode * resolution). 'page' mode grounds the article in the post's own * title/existing content/meta description; 'brief' mode treats the * user-supplied $brief as the actual topic, with the page only as * secondary context (title kept for tone/audience, existing content only * if there's something to build on). * * @param string $mode 'page' or 'brief' * @param string $length 'short' (~400 words), 'medium' (~800 words) or 'long' (~1500 words) */ public static function for_article( \WP_Post $post, string $mode, string $brief, string $length ): string { $title = get_the_title( $post ); $word_targets = array( 'short' => __( 'about 400 words', 'acez-seo' ), 'medium' => __( 'about 800 words', 'acez-seo' ), 'long' => __( 'about 1500 words', 'acez-seo' ), ); $word_target = $word_targets[ $length ] ?? $word_targets['medium']; $content = (string) apply_filters( 'acez_seo_post_source_content', (string) $post->post_content, $post ); $excerpt = wp_trim_words( wp_strip_all_tags( $content ), 150 ); if ( 'brief' === $mode ) { $prompt = sprintf( /* translators: 1: user-supplied brief/topic, 2: post title (may be empty), 3: target word count */ __( 'Write a complete article (%3$s) on the topic described below. The user\'s topic/brief (treat as the main source of truth for what the article should cover): "%1$s". Title of the page the article will appear on (for tone/audience context only, not a fixed topic): "%2$s".', 'acez-seo' ), $brief, $title, $word_target ); } else { $prompt = sprintf( /* translators: 1: post title, 2: target word count, 3: existing content excerpt (may be empty) */ __( 'Write a complete article (%2$s) expanding on the topic of the page titled "%1$s". %3$s', 'acez-seo' ), $title, $word_target, '' !== trim( $excerpt ) /* translators: %s: excerpt of the post's existing content */ ? sprintf( __( 'The page already has the following, incomplete content — expand/continue it coherently, don\'t start from scratch: %s', 'acez-seo' ), $excerpt ) : __( 'The page has no content yet — write the article from scratch.', 'acez-seo' ) ); } $prompt .= ' ' . __( 'Return ONLY the article content in Markdown format: headings as "## "/"### ", bold as "**text**", italics as "*text*", lists as "- " or "1. ". Do not add the article\'s main title as a top-level heading (the page title is set separately) — start with the first paragraph or a "## " subheading. Do not add any comments before or after the content, including an introduction like "Here\'s the article:".', 'acez-seo' ); $prompt = self::append_user_context( $prompt, self::user_context_for_field( 'title', $post ) ); $prompt = self::append_search_intent( $prompt, 'article', $post ); /** @see PromptBuilder::for_field() for the filter signature */ return (string) apply_filters( 'acez_seo_ai_prompt', $prompt, 'article', $post ); } /** * Vision variant (M34): the model SEES the image, so the prompt asks for * a description of the actual content instead of guessing from the * filename. */ public static function for_alt_text_vision( int $attachment_id ): string { $caption = (string) wp_get_attachment_caption( $attachment_id ); $prompt = sprintf( /* translators: %s: optional caption clause */ __( 'Look at the attached image and write a short, descriptive alt text (alt attribute, max 125 characters) reflecting its actual content%s. Write in English, concretely, without phrases like "image shows". Reply with only the alt text, no quotation marks.', 'acez-seo' ), /* translators: %s: attachment caption */ '' !== $caption ? sprintf( __( ' (image caption: "%s")', 'acez-seo' ), $caption ) : '' ); /** @see PromptBuilder::for_field() for the filter signature */ return (string) apply_filters( 'acez_seo_ai_prompt', $prompt, 'alt_text_vision', $attachment_id ); } public static function for_alt_text( int $attachment_id ): string { $filename = basename( (string) get_attached_file( $attachment_id ) ); $caption = (string) wp_get_attachment_caption( $attachment_id ); $prompt = sprintf( /* translators: 1: image filename, 2: optional caption clause */ __( 'Write a short, descriptive alt text (max 125 characters) for an image with the filename "%1$s"%2$s. Reply with only the alt text, no quotation marks.', 'acez-seo' ), $filename, /* translators: %s: attachment caption */ '' !== $caption ? sprintf( __( ' with the caption "%s"', 'acez-seo' ), $caption ) : '' ); /** @see PromptBuilder::for_field() for the filter signature */ return (string) apply_filters( 'acez_seo_ai_prompt', $prompt, 'alt_text', $attachment_id ); } }