Automatic Alternative Text
Automatically generates alternative text for images using Microsoft Azure Cognitive Services Computer Vision API when no alt text has been provided by the user.
auto_alter
Install
composer require 'drupal/auto_alter:^2.0'
Overview
The Automatic Alternative Text module integrates with Microsoft Azure Cognitive Services to provide AI-powered alternative text generation for images in Drupal. When content editors upload or save images without providing alternative text, the module automatically queries Azure's Computer Vision API to analyze the image and generate a descriptive caption.
The module operates transparently during entity save operations, examining all image fields and populating empty alt text fields with AI-generated descriptions. It also provides optional functionality to suggest alternative text immediately upon image upload, allowing editors to review and modify the AI-generated text before saving.
The generated descriptions include confidence scores from the Azure API, which can optionally be displayed to users via status messages. For images larger than 1MB, the module automatically creates scaled derivatives to optimize API requests and reduce bandwidth usage.
A companion submodule (Automatic Alternative Text Translation) extends functionality by translating the English descriptions returned by Azure into the site's current language using the Azure Translator Text API.
Features
- Automatic alt text generation using Microsoft Azure Computer Vision API during entity save operations
- Optional immediate alt text suggestions when images are uploaded
- Support for all image fields across all content entity types
- Automatic image scaling for files larger than 1MB to optimize API requests
- Status messages showing generated alt text with confidence percentages
- Integration with CKEditor image dialog for inline image alt text generation
- Built-in API validation during configuration to verify credentials
- Comprehensive error logging for API communication issues
- Submodule for translating generated English descriptions to other languages
Use Cases
Improving Accessibility Compliance
Organizations required to meet WCAG accessibility standards can use this module to ensure all images have meaningful alternative text. When content editors forget to add alt text or lack time to write descriptions, the module automatically generates appropriate text, helping maintain accessibility compliance across the site.
High-Volume Content Sites
News sites, e-commerce platforms, or other content-heavy sites where editors upload many images daily benefit from automated alt text generation. Editors can review and refine the suggestions rather than writing descriptions from scratch, significantly reducing content creation time.
Multilingual Sites
Sites serving multiple language audiences can combine the main module with the translation submodule to automatically generate and translate alt text. The Computer Vision API analyzes images and returns English descriptions, which are then translated to the visitor's language (German, French, Spanish, etc.).
Legacy Content Migration
When migrating content from systems without alt text or importing large image libraries, this module can automatically populate alt text for images that lack descriptions, improving the accessibility of migrated content without manual intervention.
CKEditor Inline Images
Content editors inserting images directly into WYSIWYG content using CKEditor can click the 'Get suggestion' button in the image dialog to generate alt text without leaving the editor, streamlining the content creation workflow.
Tips
- Test your Azure API configuration using the built-in validation on the settings form before relying on automatic alt text generation
- Enable 'Show status message to user' during initial setup to verify the module is working and see confidence scores
- Use the 'Make suggestion' option to allow editors to review and improve AI-generated descriptions before saving
- Monitor your Azure API usage to avoid unexpected costs, especially on high-traffic sites
- The module creates an 'auto_alter_help' image style that scales images to 1440x1440 and converts to JPG - this is used automatically for files over 1MB
- Consider the translation submodule if your site serves non-English audiences - it adds minimal overhead and ensures localized alt text
Technical Details
Admin Pages 2
/admin/config/media/auto_alter
Configure the Microsoft Azure Computer Vision API integration for automatic alternative text generation. This page allows you to enter your Azure API credentials and control how the module behaves when generating alt text.
/admin/config/media/auto_alter/translate
Configure the Microsoft Azure Translator Text API to translate the AI-generated English descriptions into other languages. This settings page is provided by the auto_alter_translate submodule.
Permissions 1
Hooks 3
hook_entity_presave
Examines all image fields on content entities during save operations. For any image without alt text, calls the Azure API to generate and populate the alt text automatically.
hook_form_alter
Modifies entity forms to provide alt text suggestions when images are uploaded. Also adds a 'Get suggestion' button to the CKEditor image dialog for inline image insertion.
hook_modules_installed
Displays a reminder message when the module is first installed, prompting administrators to configure their Azure API credentials.
Troubleshooting 6
Navigate to /admin/config/media/auto_alter and enter your Azure Computer Vision API key and endpoint URL. You must create a Computer Vision resource in your Azure Portal first.
Verify you copied the complete API key from Azure Portal. Ensure you're using the key from a Computer Vision resource, not another Azure service.
Check that your endpoint URL is complete and correct. It should include the region, API version, and describe operation. Example: https://westeurope.api.cognitive.microsoft.com/vision/v1.0/describe?maxCandidates=1
1) Verify API credentials are correct via the settings page validation. 2) Check Drupal logs for Azure API error messages. 3) Ensure the image field has the 'Alternative text' field enabled in field settings.
Ensure the auto_alter_translate submodule is enabled, the 'Enable translation' checkbox is checked, and valid Azure Translator API credentials are configured. The source language must differ from the target language.
The module automatically scales images larger than 1MB using the 'auto_alter_help' image style. If issues persist, consider reducing maximum upload size or optimizing images before upload.
Security Notes 4
- API keys are stored in Drupal configuration - ensure proper access controls on configuration export files
- The module sanitizes API responses using Drupal's XSS filter before storing alt text
- Image data is transmitted to Microsoft Azure servers for processing - review Azure's data handling policies for compliance requirements
- Ensure 'administer Automatic Alternative Text' permission is granted only to trusted administrators