# Image descriptions (/docs/reader-support/images)



Long image descriptions use the same text map as the rest of the page. For an image node, use the `texts.json` entry for its `data-id`, then fall back to the page’s own description, `alt`, or `figcaption`.

The natural presentation is an image lightbox or zoom view, where readers have space to read a longer description. Show it only when `features.describeImages` is true.

## Localized image variants [#localized-image-variants]

`images.json` maps an image id to a replacement asset when the image itself contains translated content, such as a labelled diagram. On language change, replace the `src` of the corresponding image nodes.

The map is optional. `features.describeImages` can be true when the export has descriptions but no translated image asset, so leave the original `src` in place whenever the map or its id is absent.

Variants exist for target languages, never the source one, so the map lives under each translated locale:

<PackageSnippet path="content/i18n/pt-BR/images.json" />

The key is the `data-id` on the `<img>`; the value is a file sitting beside the original in `images/`. Switching to pt-BR means swapping `src` on exactly those six images and leaving every other image untouched.

<PackageSnippet title="Image-description feature configuration" path="assets/config.json" />

<Callout title="An empty map is valid">
  Most books need no translated images at all, and ship `{}`. Leave the original source in place whenever the map, or an image's id within it, is absent.
</Callout>