# AI Babel Enchanter Documentation

Installation steps and a complete reference for every setting, with concrete examples — the same level of detail our support uses to help customers. AI Babel Enchanter rewrites, improves and translates your Magento catalog at scale, driven by reusable profiles, with a dry-run preview and full rollback so nothing is a one-way door.

## Installation

### Requirements

Magento 2.4.x — tested on 2.4.9, compatible with previous 2.4.* releases. PHP 8.1–8.5. Compatible with both the default Luma theme and the Hyvä theme — the module works entirely in the admin and writes standard catalog attributes, so the storefront renders your improved content with no template changes. Depends on the free `codingrow/module-core` module, installed automatically. Requires an API key from at least one AI provider for the rewrite/improve step (Anthropic, OpenAI, Google or OpenRouter) and, for translation, either a machine-translation key (DeepL) or an LLM used as the translator. All AI and translation usage is billed to you directly by the provider — Codingrow never marks it up.

### Setup steps

1. Add the credentials you'll receive by email to `auth.json` in your Magento project root:
   ```json
   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
   ```
2. `composer config repositories.codingrow composer https://repo.codingrow.com`
3. `composer require codingrow/module-ai-babel-enchanter`
4. `bin/magento module:enable Codingrow_BabelEnchanter`
5. `bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush`
   (on a production deployment `setup:di:compile` is required; on a developer setup you can skip it)
6. Paste your license key into **Admin → Stores → Configuration → Codingrow → AI Babel Enchanter → License → License Key**, save, then flush the cache.

### Configuration

**Stores → Configuration → Codingrow → AI Babel Enchanter.**

| Setting | What it does | Default | Notes |
|---|---|---|---|
| **License Key** | The license key issued for this domain. | — | Accepts a single-module key or a Codingrow subscription key. Without a valid license the module does not run. |
| **Enable** | Master switch for the module. | No | Requires a valid license and at least one provider API key. |
| **Enhancement provider** | Which provider rewrites and improves the text (Anthropic, OpenAI, Google, OpenRouter), plus the model and API key. | — | Use the **Load models** button next to the Model field — see below. This is the improve/rewrite engine. |
| **Translation provider** | How target languages are produced: a machine-translation service (DeepL) or an LLM used as the translator, with its model and API key. | — | You can translate with the same LLM as the improve step, or with a dedicated MT key for lower per-character cost. |
| **SEO options** | Toggles for what gets generated: meta title, meta description, meta keywords, URL key, alongside the main content rewrite. | — | Turn off anything you don't want the module to touch. |
| **Resilience** | Circuit-breaker for provider credit/errors: **auto-retry** on transient failures, **cooldown hours** before retrying a paused queue, **pause after N errors** in a row. | — | Protects a long run from burning through the queue when the provider is out of credit or rate-limiting. |

### Uninstallation

Set **Enable** to **No** and save to stop all processing immediately. Your catalog content stays exactly as it is — use rollback first if you want to revert to the original text (see the User guide). To remove the module entirely: `bin/magento module:disable Codingrow_BabelEnchanter` then `composer remove codingrow/module-ai-babel-enchanter`.

## Choosing providers and getting API keys

AI Babel Enchanter has two independent provider slots: one for the **improve/rewrite** step (an LLM) and one for **translation** (an LLM or a dedicated machine-translation service). You bring your own keys, and all usage is billed to you directly by the provider you pick.

### Anthropic (Claude models)

