make button text translatable#264
Open
sneakers-the-rat wants to merge 1 commit into
Open
Conversation
This was referenced Jul 12, 2026
Closed
chrisjsewell
pushed a commit
that referenced
this pull request
Jul 12, 2026
Builds on the approach from #264: gettext targets only the button text via a translatable inline, so translated button-link/button-ref keep their classes and links (closes #96, #44, #263). Additional hardening and coverage on top of #264: - wrap the translatable placeholder inline in a plain inline, so the reference always retains an element child after sphinx unwraps the placeholder (an unresolved button-ref otherwise crashed the build during reference resolution in translated projects) - this also restores the pre-existing doctree shape (inline wrapper), keeping HTML output identical to previous releases - add gettext extraction regression (pot) and a translated-build round-trip test proving classes/links/refs survive with translated text, for both button types, plus a badge control - align the rst button-link snippet with the myst one (both feed the same regression files) - note: button-ref text is still missing from pot extraction because std-domain xref resolution flattens explicit-title content before the gettext builder extracts; translation itself works (documented in the test, follow-up tracked on the roadmap)
chrisjsewell
pushed a commit
that referenced
this pull request
Jul 12, 2026
Builds on the approach from #264: gettext targets only the button text via a translatable inline, so translated button-link/button-ref keep their classes and links (closes #96, #44, #263). Additional hardening and coverage on top of #264: - wrap the translatable placeholder inline in a plain inline, so the reference always retains an element child after sphinx unwraps the placeholder (an unresolved button-ref otherwise crashed the build during reference resolution in translated projects) - this also restores the pre-existing doctree shape (inline wrapper), keeping HTML output identical to previous releases - add gettext extraction regression (pot) and a translated-build round-trip test proving classes/links/refs survive with translated text, for both button types, plus a badge control - align the rst button-link snippet with the myst one (both feed the same regression files) - note: button-ref text is still missing from pot extraction because std-domain xref resolution flattens explicit-title content before the gettext builder extracts; translation itself works (documented in the test, follow-up tracked on the roadmap)
chrisjsewell
pushed a commit
that referenced
this pull request
Jul 12, 2026
Builds on the approach from #264: gettext targets only the button text via a translatable inline, so translated button-link/button-ref keep their classes and links (closes #96, #44, #263). Additional hardening and coverage on top of #264: - wrap the translatable placeholder inline in a plain inline, so the reference always retains an element child after sphinx unwraps the placeholder (an unresolved button-ref otherwise crashed the build during reference resolution in translated projects) - this also restores the pre-existing doctree shape (inline wrapper), keeping HTML output identical to previous releases - add gettext extraction regression (pot) and a translated-build round-trip test proving classes/links/refs survive with translated text, for both button types, plus a badge control - align the rst button-link snippet with the myst one (both feed the same regression files) - note: button-ref text is still missing from pot extraction because std-domain xref resolution flattens explicit-title content before the gettext builder extracts; translation itself works (documented in the test, follow-up tracked on the roadmap)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fix: #96
After i tried many things, i think i figured out the problem here.
usually references are just on one line in docutils. I noticed that the generated .pot files for buttons were targeting the whole directive, so i believe that when the gettext transform happens, the entire directive is just swapped out for the content of the button.
the fix here is adapted from something i found ctrl+f'ing through the sphinx source code - just explicitly mark the inner text as translatable, adjust the line number by the content offset, and then mark the outer container as not translatable. this seems to work for regular buttons, buttons with options, and buttons whose label text spans multiple lines.
I don't really know the best way to test this - ideally we would test the html output, but i didn't see that done in the tests, so i kept it to just testing the .pot files, but let me know if that's inadequate.