gh-126609: Allow translating the availability directive

[AA-Turner]

• Issue: Availability extension's text translation breaks directive rendering #126609

---

📚 Documentation preview 📚: https://cpython-previews--129549.org.readthedocs.build/

[m-aciek]

I hope I'm not missing anything, but that's what I get:

When I build gettext with % make -e SPHINXOPTS="--write-all" gettext on the branch, I get a full reference statement in the pot file:

#: ../../library/webbrowser.rst:54
msgid ":ref:`Availability <availability>`: not WASI, not Android."
msgstr ""

Then after inserting the translation in po file and building docs:

msgid ":ref:`Availability <availability>`: not WASI, not Android."
msgstr ":ref:`Dostępność <availability>`: nie WASI, nie Android."

It's not being loaded when building html with % make -e SPHINXOPTS="-D language='pl'" html:

When I add manually to that the Availability word translation, I get the warning in logs and the same effect as on main branch:

[AA-Turner]

You should definitely not get the :ref: line on this branch as it constructs nodes directly. Could you try make clean or deleting your build folder to clear any caches?

A

[AA-Turner]

I'm minded to merge this as it fixes a definite oversight in the original PR, and doesn't prevent us merging the revert commit if need be.

A

[m-aciek]

Indeed, I've checked wrong file. There's Availability still generated in the POT. Though in html build I still receive broken rendering.

[AA-Turner]

Though in html build I still receive broken rendering.

Do you still get the [i18n.inconsistent_references] warning?

[m-aciek]

Do you still get the [i18n.inconsistent_references] warning?

Yes, I do.

[AA-Turner]

@m-aciek what are your reproduction steps?

[m-aciek]

CPython repository checked out on this branch, symlink at Doc/locales/pl: LC_MESSAGES to a repository with language translations.

% ls -la locales/pl/LC_MESSAGES 
lrwxr-xr-x  1 …  staff  26 Oct 30  2022 locales/pl/LC_MESSAGES -> ../../../../python-docs-pl

Language repository (pl) checked out at 3.13 with a patch applied:

Index: library/webbrowser.po
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/library/webbrowser.po b/library/webbrowser.po
--- a/library/webbrowser.po	(revision 632304c02750bb5b42a49e0f7230981f0285dcb9)
+++ b/library/webbrowser.po	(date 1738506193244)
@@ -88,7 +88,7 @@
 msgstr ""
 
 msgid "Availability"
-msgstr "Availability"
+msgstr "Dostępność"
 
 msgid "The following exception is defined:"
 msgstr ""

Than in CPython repo, Doc directory I run:

% make clean
% make -e SPHINXOPTS="-D language='pl' --write-all" html

In the build output I see bunch of warnings from license.rst and one from webbrowser.rst.

…/projects/cpython/Doc/library/webbrowser.rst:54: WARNING: inconsistent term references in translated message. original: ['Availability'], translated: [] [i18n.inconsistent_references]

And in Doc/build/html/library/webbrowser.html, only "Dostępność" instead of the rendering, as on the screenshot in the previous message.

[AA-Turner]

For reference, from a clean check-out of my branch I ran:

PS> cd Doc
PS> python -m sphinx build -M gettext . build -aET
PS> rmdir -Recurse build/gettext/.doctrees
PS> mkdir locales/en_GB/LC_MESSAGES
PS> mv build/gettext/* locales/en_GB/LC_MESSAGES
PS> cd locales
PS> Get-ChildItem -Recurse -Include *.pot | Rename-Item -NewName { $_.Name.replace(".pot",".po") }

Then renaming all instances of

msgid "Availability"
msgstr ""

to

msgid "Availability"
msgstr "AVAILABILITY"

and then

python -m sphinx build -M html . build -aETW --define language=en_GB

With this I get no errors, and the directive renders & links correctly:

[AA-Turner]

Index: library/webbrowser.po
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/library/webbrowser.po b/library/webbrowser.po
--- a/library/webbrowser.po	(revision 632304c02750bb5b42a49e0f7230981f0285dcb9)
+++ b/library/webbrowser.po	(date 1738506193244)
@@ -88,7 +88,7 @@
 msgstr ""
 
 msgid "Availability"
-msgstr "Availability"
+msgstr "Dostępność"
 
 msgid "The following exception is defined:"
 msgstr ""

Is there any difference if all instances are replaced instead of just this one?

Than in CPython repo, Doc directory I run:

% make clean
% make -e SPHINXOPTS="-D language='pl' --write-all" html

Please could you try with SPHINXOPTS="-D language='pl' --fresh-env --write-all"?

[m-aciek]

Is there any difference if all instances are replaced instead of just this one?

I don't think so, just tried with a minimal change.

Please could you try with SPHINXOPTS="-D language='pl' --fresh-env --write-all"?

No difference in the output.

Trying with changing Dostępność to AVAILABILITY, it may match the reference case-insensitively?

[m-aciek]

Hm, no, that's strange. AVAILABILITY breaks too 🤔 . I've updated all my dependencies recently.

[AA-Turner]

@m-aciek I think I've identified the problem -- you need to add a msgid/msgstr pair to sphinx.po. Without it, I get the errors you observe.

I didn't observe the errors as I was rebuilding with gettext from this branch each time, whereas the python-docs-pl clone used the 3.13 branch rather than this branch.

Cloning python-docs-pl and then adding the below to sphinx.po, I get

msgid "Availability"
msgstr "PL-AVAILABILITY"

[m-aciek]

Thank you for reproducing this. Confirming it works indeed, and the reference link works as intended.

[miss-islington-app]

Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-129584 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-129585 is a backport of this pull request to the 3.12 branch.