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 https://bugs.kde.org/show_bug.cgi?id=439708. Instead, the changes in https://github.com/sphinx-doc/sphinx/pull/9454 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"
    and 
    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