gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

m-aciek · 2025-02-02T20:54:51Z

Localizes platform support lists using Babel's format_list().
Exposes translation phrase not {platform} and fetches its translation in the availability directive content. This will allow full translations of availability directive content.
Renders text-based greater-than or equal-to sing >= as UTF-8 ≥.

Tested locally, both make gettext (exposes new phrase in sphinx.pot) and rendering with make html. Examples of renderings:

library/os.rst:2311

original:

Traditional Chinese:

Polish:

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

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

AA-Turner · 2025-02-02T23:22:01Z

Doc/tools/extensions/availability.py

@@ -68,14 +69,17 @@ def run(self) -> list[nodes.container]:
            refwarn=True,
        )
        sep = nodes.Text(": ")
-        parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno)


It is somewhat surprising that this doesn't work, as sphinx.util.nodes.extract_messages() should pick up the rawsource attributes -- we shouldn't need to parse & reparse.

Even when I've added not WASI, not Android. translation string by hand, it wasn't picked up in the build process.

tomasr8 · 2025-02-02T23:33:04Z

Doc/tools/extensions/availability.py

-        parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno)
+        platforms = self.parse_platforms()
+        platforms_text = (
+            f"{', '.join(starmap(_print_platform, platforms.items()))}."


Not sure if babel is available here, but format_list might be a better option?

Babel is Sphinx's dependency, it is available. Thank you for the suggestion, I've added it.

StanFromIreland

Other than my little nitpick it looks very good!

StanFromIreland · 2025-02-03T09:45:13Z

Doc/tools/extensions/availability.py

+        return platform
+    if not version:
+        return sphinx_gettext("not {platform}").format(platform=platform)
+    return f"{platform} ≥ {version}"


Suggested change

return f"{platform} ≥ {version}"

return f"{platform} >= {version}"

How well supported is "≥"? Does it render well in pdf outputs?

@AA-Turner could you please advise, is there some direct way to recognize epub build in the directive code and fallback to >=? Or should I rather drop the UTF-8 character from here?

I find no mention of using "≥" or ">=" for versions in the Google, Microsoft and Apple style guides, and they say to use words such as "Use version 2.2 or later" and not "Use version 2.2 or higher":

https://developers.google.com/style/word-list#later

https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/l/later

https://support.apple.com/en-gb/guide/applestyleguide/apsg51b3c806/web

I agree with @hugovk . This again will require translation.

I will add that >= is currently used.

https://developers.google.com/style/word-list#later

I find Google's style guide contradictory 🤔

A release with the highest version number might not be the latest version. For example, if version 2.0 of an operating system receives a bug-fix update after version 3.0 has been released, then version 2.0.1 might be the latest version, even though its version number is lower than 3.0.

In this meaning we rather want to express "higher" than "later". And later they recommend higher in Android docs. I've filed a feedback to this section.

I agree that the written form may be easier to read than the symbolic one. Though ≥ seems to be inambiguous, contrary to “later”.

I will add that >= is currently used.

I wonder what should be the approach, if we decide to use "Linux 2.6.27 or later", should we rewrite also the availability directives content in .rsts? Or introduce a simplified "syntax", that will be rendered to "or later" from a ">=" specificator? That may be confusing to docs editors. (?)

If we choose to use words, I'd rewrite the existing ">=" to avoid problems/confusion by automation changing things in unexpected ways.

We discussed this in this month's docs workgroup meeting: let's keep the directives compact; they're not prose, and use the single symbol. The Unicode symbol was introduced in 1993, hopefully it renders well on near anything. If there's an issue with Unicode in some of the backends (such as man pages), we should fix that.

(Minutes will appear at https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html in the near future.)

hugovk · 2025-02-03T15:00:31Z

Doc/tools/extensions/availability.py

+        return platform
+    if not version:
+        return sphinx_gettext("not {platform}").format(platform=platform)
+    return f"{platform} ≥ {version}"


I find no mention of using "≥" or ">=" for versions in the Google, Microsoft and Apple style guides, and they say to use words such as "Use version 2.2 or later" and not "Use version 2.2 or higher":

https://developers.google.com/style/word-list#later

https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/l/later

https://support.apple.com/en-gb/guide/applestyleguide/apsg51b3c806/web

Doc/tools/extensions/availability.py

Co-authored-by: Hugo van Kemenade <[email protected]>

AA-Turner · 2025-02-04T09:44:38Z

It would be good to properly investigate why the gettext builder is not picking up the raw text here. In the other part of #126609, there was a fairly simple resolution instead of a partial revert -- the PR as it stands now is duplicative, parsing and re-creating the text provided to the directive, whereas currently we just validate that it is correct. If we fix the source text being picked up by gettext, it would also mean that we don't need babel.lists, as translators can simply translate the source text naturally. As such, I've added the DO-NOT-MERGE label for the time being.

A

m-aciek · 2025-02-19T14:22:18Z

I'm convinced that we should translate the full text, instead of building it from fragments (vide Prefer WET over DRY for i18n). Therefore I will close this PR. I didn't yet succeed with the correct solution. I will try to write my findings in related discussion thread soon https://github.com/orgs/sphinx-doc/discussions/13280.

m-aciek added 2 commits February 2, 2025 21:45

Docs: allow translation of a phrase in availability directive

a2399c0

Use greater-than or equal-to character

8de15ea

m-aciek requested review from AA-Turner and hugovk as code owners February 2, 2025 20:54

bedevere-app bot added the awaiting review label Feb 2, 2025

m-aciek changed the title ~~Docs: allow translation of a phrase in the availability directive~~ Docs: allow translation of a phrase in the availability directive, use ge operator character Feb 2, 2025

m-aciek changed the title ~~Docs: allow translation of a phrase in the availability directive, use ge operator character~~ Docs: allow translation of a phrase, use ge operator character in the availability directive Feb 2, 2025

m-aciek added 2 commits February 3, 2025 00:03

Refactor: move helper function down

c9ee08d

Fix type annotations

88a9a9e

AA-Turner reviewed Feb 2, 2025

View reviewed changes

AA-Turner added the skip news label Feb 2, 2025

AA-Turner changed the title ~~Docs: allow translation of a phrase, use ge operator character in the availability directive~~ gh-126609: allow translation of a phrase, use ge operator character in the availability directive Feb 2, 2025

bedevere-app bot mentioned this pull request Feb 2, 2025

Availability extension's text translation breaks directive rendering #126609

Closed

tomasr8 reviewed Feb 2, 2025

View reviewed changes

Use Babel's format_list()

e6fe49e

m-aciek changed the title ~~gh-126609: allow translation of a phrase, use ge operator character in the availability directive~~ gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive Feb 3, 2025

StanFromIreland approved these changes Feb 3, 2025

View reviewed changes

bedevere-app bot added awaiting core review and removed awaiting review labels Feb 3, 2025

hugovk reviewed Feb 3, 2025

View reviewed changes

m-aciek and others added 2 commits February 3, 2025 22:40

Rename _print_platform() to _format_platform()

2cb41d9

Co-authored-by: Hugo van Kemenade <[email protected]>

Rename formatting function in a call

f273e6e

Co-authored-by: Hugo van Kemenade <[email protected]>

AA-Turner added the DO-NOT-MERGE label Feb 4, 2025

m-aciek marked this pull request as draft February 4, 2025 14:26

bedevere-app bot removed the awaiting core review label Feb 4, 2025

m-aciek closed this Feb 19, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

m-aciek commented Feb 2, 2025 •

edited

Loading

AA-Turner Feb 2, 2025

m-aciek Feb 3, 2025 •

edited

Loading

tomasr8 Feb 2, 2025

m-aciek Feb 3, 2025

StanFromIreland left a comment

StanFromIreland Feb 3, 2025

StanFromIreland Feb 3, 2025

m-aciek Feb 3, 2025 •

edited

Loading

hugovk Feb 3, 2025

StanFromIreland Feb 3, 2025

StanFromIreland Feb 3, 2025

m-aciek Feb 3, 2025 •

edited

Loading

hugovk Feb 4, 2025

hugovk Feb 4, 2025

hugovk Feb 3, 2025

AA-Turner commented Feb 4, 2025

m-aciek commented Feb 19, 2025

	return f"{platform} ≥ {version}"
	return f"{platform} >= {version}"

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

Conversation

m-aciek commented Feb 2, 2025 • edited Loading

Choose a reason for hiding this comment

m-aciek Feb 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StanFromIreland left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-aciek Feb 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-aciek Feb 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AA-Turner commented Feb 4, 2025

m-aciek commented Feb 19, 2025

m-aciek commented Feb 2, 2025 •

edited

Loading

m-aciek Feb 3, 2025 •

edited

Loading

m-aciek Feb 3, 2025 •

edited

Loading

m-aciek Feb 3, 2025 •

edited

Loading