Add i18n support for exercise and solution labels by douden · Pull Request #75 · executablebooks/sphinx-exercise

douden · 2025-07-30T13:19:39Z

This PR references and solves issue #73.
Closes #73

This pull request introduces internationalization (i18n) support for the sphinx_exercise extension, enabling translations for exercise-related text. It includes changes to add translation files, update the codebase to use translatable strings, and provide a mechanism for compiling and managing translation files.

Internationalization Support:

Added translation infrastructure:
- Introduced MESSAGE_CATALOG_NAME and get_translation for retrieving localized strings in sphinx_exercise/__init__.py, directive.py, and nodes.py. [1] [2] [3]
- Updated default titles and labels to use translatable strings (e.g., "Exercise" and "Solution to"). [1] [2] [3] [4] [5]
- Registered translation message catalogs and locale directories in the setup function.
Added translation files:
- Created JSON files for translations of "Exercise" and "Solution to" in multiple languages. [1] [2]
- Added .po files for supported languages in the translations/locales directory. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

Translation Management:

Added a script (_convert.py) to convert JSON translation files into .po and .mo files for use in the extension. The script handles file creation, updates, and compilation.
Documented the translation process in a new README.md file within the translations directory.

Packaging Updates:

Updated MANIFEST.in to include translation files and other necessary assets in the package distribution.

Introduces internationalization for 'Exercise' and 'Solution to' labels using Sphinx's message catalog system. Adds translation JSONs, conversion script, and locale files for multiple languages. Updates code to use translated labels and registers message catalog in Sphinx extension setup.

Changed the project name to 'teachbooks-sphinx-exercise' and updated the description to indicate this is a TeachBooks temporary version. Added a new author to the authors list.

Removed the old CI workflow and introduced a new Python publishing workflow for building, publishing, and signing releases. Added initial files for Dutch translation tests under the tests/books/test-dutch directory.

Added [tool.hatch.build.targets.wheel] section to specify the package directory for building wheels, ensuring correct packaging of 'src/sphinx_exercise'.

Renamed all occurrences of the 'sphinx_exercise' package to 'teachbooks_sphinx_exercise', including source files, assets, translations, and configuration in pyproject.toml. Updated optional dependencies and version path in pyproject.toml to reflect the new package name.

This reverts commit b56c535.

This reverts commit 71ffa4a.

This reverts commit e72061c.

This reverts commit 2dab815.

Copilot

Pull Request Overview

This PR introduces internationalization (i18n) support for the sphinx_exercise extension, enabling translations of "Exercise" and "Solution to" labels across 21 languages. The implementation uses Sphinx's built-in translation infrastructure with .po and .mo files.

Key changes:

Added translation infrastructure using Sphinx's get_translation API
Created translation files (.po) for 21 languages with corresponding JSON source files
Implemented a conversion script to generate .po/.mo files from JSON translations

Reviewed Changes

Copilot reviewed 28 out of 48 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
sphinx_exercise/init.py	Registers message catalog and locale directory; uses translated strings for numfig format
sphinx_exercise/directive.py	Updates default title text to use translated strings
sphinx_exercise/nodes.py	Modifies title validation to check against translated strings
sphinx_exercise/translations/_convert.py	Provides script to convert JSON translations to .po/.mo files
sphinx_exercise/translations/README.md	Documents the translation conversion process
sphinx_exercise/translations/jsons/*.json	Source translation data for Exercise and Solution labels
sphinx_exercise/translations/locales/*/LC_MESSAGES/exercise.po	Generated .po files for 21 languages
MANIFEST.in	Includes translation files in package distribution

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-21T00:08:28Z

sphinx_exercise/translations/_convert.py

+def convert_json(folder=None):
+    folder = folder or Path(__file__).parent
+
+    # remove exising


Corrected spelling of 'exising' to 'existing'.

Suggested change

# remove exising

# remove existing

Copilot · 2025-10-21T00:08:28Z

sphinx_exercise/nodes.py

    def default_title(self):
        title_text = self.children[0].astext()
-        if title_text == "Exercise" or title_text == "Exercise %s":
+        if title_text == f"{translate('Exercise')}" or title_text == f"{translate('Exercise')} %s":


The f-string formatting is unnecessary when wrapping a single function call. The code can be simplified to if title_text == translate('Exercise') or title_text == f"{translate('Exercise')} %s": for better readability.

Suggested change

if title_text == f"{translate('Exercise')}" or title_text == f"{translate('Exercise')} %s":

if title_text == translate('Exercise') or title_text == translate('Exercise') + " %s":

Copilot · 2025-10-21T00:08:28Z

sphinx_exercise/nodes.py

    def default_title(self):
        title_text = self.children[0].astext()
-        if title_text == "Solution to":
+        if title_text == f"{translate('Solution to')}":


The f-string formatting is unnecessary when wrapping a single function call. The code can be simplified to if title_text == translate('Solution to'): for better readability.

