Automatic alt text

With the help of this extension, you can be sure that your content has alt text that makes it accessible for users who rely on screen readers, without the need to manually enter alt text for every image and locale.

This content field extension can be used in two modes:

• Automatic mode: seamlessly retrieve and use automatically generated alt text for images in Content Hub, as part of your authoring workflow in Dynamic Content. This is the default mode and retrieves image alt text generated by the Automatic Alt Text service. This service uses the Content Studio alt text template and requires Amplience credits to generate alt text.
• Generated mode: generate alt text on the fly from within the authoring experience. Alt text can be generated for multiple locales using the alt text template in Content Studio. To use the extension in this mode you will need to set the mode to GENERATED in the extension installation parameters. You must have Content Studio installed and have sufficient Amplience credits to generate alt text.

Amplience Credits and alt text generation

Image alt text generation requires Amplience credits for generating alt text at a rate of 1 credit per image, per locale.

Using the automatic alt text extension

To use the extension in either the automatic or generated mode, simply associate it with an image field and a string field (that represents the alt text) in your content type schema. You can use this extension with both standard and localized text string fields.

The extension can be used with any native Amplience image field, including if that field is in an extension.

Setting up this extension

You can find complete configuration documentation for this extension on GitHub.

Using the extension in automatic mode

By default, the extension uses automatic mode and retrieves the alt text that was added by the Automatic alt text service to the image metadata.

Before using this extension in automatic mode...

• Ensure that the Automatic Alt Text service is enabled for your account so that alt text can be retrieved from your image metadata.
• Your Dynamic Content Hub must have the Assets Tab enabled, to ensure API access to alt text meta data for images.

In addition to automatically including existing image alt text into your content, this extension lets you modify alt text to better match your content, saving the changes as part of the content. See Refreshing and modifying alt text.

Alt text for standard text fields

When the Automatic alt text extension is used with a standard text field, the Dynamic Content authoring experience will show one alt text field and a number of locale options, like the example below:

The alt text that will be used with the image is displayed in the "Alt text" field. You can view or select other alt text from the available locale options displayed below the text field.

If you modify alt text values, the updates will be saved with the content, without updating the alt text in Content Hub. To reset changed alt text values back to those stored in Content Hub, select the required locale and click the globe icon.

Alt text for localized text fields

When the extension is used with a localized text field, the Dynamic Content authoring experience displays each alt text locale in a list that you can expand or collapse.

To reset the alt text values back to those stored in Content Hub you can:

• Reset all of the alt text values at once by clicking "Refresh alt texts". This will reset/clear all of the alt text values shown on your form.
• Reset individual alt text values by refreshing them individually

Clearing all alt text values

Quickly clear all image alt text values for all localized fields by using the Clear all feature.

Note that filtering locales in your content form will not filter the localized alt text fields displayed in the form. This is demonstrated in the image above where the locale filters (top right) show that 2 locales are selected, but the extension still shows the locales for which it has been configured.

Refreshing and modifying alt text

To overwrite alt text shown in the authoring experience with image alt text stored in Content Hub, you use 'Refresh alt texts'.

Instances when you may want to refresh alt text values in your content are:

• To reset image alt text values you've modified while authoring content, back to what’s saved in Content Hub.
• If you retrieve image alt text after swapping an image for a different image.
• If the extension is configured not to automatically retrieve image alt text from Content Hub, you will need to use 'refresh' to initially load image alt text from Content Hub. When you save content that has alt text, the alt text will be loaded when you next open the content.

note

• Any alt text updates that you make in the Dynamic Content authoring experience are made in your content only, and are not saved back to Content Hub.
• If you edit an image in Image Studio and save it, it creates a new image and the appropriate alt text will apply

Using the extension in generated mode

To use the extension in generated mode, set the mode parameter to GENERATED in the extension installation parameters. You will then be able to generate alt text for an image using the Content Studio alt text template rather than retrieving it from the image metadata.

You can also specify your brand in the extension parameters so that the alt text will be generated to conform to your brand rules.

Generating alt text for standard fields

As with the automatic mode, when the extension is used in generated mode with a standard text field, the alt text field will be shown together with your supported locales. When an image is added, the alt text is automatically generated for the selected locale. Click the buttons for each locale to generate alt text. When you choose a locale it will become the default and the alt text for that locale be saved with the content.

Note that you can turn the automatic generation of captions off by setting autoCaption to false in the extension installation parameters.

Generating alt text for localized fields

