WordPress Media Library Bulk Alt Text: JSON Mapping

Sample file

Three sample entries, generated by the WordPress JSON export code.

{
  "team-photo-2024.jpg": {
    "alt": "Six colleagues standing in front of a glass office entrance",
    "caption": "Six colleagues stand together in front of a glass office entrance",
    "description": "Six colleagues stand together in front of a glass office entrance. They are smiling and dressed casually."
  },
  "sales-chart-q3.png": {
    "alt": "Bar chart showing sales rising each month from July to September",
    "caption": "A bar chart of monthly sales for the third quarter",
    "description": "A bar chart of monthly sales for the third quarter. The bars grow taller from July to September."
  },
  "workshop-bench.jpg": {
    "alt": "Wooden workbench with hand tools hung on a pegboard",
    "caption": "A wooden workbench in a workshop with hand tools hung neatly on a pegboard above it",
    "description": "A wooden workbench in a workshop with hand tools hung neatly on a pegboard above it."
  }
}

Steps

1. Generate alt text for the images in your media library and review it.
2. Choose the WordPress JSON export. Each entry is keyed by the image's file name.
3. Find the attachment ID for each file name in your site. The media library list or a WP-CLI query shows it.
4. Set the alt text with WP-CLI, for example wp post meta update followed by the ID, _wp_attachment_image_alt and the text.
5. Run the script on a staging copy first, then spot-check a few images on the live site.

Start with the Alt text generator, then check the text with the alt text checker.

How the file is laid out

The file is a single JSON object. Each key is an image file name, and each value has three fields: alt, caption and description. Alt is the text for the alt attribute. Description is the longer sentence the model wrote. Caption is the first sentence of that description, or the alt text when there is no description.

The structure is a convenience for scripts. WordPress itself does not read this file, and nothing in core imports it.

Where WordPress keeps alt text

Every item in the media library is a post of type attachment. Its alt text is saved as post meta under the key _wp_attachment_image_alt. The caption lives in the attachment's excerpt, and the description in its content. WP-CLI's post meta update command can write the alt text when you give it the attachment ID, the key and the value.

A file name is not the same as an ID, and the same file name can exist more than once, for example after re-uploads. Resolve each name to an ID first, and decide what to do when you find none or more than one.

A safe way to run a bulk update

Work on a staging copy, or take a full database backup. Write the script so it only changes images whose alt text is currently empty, which avoids overwriting text a person has already improved. Log every change, and spot-check a sample against the site.

If you do not use the command line, a plugin that edits alt text in bulk can do the same job. Check it is maintained and test it on a small set.

A note on captions and descriptions

Visible captions appear under the image on the page, so only use a caption when you want readers to see it. Writing the same sentence into alt text and a caption makes screen reader users hear it twice. Treat the caption and description fields in the file as optional drafts.

Limits and facts

Frequently asked questions