Add i18n support & general improvements#66
Merged
douden merged 11 commits intoexecutablebooks:masterfrom Jan 14, 2026
Merged
Conversation
Introduces internationalization for Sphinx-ToggleButton by adding translation infrastructure, updating config values to use translated strings, and including translation files (.json, .po, .mo) for multiple languages. Updates MANIFEST.in to package translation assets and adjusts .gitignore to allow .mo files. Also adds a conversion script for generating locale files from JSON.
Added translation-related files and directories to the package_data section in setup.py to ensure they are included in the distribution. This supports proper packaging and deployment of translation resources.
Adds functions to synchronize toggle button hints and aria-expanded attributes with the current state. Introduces a MutationObserver to update button hints when toggle item classes change, ensuring external extensions or DOM changes are reflected in the UI.
Update togglebutton.js to use an admonition's existing ID if present, instead of always generating a new one. This prevents overwriting custom or pre-existing IDs on admonition elements.
Improved code formatting and structure for better readability and maintainability. Added blank lines for separation, split long function calls, and enhanced consistency in function definitions and configuration setup.
Improves code readability by reformatting lists and dictionary values in setup.py and breaking up a long path assignment in _convert.py. No functional changes were made.
Imports in setup.py, __init__.py, and _convert.py were reordered to follow PEP8 guidelines and improve readability. No functional changes were made.
Reformatted code for better readability in docs/conf.py and sphinx_togglebutton/__init__.py by expanding lists and function calls over multiple lines. Removed unused 'os' import from setup.py.
Updated CHANGELOG, README, and docs to document new internationalization support for toggle button texts. Added a list of supported languages and instructions for configuring language in Sphinx. Also mentioned new functions for dynamic hint updates and a fix for using existing admonition IDs.
Added the 'sphinx.configuration' key to explicitly set the path to the Sphinx config file as 'docs/conf.py' for Read the Docs builds.
Tom-van-Woudenberg
requested changes
Jan 14, 2026
There was a problem hiding this comment.
Could we handle all the .mo and .po similarly as here: https://github.com/executablebooks/sphinx-book-theme/tree/master/src/sphinx_book_theme/assets/translations?
Contributor
Author
Currently the setup is the same as for https://github.com/executablebooks/sphinx-proof, so for now let's leave this as is. |
Expanded the changelog entry for syncToggleHint and syncAllToggleHints to clarify that these functions allow automatic updating of button hint text when the open or closed state changes.
Tom-van-Woudenberg
approved these changes
Jan 14, 2026
Tom-van-Woudenberg
left a comment
Tom-van-Woudenberg
left a comment
There was a problem hiding this comment.
Tested locally in a dutch book, works perfectly!
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
2 participants
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.
This PR references and solves issue #22.
Closes #22
This pull request introduces internationalization (i18n) support for the
sphinx_togglebuttonpackage, enabling translations for toggle button text, and adds functionality to dynamically synchronize toggle states in the DOM. The most important changes include adding translation infrastructure, updating configuration to support translations, and enhancing JavaScript functionality for better toggle state management.Internationalization (i18n) Support:
.poand.moformats for multiple languages, along with JSON source files (sphinx_togglebutton/translations/jsons/*.json) and a script (_convert.py) to convert JSON to.poand.mofiles. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15]setup.pyto include translation-related files in the package distribution.sphinx_togglebutton/__init__.pyto integrate Sphinx's translation system and register the message catalog. [1] [2]JavaScript Enhancements:
syncToggleHint,syncAllToggleHints) to dynamically update toggle button hints based on the current state. This allows developers to change the open or closed state of an element and have the button hint text update accordingly automatically.MutationObserverto monitor changes in toggle states and synchronize button hints accordingly.Packaging and Manifest Updates:
MANIFEST.into include translation-related files and directories in the source distribution.