Skip to content

Draft: Sphinx 4 i18n migration (Remove `image` from `gettext_additional_targets`)

Alvin Wong requested to merge work/alvin/disable-gettext-image into master

Since Sphinx 4.0, image alt-texts are translatable by default, separate from the image links. As the contributor's guide instructs placing translated images under the "language_code" subdirs to be auto-discovered by Sphinx, we no longer need to make use of the translation feature for images.

This requires Scripty to use Sphinx >=4.0 (note: the binary-factory builder is already using Sphinx >=4.0). However, I recommend against upgrading the Scripty environment to the official package for now, due to the issue described in Instead, the changes in should be included. Otherwise, it might make the translation process quite messy. (This only applies to generating the POT files, so we don't need to touch the binary-factory builder.)

Upgrading to Sphinx >=4.0 including the aforementioned changes will change the msgid format of image alt texts.

  • How it used to be in Sphinx <3.5:
    msgid ""
    ".. image:: images/color_category/Kiki_cLUTprofiles.png\n"
    "   :alt: Image of Kiki looking confused through books."
  • After upgrading, they will become two separate msgids:
    msgid ".. image:: /images/color_category/Kiki_cLUTprofiles.png"
    msgid "Image of Kiki looking confused through books."

Merging this MR will then remove the image links (the first msgid, i.e. msgid ".. image:: images/color_category/Kiki_cLUTprofiles.png") from the POT template.

We are getting close to branching a new stable branch for translations, so we probably want to synchronize the Sphinx upgrade with moving the translation branch. Not sure what would be the best course of action, but I think we should notify the localization team.

CC @teams/localization (is this right?)

Merge request reports