Working with image alt text

Automatic alt text generation helps ensure that images you publish go live with text descriptions that can be read by screen readers. Alt text can be generated in multiple languages for use across multiple locales and can be configured to adhere to your brand rules.

Generating alt text automatically for images helps:

• Improve accessibility of your Web content by enabling screen-reader users to comprehend images
• Enhance your SEO by including descriptive text with images
• Adhere to accessibility laws such as "The European Accessibility Act" in the European Union and the "Websites and Software Applications Accessibility Act" in the US

Automatic alt text generation and Amplience credits

Image alt text generation requires Amplience credits for generating alt text at a rate of 2 credits per image, per locale. More about Amplience credits.

Setting up automatic alt text

To start generating alt text automatically, you'll need to reach out to Amplience Support, who will configure the service for your chosen asset stores. You'll need to provide the default locale to use for image descriptions, and any additional locales you would like to use.

Tune image alt text generation

If you're already using Content Studio and have set up brand rules, such as words to substitute, these can be included when configuring the service.

Generating alt text automatically

Once set up, alt text will be automatically generated when you use any of the following upload methods:

• The GraphQL Asset Management API
• Automated bulk upload
• Manual upload using Content Hub
• Manual upload using the Asset Tab in Dynamic Content

Alt text will also be generated when you edit images with Image Studio through Dynamic Content. See Editing images as part of your workflow.

For help with generating alt text for previously uploaded images, please contact your Amplience account director for more information.

When alt text is generated for sets, descriptions are generated for each individual image in the set. More about sets.

Assets, locales and images

The locales that are used for setting up automatic alt text generation are independent from the Content Hub asset locales used to retrieve and group assets. See Content Hub asset locales.

Fetching image alt text

You can retrieve alt text that's stored in image metadata, along with any locale variants, using the Media Delivery API.

You can also use manifests to retrieve alt text

Image alt text metadata can be retrieved using manifests, as part of your regular asset export schedule. See Manifests

Use the Media Delivery API to retrieve image alt text for published images from image metadata.

For example, to fetch the metadata for an image with the name sunglasses-on-beach use:

https://cdn.media.amplience.net/i/demobootha/sunglasses-on-beach.json?metadata=true

For this example, the API returns the following alt text descriptions:

{
  "isImage": true,
  "alpha": false,
  "width": 5184,
  "height": 3456,
  "format": "JPEG",
  "metadata": {
    "altText": {
      "descriptions": {
        "it-IT": "Occhiali da sole con lenti arancioni sulla sabbia al tramonto.",
        "de-DE": "Sonnenbrille mit orangefarbenen Gläsern liegt am Strand bei Sonnenuntergang.",
        "en-US": "Aviator sunglasses with orange lenses placed on sandy beach at sunset.",
        "es-ES": "Gafas de sol con lentes naranja reflejando el atardecer en la playa.",
        "fr-FR": "Lunettes de soleil aviateur à verres orange sur une plage de sable au coucher du soleil."
      },
      "defaultDescription": "Aviator sunglasses with orange lenses placed on sandy beach at sunset."
    }
  },
  "status": "ok"
}

See Viewing generated image alt text for more details of viewing and editing image alt text within Content Hub.

Managing alt text in Dynamic Content

With Next Generation Authoring switched on in Dynamic Content, alt text can be viewed on the media card when you add an image containing alt text metadata to a content item.

In your content type schema you just need to include an image property, with no additional settings required.

Viewing and editing alt text

To view alt text on the content form, hover over an image and click the "alt text" icon.

A dialog showing the image alt text is displayed. You can edit the alt text by clicking in the text box, making a change and clicking the "apply" button. The edited alt text will be saved with the content but the image asset meta data will not be updated.

Viewing locale variants

If alt text has been generated for multiple locales then you can choose the locale you want to view from the "Choose variant" menu. If you choose a variant and click the "Apply" button, the variant will be used as the default alt text stored with the content.

Alt text in the content item JSON data

Image alt text is stored in the altText field of an image property and returned in the content item's JSON. If the image asset does not contain any alt text metadata then the image property will not contain an altText field.

Here's the Content Delivery URL to return the JSON for a content item that contains a single image property. We've added an image containing alt text metadata to the content.

https://demobootha.cdn.content.amplience.net/content/id/375c95a1-a734-4133-b3e6-712369e13458?depth=all&format=inlined

The JSON for the content item is shown below. In this example we chose to set the image alt text to the es-ES variant.

{
   "content":{
      "_meta":{
         "schema":"https://example.com/image-with-alt-text",
         "name":"Image with alt text",
         "deliveryId":"375c95a1-a734-4133-b3e6-712369e13458"
      },
      "image":{
         "_meta":{
            "schema":"http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
         },
         "id":"611acc54-d90d-4d39-95fb-5fefe2db991b",
         "name":"sunglasses-on-beach",
         "endpoint":"demobootha",
         "defaultHost":"cdn.media.amplience.net",
         "mimeType":"image/jpeg",
         "altText":"Gafas de sol con lentes naranja reflejando el atardecer en la playa."
      }
   }
}

altText will contain the default alt text for an image. If you want to fetch the alt text for each locale then you will need to retrieve it from the image metadata using the Media Delivery API.

Alt text and Next Generation Authoring

The altText field is included with an image property whether or not you're using Next Generation Authoring, but text is only shown in the media card when the new authoring experience is enabled.

Turning off alt text on the media card

Alt text will be shown on the media card by default, but you can hide the alt text icon by setting the withAltText params for an image property in your content type schema. An image property with alt text switched off is shown below.

"type": "object",
    "properties": {
        "image": {
            "title": "Image",
            "allOf": [
                { "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link" }
            ],
            "ui:component": {
                "params": {
                    "withAltText": false
                }
            }
        }

Using alt text with the img tag

When you display images on your site with HTML, you use the <img> tag, adding alt text as an attribute to provide a description that screen readers can use, or in case the image doesn't load for some reason.

You can retrieve the alt text for an image either from the image's metadata or from the altText field of a content item that contains the image.

The <img> tag has two attributes:

• src to specify the path to the image
• alt to specify alternate text that's descriptive enough to give the reader a sense of what the image is about

Here's an example showing alt text with an <img> tag:

<img src="https://cdn.media.amplience.net/i/demobootha/sunglasses-on-beach" alt="Aviator sunglasses with orange lenses placed on sandy beach at sunset."></img>

And here's the rendered image for the above example. Hovering your cursor over the image will display the alt text.

If an image has multiple alt text descriptions for different locales, include the text for your chosen locale in the alt attribute. For example:

<img src="https://cdn.media.amplience.net/i/ampproduct/woman_summer_outfit" alt="Gafas de sol con lentes naranja reflejando el atardecer en la playa."></img>

Alternative approaches to supporting alt text

If you choose not to enable automatic alt text generation then some alternative approaches include:

• Using the image alt text extension to generate alt text for images and store the text with your content.
• Adding an alt text string property to your content type schemas to allow users to enter their own alt text for an image. The media schema example is a very simple example of this approach,

Related pages

Viewing and editing generated image alt text

Content Studio Alt text template

Amplience credits

Media Delivery API