Suggested change

if title_text == f"{translate('Solution to')}":

if title_text == translate('Solution to'):

Copilot · 2025-10-21T00:08:29Z

sphinx_exercise/directive.py


    def run(self) -> List[Node]:
-        self.defaults = {"title_text": "Exercise"}
+        self.defaults = {"title_text": f"{translate('Exercise')}"}


The f-string formatting is unnecessary when wrapping a single function call. The code can be simplified to self.defaults = {"title_text": translate('Exercise')} for better readability.

Suggested change

self.defaults = {"title_text": f"{translate('Exercise')}"}

self.defaults = {"title_text": translate('Exercise')}

Copilot · 2025-10-21T00:08:29Z

sphinx_exercise/directive.py


    def run(self) -> List[Node]:
-        self.defaults = {"title_text": "Solution to"}
+        self.defaults = {"title_text": f"{translate('Solution to')}"}


The f-string formatting is unnecessary when wrapping a single function call. The code can be simplified to self.defaults = {"title_text": translate('Solution to')} for better readability.

Suggested change

self.defaults = {"title_text": f"{translate('Solution to')}"}

self.defaults = {"title_text": translate('Solution to')}

Copilot · 2025-10-21T00:08:29Z

sphinx_exercise/__init__.py


    config["numfig"] = True
-    numfig_format = {"exercise": "Exercise %s"}
+    numfig_format = {"exercise": f"{translate('Exercise')} %s"}


The f-string can be simplified by removing unnecessary braces. Change to numfig_format = {"exercise": f"{translate('Exercise')} %s"} or use string concatenation: numfig_format = {"exercise": translate('Exercise') + " %s"} for better readability.

Suggested change

numfig_format = {"exercise": f"{translate('Exercise')} %s"}

numfig_format = {"exercise": translate('Exercise') + " %s"}

mmcky · 2025-10-21T00:10:03Z

Thanks @douden -- this is a great addition to this extension. Again apologies for the delay in review, appreciate the contribution.

I have done some local testing and it is looking pretty good on my end, I will take a look at the copilot review as a final check.

I will add a few languages, but I will do that in a separate PR.

mmcky · 2025-10-21T00:11:29Z

Actually I just realised this is from a fork @douden so those suggestions can't be easily committed unless you do so upstream. I will include some of them in a new PR.

douden added 9 commits July 30, 2025 14:41

Update project name and metadata in pyproject.toml

2dab815

Changed the project name to 'teachbooks-sphinx-exercise' and updated the description to indicate this is a TeachBooks temporary version. Added a new author to the authors list.

Replace CI workflow and add Dutch translation tests

e72061c

Removed the old CI workflow and introduced a new Python publishing workflow for building, publishing, and signing releases. Added initial files for Dutch translation tests under the tests/books/test-dutch directory.

Configure wheel build package path for Hatch

71ffa4a

Added [tool.hatch.build.targets.wheel] section to specify the package directory for building wheels, ensuring correct packaging of 'src/sphinx_exercise'.

Revert "Rename package to teachbooks_sphinx_exercise"

4e6acbc

This reverts commit b56c535.

Revert "Configure wheel build package path for Hatch"

6b4548b

This reverts commit 71ffa4a.

Revert "Replace CI workflow and add Dutch translation tests"

3c6c876

This reverts commit e72061c.

Revert "Update project name and metadata in pyproject.toml"

d27e055

This reverts commit 2dab815.

mmcky requested a review from Copilot October 21, 2025 00:07

Copilot AI reviewed Oct 21, 2025

View reviewed changes

mmcky merged commit 568df6c into executablebooks:main Oct 21, 2025

This was referenced Oct 21, 2025

[ENH] Patch translations #42

Closed

Add ability to change exercise-title and solution-title from conf.py … #74

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add i18n support for exercise and solution labels#75

Add i18n support for exercise and solution labels#75
mmcky merged 9 commits intoexecutablebooks:mainfrom
TeachBooks:main

douden commented Jul 30, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

Copilot AI Oct 21, 2025

Uh oh!

mmcky commented Oct 21, 2025

Uh oh!

mmcky commented Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	if title_text == f"{translate('Exercise')}" or title_text == f"{translate('Exercise')} %s":
	if title_text == translate('Exercise') or title_text == translate('Exercise') + " %s":

	if title_text == f"{translate('Solution to')}":
	if title_text == translate('Solution to'):

	self.defaults = {"title_text": f"{translate('Exercise')}"}
	self.defaults = {"title_text": translate('Exercise')}

	numfig_format = {"exercise": f"{translate('Exercise')} %s"}
	numfig_format = {"exercise": translate('Exercise') + " %s"}

Conversation

douden commented Jul 30, 2025

Internationalization Support:

Translation Management:

Packaging Updates:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

mmcky commented Oct 21, 2025

Uh oh!

mmcky commented Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants