Gettext builder cannot extract 'option' directive

[hwhsu1231]

Describe the bug

Hello, Sphinx Maintainance Team.

Recently, I tried to translate CMake Documentation with its .po files generated by Gettext builder. In CMake Documentation, we can see that there is a type of content derived from the Sphinx option directive. Take cmake's --graphviz=<file> as an example:

• Corresponding .html link: --graphviz=<file>
• Corresponding .rst link: --graphviz=<file>

If possible, I want to translate the <file> in the --graphviz=<file> as well. However, I found that even though I specify all the possible values in gettext_additional_targets when building with gettext builder:

-Dgettext_additional_targets=index,literal-block,doctest-block,raw,image

I still don't see the content of option directives being extracted into the generated cmake.1.pot.

What did I miss? Is this a bug? Or Is Sphinx's gettext builder designed to be unable to extract option directive? Or is it just not able to do it currently, and is required a feature request?

How to Reproduce

1. Run the following commands in order:

   git clone --depth=1 --branch=v3.28.4 https://github.com/Kitware/CMake.git
   cd CMake
   cmake -D SPHINX_HTML=ON -S Utilities/Sphinx -B Utilities/Sphinx/build
   LANG=en_US.UTF-8 sphinx-build -b gettext -Dgettext_additional_targets=index,literal-block,doctest-block,raw,image -Dgettext_compact=0 -c Utilities/Sphinx/build Help Help/locale/pot
   kate Help/locale/pot/manual/cmake.1.pot

2. Search --graphviz=<file> string in Kate (Ctrl+F).

Expected/Actual Result:

• Expected Result: Find an entry with --graphviz=<file> in the cmake.1.pot.
• Actual Result: Not found.

Environment Information

Platform:              linux; (Linux-6.5.0-35-generic-x86_64-with-glibc2.35)
Python version:        3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

No response

Additional context

Full log of How to Reproduce

Click to expand the full log

hwhsu1231@vb-kubuntu:~/Repo/testing$ git clone --depth=1 --branch=v3.28.4 https://github.com/Kitware/CMake.git
Cloning into 'CMake'...
remote: Enumerating objects: 21228, done.
remote: Counting objects: 100% (21228/21228), done.
remote: Compressing objects: 100% (15454/15454), done.
remote: Total 21228 (delta 4458), reused 14380 (delta 3547), pack-reused 0
Receiving objects: 100% (21228/21228), 13.11 MiB | 7.55 MiB/s, done.
Resolving deltas: 100% (4458/4458), done.
Note: switching to 'b5602e7254c8ce4a6f732c017d784cd80559e5aa'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

hwhsu1231@vb-kubuntu:~/Repo/testing$ cd CMake
hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ cmake -D SPHINX_HTML=ON -S Utilities/Sphinx -B Utilities/Sphinx/build
-- Configuring done (0.3s)
-- Generating done (0.0s)
-- Build files have been written to: /home/hwhsu1231/Repo/testing/CMake/Utilities/Sphinx/build
hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ LANG=en_US.UTF-8 sphinx-build -b gettext -Dgettext_additional_targets=index,literal-block,doctest-block,raw,image -Dgettext_compact=0 -c Utilities/Sphinx/build Help Help/locale/pot
Running Sphinx v7.2.6
making output directory... done
building [gettext]: targets for 1 template files
reading templates... [100%] /home/hwhsu1231/Repo/testing/CMake/Utilities/Sphinx/templates/layout.html
building [gettext]: targets for 1997 source files that are out of date
updating environment: [new config] 1997 added, 0 changed, 0 removed
reading sources... [100%] variable/XCODE_VERSION
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... done
writing output... [100%] variable/XCODE_VERSION
writing message catalogs... [100%] variable/XCODE_VERSION
build succeeded.

The message catalogs are in Help/locale/pot.
hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ kate Help/locale/pot/manual/cmake.1.pot
hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ 

[n-peugnet]

What did I miss? Is this a bug? Or Is Sphinx's gettext builder designed to be unable to extract option directive? Or is it just not able to do it currently, and is required a feature request?

Sphinx's gettext builder is currently explicitly designed to ignore certain strings by default, such as code-blocks, or the option directive. Though some have been added as optional additional targets, it is usually useful to ignore them as these are strings that are likely not to be changed by translations.

The option directive simply hasn't been yet added as a possible additional target. But it would not be trivial to add as it is also a cross-reference target, so it would be quite difficult to make it work correctly if the option name is changed in the translations.

[hwhsu1231]

Hello, @n-peugnet

The option directive simply hasn't been yet added as a possible additional target. But it would not be trivial to add as it is also a cross-reference target, so it would be quite difficult to make it work correctly if the option name is changed in the translations.

What about translating the entry which cross-references the option directive with the following form:

# Source (msgid)
:option:`--graphviz=<file>`

# Translation (msgstr)
:option:`--graphviz=<檔案> <--graphviz=<file>>`

Just like the way CMake Documentation did in its cmake.1.rst

:manual:`CMake Presets <cmake-presets(7)>`

Is it possible to do so?

[n-peugnet]

What about translating the entry which cross-references the option directive with the following form:

# Source (msgid)
:option:`--graphviz=<file>`

# Translation (msgstr)
:option:`--graphviz=<檔案> <--graphviz=<file>>`

Translating the option role and adding an explicit target should already possible. You were initially talking about the option directive.

Maybe a simple way to do it would be to only extract the option's example value (=<file> in your initial example), as it seems like is is already treated differently from the rest, and changing it should not affect the cross-referencing (it is not mandatory in the option role). But I didn't check the code yet, so not sure how complicated it would be and if it really is a good idea.

Anyway, this should be tagged as a feature request as this is not a bug, but I don't have the permissions to change the tags myself.

[jayaddison]

(issue labels updated; let me know if those seem accurate/inaccurate)