enable sphinx-i18n

Author: vke

.gitignore

@@ -65,3 +65,8 @@ genrst/
 stderr-ldview
 stdout-ldview
 LPub3D/
+
+# Translation files
+######################
+doc/locales/pot/
+*.mo

CONTRIBUTING.md

@@ -149,6 +149,47 @@ Build docs:
     poetry run doc\make.bat html
     Invoke-Item doc\main\build\html\index.html
 
+Translations:
+
+The documentation supports multiple languages through Sphinx's internationalization (i18n) feature.
+
+Directory structure:
+- `doc/locales/pot/` - Contains template (.pot) files generated by `make gettext`. These files contain all original strings that need to be translated.
+- `doc/locales/<language>/LC_MESSAGES/` - Contains translation (.po) files for each language. These files must be directly in the LC_MESSAGES directory (not in subdirectories) and contain the actual translations that will be used to build the documentation.
+
+Note about translations:
+The translation system uses unique IDs (UUIDs) for each translatable string. This ensures that translations are preserved even if you move text to different files or lines. The source file locations are included as comments in the .po files to help track where translations are used.
+
+Translation files:
+- `.po` files are human-readable text files containing the translations. These should be committed to the repository.
+- `.mo` files are compiled binary versions of .po files, generated automatically during build. These should not be committed.
+
+To work with translations:
+
+1. Generate translation templates:
+
+       poetry run make -C doc gettext
+
+   This creates .pot template files in `doc/locales/pot/`
+
+2. Initialize or update a language (e.g., German 'de'):
+
+       poetry run make -C doc update-po-de
+
+   This creates or updates .po files in `doc/locales/de/LC_MESSAGES/`
+
+3. Edit the .po files in `doc/locales/<language>/LC_MESSAGES/` to add translations
+
+4. Build documentation for a specific language:
+
+       poetry run make -C doc html-de    # For German
+       poetry run make -C doc html-fr    # For French
+       poetry run make -C doc html-ja    # For Japanese
+
+When adding translations to the repository:
+- Commit the .po files in `doc/locales/<language>/LC_MESSAGES/`
+- Do not commit the .pot files in `doc/locales/pot/` (these are generated files)
+
 Building IDE docs variant:
 
     # Linux/macOS

doc/Makefile

@@ -8,6 +8,7 @@ SPHINXPROJ    = Pybricks
 SOURCEDIR     = main
 BUILDDIR      = "$(SOURCEDIR)"/build
 TAG           = main
+LOCALEDIR     = locales
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -19,7 +20,19 @@ diagrams:
 	@$(MAKE) -C "$(SOURCEDIR)"/diagrams_source clean
 	@$(MAKE) -C "$(SOURCEDIR)"/diagrams_source
 
+# i18n targets
+gettext:
+	@$(SPHINXBUILD) -b gettext "$(SOURCEDIR)" "$(LOCALEDIR)/pot" -D gettext_compact=0 $(SPHINXOPTS) -t $(TAG) $(O)
+
+update-po-%:
+	@sphinx-intl update -p "$(LOCALEDIR)/pot" -l $*
+
+html-%:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/$*" $(SPHINXOPTS) -t $(TAG) -D language=$* $(O)
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)
+
+.PHONY: gettext update-po-% html-%

doc/main/conf.py

@@ -53,6 +53,14 @@
     extensions.append("sphinx.ext.imgmath")  # noqa F821
     html_theme_options["prev_next_buttons_location"] = None  # noqa F821
 
+# Internationalization configuration
+language = 'en'
+locale_dirs = ['../locales']   # path relative to conf.py location
+gettext_compact = False        # optional
+gettext_uuid = True            # Use UUIDs to preserve translations when text moves
+gettext_location = True        # Include locations as comments for reference
+gettext_additional_targets = ['literal-block', 'image']  # Also translate code blocks and image captions
+
 # Build hub specific example scripts.
 sys.path.append(os.path.abspath("../../examples/pup/hub_common"))
 import make_examples  # noqa F401, E402

pyproject.toml

@@ -36,6 +36,7 @@ flake8 = "^4.0"
 [tool.poetry.group.doc.dependencies]
 Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "cd277d09" }
 sphinx-rtd-theme = "^1.0.0"
+sphinx-intl = "^2.1.0"
 toml = "^0.10.0"
 
 [build-system]