Sylius Media Alt Text: Configuration
Configuring the Sylius Media Alt Text plugin: the global switch in the admin, maintaining alt texts per image and language, decorative images and the backfill command with all its options.
Sylius Media Alt Text: Configuration
This documentation always describes the latest published version.
The plugin has no YAML configuration and reads no environment variables. There is exactly one setting, and it lives in the admin.
Setting in the admin
Admin sidebar > MMKreativ Plugins > Image Alt Texts, available at /admin/media-alt-text/settings (the prefix follows your configured admin path). Access is granted to anyone with ROLE_ADMINISTRATION_ACCESS.
| Setting | Default | Description |
|---|---|---|
| Output alt texts | on | Turns the output in the Storefront and Shop API on or off |
The setting applies to the whole shop, not per channel and not per language.
When the output is off:
- the Storefront and Shop API behave as they do without the plugin: images are described by the product or category name, and the Shop API omits
alt - the alt text fields disappear from the image forms in the admin
- the stored texts are kept and come back as soon as you turn the output on again
- the Admin API still accepts and returns alt texts
Headless clients read the state through GET /api/v2/shop/media-alt-text-settings, see Shop API.
Maintaining alt texts
Every product image, category image and admin avatar shows the alt text editor in its own image card:
- a Decorative image switch
- one collapsible section per enabled shop language; the default language comes first and starts expanded, as do sections with errors, and a language with text carries a "filled" badge
- each text is limited to 255 characters, leading and trailing whitespace is removed, and an empty language is not saved (an existing text for that language is deleted)
For taxons, the editor sits to the right of each image; for products, in every image card of the media section.
How a text is chosen
- Text in the requested language
- Text in the shop's default language
- The name of the product or category in the requested language, or failing that a name in another language (for avatars the first and last name, otherwise the username)
An image counts as decorative as soon as one of its rows is marked that way. In that case the alt text is empty (alt=""), and the fallback does not apply.
A decorative image without text stores an empty row in the default language, because the flag is attached to the row.
Backfill command
mmd:media-alt-text:backfill pre-fills missing texts with the product or category name, so editors have something to refine.
| Option | Default | Description |
|---|---|---|
--type, -t |
product, taxon |
Image type, can be given multiple times. Allowed values are product, taxon and avatar |
--locale, -l |
all enabled shop languages | Language, can be given multiple times |
--force |
off | Also replaces existing texts |
--dry-run |
off | Report only, write nothing |
bin/console mmd:media-alt-text:backfill --dry-run
bin/console mmd:media-alt-text:backfill --locale=de_DE --type=product
The command:
- fills a language only from a name written in exactly that language (no falling back to another language)
- leaves existing texts alone, unless you pass
--force - never touches images marked as decorative
- skips avatars unless you pass
--type=avatar - truncates names to 255 characters
- reports at the end how many images it checked, how many texts it created or replaced, and how many it left unchanged
- exits with an error message, without writing anything, if the type is unknown or the language is not enabled
A product name is a starting point for editors, not an image description. Review the generated texts before you rely on them.
Practical examples
New shop, maintaining texts gradually: Install the plugin and do nothing else. Images without text keep outputting the product name, and editors add texts as they edit the products.
Existing shop with many products: Do a dry run first, then fill only the default language:
bin/console mmd:media-alt-text:backfill --dry-run
bin/console mmd:media-alt-text:backfill --locale=de_DE
Temporarily hiding the plugin: Turn off the "Output alt texts" switch. Nothing is lost, the fields in the admin disappear and the shop behaves as before.