👌 IMPROVE: Add i18n support & general improvements (#66)

* Add i18n support and translations for togglebutton

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.

* Include translation files in package data

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.

* Sync toggle button hints with external state changes

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.

* Preserve existing IDs for admonition toggle items

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.

* Refactor sphinx_togglebutton/__init__.py for readability

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.

* Refactor formatting in setup.py and _convert.py

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.

* Reorder imports for consistency and PEP8 compliance

Imports in setup.py, __init__.py, and _convert.py were reordered to follow PEP8 guidelines and improve readability. No functional changes were made.

* Refactor formatting and remove unused import

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.

* Add i18n support and document toggle button languages

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.

* Specify Sphinx configuration path in readthedocs.yml

Added the 'sphinx.configuration' key to explicitly set the path to the Sphinx config file as 'docs/conf.py' for Read the Docs builds.

* Update changelog with details on toggle hint functions

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.

Author: douden

.gitignore

@@ -52,7 +52,7 @@ coverage.xml
 .pytest_cache/
 
 # Translations
-*.mo
+# *.mo
 *.pot
 
 # Django stuff:

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Support for more languages in toggle button text (see README for full list) [#66](https://github.com/executablebooks/sphinx-togglebutton/pull/66).
+- Added new functions (syncToggleHint, syncAllToggleHints) to dynamically update toggle button hints based on the current state  [#66](https://github.com/executablebooks/sphinx-togglebutton/pull/66). This allows developers to change the open or closed state of an element and have the button hint text update accordingly automatically.
+
+### Fixed
+
+- Update togglebutton.js to use an admonition's existing ID if present, instead of always generating a new one [#66](https://github.com/executablebooks/sphinx-togglebutton/pull/66).
+
 ## v0.3.2 - 2022-07-15
 
 ([full changelog](https://github.com/executablebooks/sphinx-togglebutton/compare/v0.3.1...347b1ad3a093afad0f0d4c0041249f09f39afab2))

MANIFEST.in

@@ -1 +1,9 @@
 graft doc/
+
+recursive-include sphinx_togglebutton *.js
+recursive-include sphinx_togglebutton *.css
+
+recursive-include sphinx_togglebutton *.json
+recursive-include sphinx_togglebutton *.mo
+recursive-include sphinx_togglebutton *.po
+recursive-include sphinx_togglebutton *.py

README.md

@@ -69,3 +69,10 @@ here's a container with an image inside:
 
         .. image:: https://media.giphy.com/media/mW05nwEyXLP0Y/giphy.gif
 ```
+
+Internationalization (i18n)
+============
+
+The texts `Click to hide` and `Click to show` used in the toggle buttons are internationalized by using the set language from Sphinx's configuration.
+
+Supported languages are English (default), Chinese (Simplified), Chinese (Traditional), Hindi, Spanish, French, Arabic, Bengali, Russian, Portuguese, Indonesian, Japanese, German, Korean, Turkish, Vietnamese, Tamil, Italian, Thai, Dutch, Greek, Polish, Ukrainian, Persian, Malay, Swahili, Romanian, Czech, Hungarian, Hebrew, Swedish, and Norwegian.

docs/conf.py

@@ -11,7 +11,12 @@
 
 
 # -- General configuration ---------------------------------------------------
-extensions = ["myst_nb", "sphinx_examples", "sphinx_design", "sphinx_togglebutton"]
+extensions = [
+    "myst_nb",
+    "sphinx_examples",
+    "sphinx_design",
+    "sphinx_togglebutton",
+]
 templates_path = ["_templates"]
 source_suffix = ".rst"
 main_doc = "index"

docs/use.md

@@ -129,7 +129,16 @@ Here is my toggle-able content!
 ## Change the button hint text
 
 You can control the "hint" text that is displayed next to togglebuttons.
-To do so, use the following configuration variable in your `conf.py` file:
+
+To use the default values for your language, set the language in your Sphinx configuration:
+
+```python
+language = "nl"  # or "de", "es", etc.
+```
+
+Supported languages are English (default), Chinese (Simplified), Chinese (Traditional), Hindi, Spanish, French, Arabic, Bengali, Russian, Portuguese, Indonesian, Japanese, German, Korean, Turkish, Vietnamese, Tamil, Italian, Thai, Dutch, Greek, Polish, Ukrainian, Persian, Malay, Swahili, Romanian, Czech, Hungarian, Hebrew, Swedish, and Norwegian.
+
+If you prefer to have custom hint texts instead of the defaults for your language, use the following configuration variable in your `conf.py` file:
 
 ```python
 togglebutton_hint = "Displayed when the toggle is closed."

readthedocs.yml

@@ -1,4 +1,7 @@
 version: 2
+sphinx:
+  # Path to your Sphinx configuration file.
+  configuration: docs/conf.py
 build:
   os: "ubuntu-22.04"
   tools:

setup.py

@@ -1,6 +1,6 @@
-import os
 from pathlib import Path
-from setuptools import setup, find_packages
+
+from setuptools import find_packages, setup
 
 version = [
     line
@@ -24,9 +24,26 @@
     license="MIT License",
     packages=find_packages(),
     package_data={
-        "sphinx_togglebutton": ["_static/togglebutton.css", "_static/togglebutton.js", "_static/togglebutton-chevron.svg"]
+        "sphinx_togglebutton": [
+            "_static/togglebutton.css",
+            "_static/togglebutton.js",
+            "_static/togglebutton-chevron.svg",
+            "translations/README.md",
+            "translations/_convert.py",
+            "translations/jsons/*.json",
+            "translations/locales/**/*",
+        ]
     },
     install_requires=["setuptools", "wheel", "sphinx", "docutils"],
-    extras_require={"sphinx": ["matplotlib", "numpy", "myst_nb", "sphinx_book_theme", "sphinx_design", "sphinx_examples"]},
+    extras_require={
+        "sphinx": [
+            "matplotlib",
+            "numpy",
+            "myst_nb",
+            "sphinx_book_theme",
+            "sphinx_design",
+            "sphinx_examples",
+        ]
+    },
     classifiers=["License :: OSI Approved :: MIT License"],
 )

sphinx_togglebutton/__init__.py

@@ -1,28 +1,44 @@
 """A small sphinx extension to add "toggle" buttons to items."""
+
 import os
-from docutils.parsers.rst import Directive, directives
+
 from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.locale import get_translation
+
+MESSAGE_CATALOG_NAME = "togglebutton"
+translate = get_translation(MESSAGE_CATALOG_NAME)
 
 __version__ = "0.3.2"
 
 
 def st_static_path(app):
-    static_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "_static"))
+    static_path = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "_static")
+    )
     app.config.html_static_path.append(static_path)
 
 
 def initialize_js_assets(app, config):
     # Update the global context
-    app.add_js_file(None, body=f"let toggleHintShow = '{config.togglebutton_hint}';")
-    app.add_js_file(None, body=f"let toggleHintHide = '{config.togglebutton_hint_hide}';")
+
+    app.add_js_file(
+        None, body=f"let toggleHintShow = '{config.togglebutton_hint}';"
+    )
+    app.add_js_file(
+        None, body=f"let toggleHintHide = '{config.togglebutton_hint_hide}';"
+    )
     open_print = str(config.togglebutton_open_on_print).lower()
     app.add_js_file(None, body=f"let toggleOpenOnPrint = '{open_print}';")
     app.add_js_file("togglebutton.js")
 
 
 # This function reads in a variable and inserts it into JavaScript
+
+
 def insert_custom_selection_config(app):
     # This is a configuration that you've specified for users in `conf.py`
+
     selector = app.config["togglebutton_selector"]
     js_text = "var togglebuttonSelector = '%s';" % selector
     app.add_js_file(None, body=js_text)
@@ -42,28 +58,45 @@ def run(self):
         classes = ["toggle"]
         if "show" in self.options:
             classes.append("toggle-shown")
-
         parent = nodes.container(classes=classes)
         self.state.nested_parse(self.content, self.content_offset, parent)
         return [parent]
 
 
 # We connect this function to the step after the builder is initialized
+
+
 def setup(app):
+    # add translations
+
+    package_dir = os.path.abspath(os.path.dirname(__file__))
+    locale_dir = os.path.join(package_dir, "translations", "locales")
+    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+
     # Add our static path
+
     app.connect("builder-inited", st_static_path)
 
     # Add relevant code to headers
+
     app.add_css_file("togglebutton.css")
 
     # Add the string we'll use to select items in the JS
     # Tell Sphinx about this configuration variable
-    app.add_config_value("togglebutton_selector", ".toggle, .admonition.dropdown", "html")
-    app.add_config_value("togglebutton_hint", "Click to show", "html")
-    app.add_config_value("togglebutton_hint_hide", "Click to hide", "html")
+
+    app.add_config_value(
+        "togglebutton_selector", ".toggle, .admonition.dropdown", "html"
+    )
+    app.add_config_value(
+        "togglebutton_hint", f"{translate('Click to show')}", "html"
+    )
+    app.add_config_value(
+        "togglebutton_hint_hide", f"{translate('Click to hide')}", "html"
+    )
     app.add_config_value("togglebutton_open_on_print", True, "html")
 
     # Run the function after the builder is initialized
+
     app.connect("builder-inited", insert_custom_selection_config)
     app.connect("config-inited", initialize_js_assets)
     app.add_directive("toggle", Toggle)

sphinx_togglebutton/_static/togglebutton.js

@@ -17,8 +17,13 @@ var initToggleItems = () => {
   itemsToToggle.forEach((item, index) => {
     if (item.classList.contains("admonition")) {
       // If it's an admonition block, then we'll add a button inside
-      // Generate unique IDs for this item
-      var toggleID = `toggle-${index}`;
+      // Generate unique IDs for this item,
+      // IF AND ONLY IF THE ITEM DOESN'T ALREADY HAVE AN ID
+      if (!item.id) {
+        var toggleID = `toggle-${index}`;
+      } else {
+        var toggleID = item.id;
+      }
       var buttonID = `button-${toggleID}`;
 
       item.setAttribute("id", toggleID);
@@ -123,6 +128,25 @@ var toggleHidden = (button) => {
   }
 };
 
+// Function to synchronize the data-toggle-hint with the current state
+var syncToggleHint = (button) => {
+  const target = button.dataset["target"];
+  const itemToToggle = document.getElementById(target);
+  
+  if (itemToToggle && itemToToggle.classList.contains("toggle-hidden")) {
+    button.dataset.toggleHint = toggleHintShow;
+    button.setAttribute("aria-expanded", false);
+  } else if (itemToToggle) {
+    button.dataset.toggleHint = toggleHintHide;
+    button.setAttribute("aria-expanded", true);
+  }
+};
+
+// Function to sync all toggle buttons - can be called by external extensions
+var syncAllToggleHints = () => {
+  document.querySelectorAll('.toggle-button').forEach(syncToggleHint);
+};
+
 var toggleClickHandler = (click) => {
   // Be cause the admonition title is clickable and extends to the whole admonition
   // We only look for a click event on this title to trigger the toggle.
@@ -170,6 +194,33 @@ const sphinxToggleRunWhenDOMLoaded = (cb) => {
 sphinxToggleRunWhenDOMLoaded(addToggleToSelector);
 sphinxToggleRunWhenDOMLoaded(initToggleItems);
 
+// Set up MutationObserver to watch for external changes to toggle states
+sphinxToggleRunWhenDOMLoaded(() => {
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
+        const target = mutation.target;
+        // Check if this is a toggle item that had its class changed
+        if (target.classList.contains('toggle')) {
+          // Find the associated toggle button and sync its hint
+          const button = target.querySelector('.toggle-button');
+          if (button) {
+            syncToggleHint(button);
+          }
+        }
+      }
+    });
+  });
+
+  // Start observing class changes on all toggle elements
+  document.querySelectorAll('.toggle').forEach((toggleElement) => {
+    observer.observe(toggleElement, {
+      attributes: true,
+      attributeFilter: ['class']
+    });
+  });
+});
+
 /** Toggle details blocks to be open when printing */
 if (toggleOpenOnPrint == "true") {
   window.addEventListener("beforeprint", () => {