Help:Lint errors/missing-image-alt-text

This lint isn't meant to be automatically enforced, since determining suitable alt text and when to deliberately skip it is a context-sensitive human operation. It's meant to serve as an input for possible corrections and improvements in a context-aware workflow such as in experimental mobile apps editing workflow tools. Understanding the false positives that this lint may cause, assistance remains available on the project talk page (see below) and suggestions are welcome. There are expected to be a large number of matches on this lint, and many of them may be difficult to resolve as such.

This documentation outlines the specifications and usage guidelines for the "missing-image-alt-text" linter, which records image usages in wiki pages that don't have an alt text attribute on them. Depending on context this may indicate accessibility problems for sight-impaired readers or in text-to-speech contexts without image display.

The records of missing alt text are meant to feed into workflows and tooling for improving usages of images in context, detecting possible accessibility problems and surfacing them for human review in a workflow meant to support devising and writing a good alt text.

It is not expected to be used for bulk-fix operations, as there is no general automatable solution for how to write a good alt text, or whether alt text is needed in a given situation.

This mobile apps alt text tooling is experimental for now, and may change in how it functions and whether it's kept or changed in the long term.

Overview

Images in wiki pages can have "alt text" descriptions for accessibility purposes, assigned via the alt= parameter or, for non-thumbnail images without room for a caption, by eliding the caption into an alt text attribute.

  Inline, no alt text:
  [[File:Wikipedia-logo-v2.svg]]

  Inline, with alt text via unshown "caption":
  [[File:Wikipedia-logo-v2.svg
  |Globe of puzzle pieces with characters from different languages]]

  Thumb, with caption but no alt text:
  [[File:Wikipedia-logo-v2.svg
  |right
  |The Wikipedia logo]]

  Thumb, with caption and alt text:
  [[File:Wikipedia-logo-v2.svg
  |right
  |alt=Globe of puzzle pieces with characters from different languages
  |The Wikipedia logo]]

These are meant to allow non-visual contexts such as text-to-speech or assistive technology for sight-impaired users to usefully describe the contents of the image, in its usage context, when it cannot be displayed usefully or clearly.

It is not strictly speaking an error to be missing alt text, but it may indicate that the information conveyed by the image won't be available to all users in all contexts, so alt text for information-bearing images is considered advisable for accessibility best practices.

The markup linter can detect when alt text is missing -- but it cannot detect whether alt text was needed in this context. Thus it cannot serve as an automated source of fixes, and requires human review and thought in correction workflows.

How to fix

If an alt text description is suitable and distinct from any present caption -- describing the relevant appearance of the image in ways that are not covered by any semantic information in the caption - then it can be added in the markup.

Note that the lint picks up images constructed via templates, so sometimes you may need to dive into the template to figure out where to stuff in another attribute -- there may not be a clean way to do it without modification.

Current status

As of now, the "missing-image-alt-text" lint is assigned a priority level of none. This means it is not listed in "Page information" and is not visible on the main lint error page, and there are no expectations for editors to address identified issues until further notice. The lint is undergoing testing for use in a mobile apps workflow, and depending on the analysis and impact of that work it may be kept or removed or changed in the future.

Usage guidelines

Editors are not expected to directly address lint matches for "missing-image-alt-text", but if you find it useful for your tooling as well, let us know at the mobile apps team!