AI Content for Magento 2: User Guide

AI Content Generator writes product, category and CMS page texts from your own catalogue data: descriptions, short descriptions, meta titles, meta descriptions, meta keywords, image alt texts and drafts of CMS page content. It writes per store view and in the store view's language, keeps every text in a review queue until you approve it (bulk jobs), shows the cost before a bulk job starts and can put back every text it replaced.

Requirements

Installation

The module is installed with Composer from the CommerceGears repository (see https://commercegears.com/composer-access/ for the access keys):

composer require commercegears/module-ai-content
bin/magento module:enable CommerceGears_Core CommerceGears_AiCore CommerceGears_AiContent
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

Magento cron must run: bulk jobs are processed by cron every minute.

First steps

1. Stores > Configuration > CommerceGears > AI > AI Providers & Costs: enter your Anthropic or OpenAI API key, choose the default model and, if you like, a monthly or daily budget for all AI modules. These settings are shared by all CommerceGears AI modules.
2. Stores > Configuration > CommerceGears > AI > AI Content Generator: check the language, tone and brand voice per store view (see below). The defaults work for most shops.
3. Open a product (Catalog > Products), click Generate with AI under the Meta Description field and apply the result. Then try a bulk job for a few products.

Settings

Stores > Configuration > CommerceGears > AI > AI Content Generator, also CommerceGears > AI Content Generator > Settings.

General

• Enabled: switches the Generate with AI buttons, the grid mass actions and bulk jobs on or off. Texts already applied stay.
• Model: the model for texts and translations. "Default Model" uses the default of AI Providers & Costs. Larger models write better long texts; smaller models are cheaper for meta data in bulk.
• Model for Image Alt Text: a model that reads images (vision). "Default Model" uses the model above.
• Items per Run: how many products, categories or pages (per store view) a cron run processes for bulk jobs. Default 10.
• AI Cost: this module's AI spending this month and today, its limits and the shared budget.

Language and Style (per store view)

Switch the scope (top left) to a store view to set these for that store view.

• Output Language: by default the locale of the store view (General > Locale Options), so a German store view gets German texts. Choose a language here to override it.
• Tone of Voice: clear and informative, warm and friendly, professional, premium and understated, light and playful, or technical.
• Text Length: short, medium or long. It guides descriptions and CMS drafts, for example 60 to 100, 120 to 200 or 250 to 400 words for a product description.
• Brand Voice: your house style, sent with every request, up to 3,000 characters. Example: "We are a family-run outdoor shop. Speak to the reader as you. Mention sustainability only where the data supports it."
• Words to Avoid: words and phrases the texts must not contain, comma-separated or one per line.
• Meta Title: Maximum Characters (60), Meta Description: Maximum Characters (160), Meta Keywords: Maximum Number (8). Longer answers are shortened at a word boundary.

Product Data

• Attributes in {{attributes}}: the attributes listed as "Label: value" in the prompt. With none selected, every attribute set to "Visible on Catalog Pages on Storefront" is used. Never select attributes with data you do not want to share with the AI provider.
• Brand Attribute: the attribute used for {{brand}}, for example "manufacturer".

Prompt Templates

There is one group for products, categories and CMS pages. Each has a Shop Data template, the facts sent once per request, and one template per field with the instructions for that field. Templates can differ per store view; "Use Default" brings back the shipped template.

Variables:

• Products: {{name}}, {{sku}}, {{type}}, {{brand}}, {{category}}, {{categories}}, {{attributes}}, {{options}} (configurable options, e.g. "Colour: Black, Blue; Size: S, M"), {{price}}, {{description}}, {{short_description}}, {{meta_title}}, {{meta_description}}, {{meta_keyword}}, {{url_key}}.
• Categories: {{name}}, {{path}}, {{parent}}, {{products}} (up to 15 product names in category order), {{product_count}}, {{description}}, {{meta_title}}, {{meta_description}}, {{meta_keywords}}, {{url_key}}.
• CMS pages: {{title}}, {{content_heading}}, {{content}}, {{url_key}}, {{meta_title}}, {{meta_description}}, {{meta_keywords}}. E-mail addresses, phone numbers and similar data in the page content are masked before they are sent.
• All: {{store_name}}, {{store_view}}, {{language}}.

A template line whose variables are all empty is left out, so "Brand: {{brand}}" disappears for products without a brand. Format and length rules for each field (allowed HTML, character limits) are added automatically, and every request tells the AI to use only the facts it is given.

Generate with AI in the edit forms

Product, category and CMS page edit pages show a Generate with AI button under each supported field:

• Products: Description, Short Description, Meta Title, Meta Description, Meta Keywords, and Generate Alt Texts with AI above the images (Images And Videos).
• Categories: Description, Meta Title, Meta Description, Meta Keywords.
• CMS pages: Meta Title, Meta Description, Meta Keywords and Content (as a draft).

The buttons appear once the entity has been saved. The text is written for the store view selected in the scope switcher of the page (a CMS page: the language of its store view).

In the dialog:

1. Choose What to do: write a new text, improve the current text, or translate from another store view.
2. Optionally add Extra instructions, for example "mention that it is machine washable".
3. Click Generate. The current and the generated text are shown side by side, with a preview for HTML and the model and cost of the request. You can edit the generated text.
4. Choose:

• Apply: saves the text for the store view now. If the field already has a text, you confirm first. The previous text is kept in History. The form field shows the new text, so saving the form later keeps it.
• Generate Again: a new attempt (the previous one is discarded).
• Send to Review Queue: decide later, or let a colleague decide.
• Discard: nothing is saved.

When a store view used the default value ("Use Default Value" ticked), applying saves a text for this store view only. Revert in History restores the default value again.

For image alt texts the dialog lists each image with its current and generated alt text. Up to 10 images per product are sent with the request.

Bulk jobs

Bulk jobs write texts for many items by cron.

• Products: Catalog > Products, select products (filters work too), Actions > Generate AI Content.
• CMS pages: Content > Pages, select pages, Actions > Generate AI Content.
• Categories: CommerceGears > AI Content Generator > Bulk Jobs > New Category Job, then select the categories.

On the job page choose:

• Fields to write.
• Store Views (products and categories). Each store view gets its own text in its language. "Default Values" is what store views without their own text show. CMS pages are written in the language of their own store view.
• Task: write new texts, improve the current texts (empty fields are written new), or translate from a store view.
• Existing Texts: "Only fill empty fields" is on by default. For translations it means: only store views without their own text.
• Result: the review queue (default, nothing changes until you approve) or apply directly (every change can be reverted in History).
• Extra Instructions for this job and an optional Stop at a Cost of (USD).

Click Save and Estimate Cost. The estimate uses the price list of AI Providers & Costs and the first items of the selection; texts that already exist are skipped and cost nothing. Then click Start Job.

The Bulk Jobs grid shows progress, generated, skipped and failed fields, cost and estimate. Cron processes the configured number of items per minute; Run Next Batch Now processes a few items straight away. A job pauses when the monthly or daily AI budget is used up, when no provider is set up, or when the provider reports an error; it continues with the next cron run and fails after 5 runs in a row with provider errors. Cancel stops a job; texts generated so far stay.

Review queue

CommerceGears > AI Content Generator > Review Queue lists the texts waiting for a decision, with the item, store view, field and the start of the text. Search by name or text, filter by type, store view and field.

• Review opens the text next to the current one. Edit it, then Approve and Apply, Save Edits, Generate Again or Reject. After a decision the next text opens.
• Mass actions: Approve and Apply and Reject for the selected texts.

History and revert

CommerceGears > AI Content Generator > History lists every applied, rejected, reverted and failed text with the previous value, who decided and when. Revert puts back the previous value, including "Use Default Value" for a store view. Only the newest applied text of a field can be reverted; revert newer ones first. Failed texts show the reason (for example an answer that did not match the expected format).

Output and storage

• HTML fields keep only paragraphs, headings (h2 to h4), lists, bold, italic and line breaks, without attributes. Scripts, styles, links and images are removed.
• Magento template directives such as {{block ...}}, {{widget ...}} or {{config ...}} are removed from every generated or edited text, so a text cannot pull blocks, widgets or settings into your pages. Add them in the normal editor if you need them.
• Meta fields are plain text within the configured limits; keywords are a clean, comma-separated list.
• When Magento Page Builder edits a field, the generated text is saved as one Page Builder text element and replaces the previous content of the field (which stays in History).
• Values are saved for exactly the chosen store view; caches of the item are cleaned.

Costs and budget

Every request is recorded in CommerceGears > AI Services > Usage & Costs (module "AI Content Generator", features content_text, image_alt_text and content_translation). The shared monthly and daily budget and the module limits of AI Providers & Costs are checked before each request.

Command line

bin/magento commercegears:ai-content:generate product --category=12 --fields=meta_description --stores=1,2
bin/magento commercegears:ai-content:generate category --all --fields=description --stores=0 --estimate
bin/magento commercegears:ai-content:generate product --ids=5,6 --mode=translate --source-store=1 --stores=2 --apply --yes
bin/magento commercegears:ai-content:jobs
bin/magento commercegears:ai-content:process --job=12
bin/magento commercegears:ai-content:revert 345 346

generate selects items with --ids, --all or --category (products), shows the estimate and asks before it starts. Options: --fields, --stores (0 = default values), --mode, --source-store, --overwrite (also replace filled fields), --apply (instead of the review queue), --instructions, --max-cost, --estimate (estimate only), --yes (no question), --run (process now instead of by cron).

Permissions

System > Permissions > User Roles > Role Resources > CommerceGears > AI Content Generator:

• Generate in Edit Forms: the Generate with AI buttons.
• Bulk Jobs: the grid mass actions and the Bulk Jobs page.
• Review Queue (Approve and Reject).
• History and Revert.
• Settings.

Changing a product, category or page also needs Magento's own permission for it (Catalog > Products, Catalog > Categories, Content > Pages).

Troubleshooting

• No Generate with AI buttons: check that the module is enabled, the role has "Generate in Edit Forms" and the item has been saved once.
• "Waiting for the AI budget" on a job: the monthly or daily budget of AI Providers & Costs is used up. The job continues when there is budget again, or raise the budget.
• Provider error: the message comes from AI Core (for example a wrong API key or an overloaded provider). Jobs retry with the next cron run.
• The model cannot read images: choose a vision model under Model for Image Alt Text.
• Texts in the wrong language: check Output Language and the locale of the store view.
• Jobs do not move: check that Magento cron runs (commercegears_aicontent_process_jobs), or use Run Next Batch Now.

Uninstall

bin/magento module:disable CommerceGears_AiContent
composer remove commercegears/module-ai-content
bin/magento setup:upgrade

Texts that were applied stay in your catalogue. The history tables commercegears_aicontent_job and commercegears_aicontent_draft are not used by anything else; drop them after removing the module if you do not want to keep the history.