When the extension is used in generated mode with a localized text field, each alt text locale is shown. When an image is added, the alt text will be automatically generated for each locale.

If you set autoCaption to false in the extension installation parameters, then you you will need to click "Generate alt texts" button to generate the alt text for each locale.

Schema examples

To help you get started with using the Automatic alt text extension we've created some schema examples.

There are three schema examples included: one for content that has a single alt text field, another for content that has localized fields and one that demonstrates the use of generated mode for alt text generation using the Content Studio alt text template.

All of the examples include the extension directly in the schema. In most cases you will want to register the extension so that you do not have to specify the installation parameters each time you use it in a schema. For the extension registration details, see Automatic alt text extension GitHub repository

Note that to use these examples the extension must be linked to an image property, image, that contains a JSON pointer or relative JSON pointer reference to the alt text field for which text will be retrieved.

To use the schemas you will need to set the "Read access" API permissions.

Schema example for a single alt text field

An example schema with a link to the extension using its URL, is shown below. The alt string property contains a reference to image.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema-examples.com/automatic-alt-text-extension",
  "title": "Automatic alt text extension",
  "description": "Demonstrates the use of the automatic alt text extension with a single alt text field",
  "$comment": "Docs: https://amplience.com/developers/docs/ai-services/automatic-alt-text/",
  "allOf": [
    {
      "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
    }
  ],
  "type": "object",
  "properties": {
    "image": {
      "title": "Hero Image",
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
        }
      ],
      "ui:component": {
        "params": {
          "withAltText": false
        }
      }
    },
    "alt": {
      "title": "Alt Text",
      "type": "string",
      "minLength": 0,
      "maxLength": 200,
      "ui:extension": {
        "url": "https://automatic-alt-text.extensions.content.amplience.net/",
        "params": {
          "image": "/image"
        }
      }
    }
  },
  "propertyOrder": []
}

Schema example with a localized alt text field

An example schema with a link to the extension using its URL, is shown below. The alt string property is a localized string that contains a reference to the image.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://schema-examples.com/localized-automatic-alt-text-extension",
  "title": "Localized automatic alt text extension",
  "description": "Demonstrates how to use the automatic alt text extension with a localized alt text field",
  "$comment": "Docs: https://amplience.com/developers/docs/ai-services/automatic-alt-text/ ",
  "allOf": [
    {
      "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
    }
  ],
  "type": "object",
  "properties": {
    "image": {
      "title": "Hero Image",
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
        }
      ],
      "ui:component": {
        "params": {
          "withAltText": false
        }
      }
    },
    "alt": {
      "title": "Alt text",
      "allOf": [
        {
          "$ref": "http://bigcontent.io/cms/schema/v1/localization#/definitions/localized-string"
        }
      ],
      "ui:extension": {
        "url": "https://automatic-alt-text.extensions.content.amplience.net/",
        "params": {
          "image": "/image"
        }
      }
    }
  },
  "propertyOrder": []
}

Schema example for generated mode

This example schema demonstrates the use of generated mode. It defines a single alt text string and is configured to generate alt text using the Content Studio alt text template. Generating alt text uses Amplience Credits.

The only difference between the configuration of this schema and the schema example for a single alt text field is setting mode: GENERATED in the params.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://schema-examples.com/automatic-alt-text-extension-generated",
    "title": "Automatic alt text extension",
    "description": "Demonstrates the use of the automatic alt text extension with a single alt text field in generated mode. The alt text will be generated using the Content Studio alt text template and uses Amplience Credits.",
    "$comment": "Docs: Docs: https://amplience.com/developers/docs/ai-services/automatic-alt-text/ ",
    "allOf": [
        {
            "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
        }
    ],
    "type": "object",
    "properties": {
        "image": {
            "title": "Hero Image",
            "allOf": [
                {
                    "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
                }
            ],
            "ui:component": {
                "params": {
                    "withAltText": false
                }
            }
        },
        "alt": {
            "title": "Alt Text",
            "type": "string",
            "minLength": 0,
            "maxLength": 200,
            "ui:extension": {
                "url": "https://automatic-alt-text.extensions.content.amplience.net/",
                "params": {
                    "image": "/image",
                    "mode": "GENERATED"
                }
            }
        }
    },
    "propertyOrder": []
}

Related pages

Extensions overview

Registering extensions

Schema examples

Automatic alt text extension GitHub repository

Automatic alt text generation service

Working with image alt text