1. Sign in at [console.anthropic.com](https://console.anthropic.com).
2. Go to **[console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)**.
3. Click **Create Key**, name it (e.g. "AI Babel Enchanter"), and copy the value.
4. Paste it into the provider slot with **Provider** set to Anthropic, then use **Load models**.

### OpenAI (GPT models)

1. Sign in at [platform.openai.com](https://platform.openai.com).
2. Go to **[platform.openai.com/api-keys](https://platform.openai.com/api-keys)**.
3. Click **Create new secret key**, name it, and copy it immediately — it is shown only once.
4. Paste it into the provider slot with **Provider** set to OpenAI, then use **Load models**.

### Google (Gemini models)

1. Sign in at [aistudio.google.com](https://aistudio.google.com) with a Google account.
2. Go to **[aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)**.
3. Click **Create API key**, choose or create a Google Cloud project, and copy the key.
4. Paste it into the provider slot with **Provider** set to Google, then use **Load models**.

### OpenRouter (one key, many providers' models)

1. Sign in at [openrouter.ai](https://openrouter.ai).
2. Go to **[openrouter.ai/keys](https://openrouter.ai/keys)**.
3. Click **Create Key**, name it, and copy the value.
4. Paste it into the provider slot with **Provider** set to OpenRouter, then use **Load models**.

### DeepL (machine translation)

1. Sign in at [deepl.com/pro-api](https://www.deepl.com/pro-api).
2. Open **Account → API keys** and copy your **Authentication Key**.
3. Paste it into the **Translation provider** slot with the translator set to DeepL. DeepL is priced per character (about €20 per 1M characters), which is usually cheaper than an LLM for straight translation. If you prefer, you can skip DeepL and translate with the same LLM as the improve step.

### Load models — no model id to type

After the API key is in place, save the section and click **Load models** under the Model field: the module calls the provider's own model-list endpoint with your key and fills a dropdown with every model your key can actually use — pick from the list instead of typing an id. A manual text input remains available as a fallback for a model id that isn't in the list yet. A link right below the field always points to the correct key page for whichever provider is currently selected.

### Estimating the cost of a full-catalog run

A full pass has two cost drivers that add up per product:

- **Improve** (LLM tokens): `improve = input_tokens / 1,000,000 × input_price + output_tokens / 1,000,000 × output_price`.
- **Translate** (characters): `translate = characters / 1,000,000 × char_price × number_of_languages`.

Per product, `cost = improve + translate`; for the whole catalog, multiply by the number of products. Prices below are indicative €/million.

| Improve model | Input €/M tok | Output €/M tok |
|---|---|---|
| Gemini 2.x Flash | ~0.09 | ~0.36 |
| OpenAI gpt-4o-mini | ~0.14 | ~0.55 |
| Claude Haiku 4.5 | ~0.90 | ~4.60 |
| Claude Sonnet 4.5 | ~2.80 | ~14.00 |

Translation with DeepL is about **€20 per 1M characters**. Example: 5,000 products, ~2,000 tokens/product on Claude Haiku 4.5, ~1,500 chars/product into 2 languages ≈ ~€20 improve + ~€300 translate for the whole catalog. These are purely indicative estimates — your real numbers depend on content length and the models you choose.

## User guide

### Profiles and persona prompt

Everything the module does is organized into **profiles**. A profile is a reusable configuration you can run against a slice of the catalog: which attributes it may touch, the pipeline of steps to apply, an optional **exclusive category** so the profile only ever operates on products in that category, and a **persona prompt** — free-text instructions that set the tone of voice and rules for the rewrite.

> **Example persona prompt:** "You write for a premium outdoor-gear store. Be concise and confident, lead with the benefit, use British English, never invent specifications, and keep every product description under 90 words."

Profiles are anti-revert: a product already processed by a profile is not re-processed on the next run unless you explicitly reset it, so re-running a profile is safe and only picks up new or reset products.

### Groups and steps (the pipeline)

Inside a profile you define **groups** of **steps** that run in order. The two core step types are **improve** (rewrite/enhance the source text with the enhancement provider) and **translate** (produce the target-language versions). The normal pipeline is **improve → translate**: the source language is rewritten first, then the improved text is what gets translated, so every store view inherits the better copy instead of translating the old text. Grouping lets you scope different steps to different attributes and run them as one operation.

### Cross-sell, related and up-sell (AI relations)

Three independent toggles let the profile propose **cross-sell**, **related** and **up-sell** products using the AI. The model only ever suggests **real SKUs from your catalog** — it cannot invent a product that doesn't exist — and the suggestions are written into Magento's native cross-sell/related/up-sell links, so they show up in the standard storefront blocks. Turn on only the relation types you want the module to manage.

### Dry-run preview (and rendered)

Before anything is written, run a profile in **dry-run**: the module generates the proposed content for a sample of products and shows it to you side by side with the current text, including a **rendered** preview so you see how the improved description will actually look on the page — not just raw text. Nothing is saved in dry-run; it's there to validate the persona prompt and the pipeline before you commit to a full run.

### "Enrichments & Translations" grid

The **"Enrichments & Translations"** tab is the working grid: every generated field for every product and language, paginated and filterable. You can **edit** any generated value inline before or after it is applied — the AI output is a starting point, not a lock — and each row keeps a link back to the **original** text so you can **restore the original** for that field with one action if you don't like the result. This is the human-in-the-loop layer over the automated pipeline.

### Rollback

Every value the module writes is reversible. Beyond per-row **restore original** in the grid, the `babel:rollback` CLI command reverts content in bulk — by profile, by product, or the whole run — back to the text that was in place before the module touched it. Because the original is always preserved, a full-catalog run is never a one-way door.

### Queue and credit circuit-breaker

Long runs are processed through a **queue** you can watch, pause and resume. The built-in **circuit-breaker** (configured under **Resilience**) protects the run: on repeated provider errors — most often the provider running out of credit or rate-limiting — it **pauses after N errors**, waits the configured **cooldown**, and can **auto-retry** transient failures instead of failing the whole batch. When you top up credit or the limit resets, resume the queue and it continues where it stopped.

### Command line (CLI)

| Command | What it does |
|---|---|
| `bin/magento babel:run` | Runs a profile (improve/translate pipeline) over its target products; the standard way to launch a full-catalog pass. |
| `bin/magento babel:rollback` | Reverts generated content back to the original text — scoped by profile, product, or the entire run. |
| `bin/magento babel:queue` | Inspects and controls the processing queue: status, pause, resume. |

---
© Codingrow (a brand of Revera SRLS). Sold worldwide. Licensed per domain.