Add internationalization (i18n) support for 27 languages

.github/copilot-instructions.md

@@ -0,0 +1,73 @@
+# Copilot Instructions for sphinx-exercise
+
+## General Guidelines
+
+### Code Philosophy
+- **Simplicity First**: Pursue simple code with low complexity when making changes
+- **Maintainability**: Keep code modular and easy to understand
+- **Minimal Dependencies**: Avoid adding unnecessary dependencies
+
+### Documentation Standards
+- **Do NOT create summary documents** when making changes
+- Instead, **update existing documents** where needed (README.md, docs/, etc.)
+- Keep documentation in sync with code changes
+
+### Release Management
+- **Review Documentation**: Before making any releases, please review all documentation in `docs/`
+- **Update CHANGELOG.md**: Keep the CHANGELOG.md up to date with all significant changes
+- **Release Notes**: Maintain detailed release information in `docs/releases/`
+- Follow semantic versioning principles
+
+### Release Information Structure
+Release documentation should be maintained in `docs/releases/` with the following structure:
+- One file per version (e.g., `v0.5.0.md`)
+- Link to releases from main documentation
+- Include migration guides for breaking changes
+
+## Project-Specific Guidelines
+
+### Internationalization (i18n)
+- Translation files are located in `sphinx_exercise/translations/`
+- JSON source files: `sphinx_exercise/translations/jsons/`
+- Compiled locale files: `sphinx_exercise/translations/locales/`
+- Use `_convert.py` to regenerate locale files from JSON sources
+- When adding new languages:
+  1. Add translations to both `Exercise.json` and `Solution.json`
+  2. Run `python sphinx_exercise/translations/_convert.py` to generate `.po` and `.mo` files
+  3. Update documentation to mention new language support
+
+### Testing
+- All changes should include appropriate tests
+- Test files are in `tests/` directory
+- Run tests before committing changes
+- Maintain test coverage
+
+### Code Structure
+- Main extension code: `sphinx_exercise/`
+- Directives: `directive.py`
+- Transforms: `transforms.py` and `post_transforms.py`
+- LaTeX support: `latex.py`
+- Node definitions: `nodes.py`
+
+### Documentation
+- Main docs: `docs/source/`
+- Build docs locally before committing documentation changes
+- Ensure all examples work correctly
+- Update syntax documentation when adding new features
+
+## Workflow
+
+1. **Before Starting**: Review relevant existing code and documentation
+2. **During Development**:
+   - Write simple, clear code
+   - Update tests as needed
+   - Update existing documentation inline
+3. **Before Committing**:
+   - Run tests
+   - Review documentation changes
+   - Update CHANGELOG.md if applicable
+4. **Before Releasing**:
+   - Review all documentation in `docs/`
+   - Create release notes in `docs/releases/`
+   - Update CHANGELOG.md
+   - Verify all tests pass

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [v1.1.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.1.0) (TBD)
+
+### New ✨
+
+- Added internationalization (i18n) support for 27 languages
+- Added translations for Chinese, Japanese, Korean, Arabic, Hindi, Turkish, and expanded existing language support
+- Extension now automatically detects Sphinx project language setting and displays appropriate translations
+
+### Improved 👌
+
+- Reorganized and expanded translation files with alphabetical sorting
+- Enhanced translation documentation with comprehensive guides
+- Updated README and documentation to highlight internationalization features
+
+### Documentation 📚
+
+- Added internationalization section to syntax documentation
+- Updated README with i18n feature highlights
+- Improved translation README with detailed contribution guidelines
+- Created releases documentation structure in `docs/releases/`
+- Added Copilot instructions for project maintenance
+
+
+## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-XX-XX)
+
+_No changelog available for this version._
 
 ## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-07-01)
 

README.md

@@ -9,6 +9,14 @@
 This package contains a [Sphinx](http://www.sphinx-doc.org/en/master/) extension
 for producing exercise and solution directives.
 
+## Features
+
+- **Automatic numbering** for exercises and solutions
+- **Cross-referencing** support with `ref` and `numref` roles
+- **Internationalization** support for 27 languages including Chinese, Japanese, Korean, Arabic, Hindi, and more
+- **HTML and PDF** output support
+- **Gated directive** syntax for including executable code and complex content
+- **Customizable styling** with class options and hidden directive support
 
 ## Get started
 

RELEASE.md

@@ -0,0 +1,109 @@
+# Release Checklist for v1.1.0
+
+This document provides the step-by-step process to release version 1.1.0 of sphinx-exercise.
+
+## Pre-Release Checklist
+
+- [ ] All tests pass locally
+- [ ] All tests pass on CI
+- [ ] Documentation builds successfully
+- [ ] CHANGELOG.md is up to date with release date
+- [ ] Version number updated in `sphinx_exercise/__init__.py`
+- [ ] Release notes finalized in `docs/source/releases/v1.1.0.md`
+- [ ] All PRs for this release are merged
+
+## Version Update
+
+Update the version number in:
+
+1. **`sphinx_exercise/__init__.py`**:
+   ```python
+   __version__ = "1.1.0"
+   ```
+
+2. **`CHANGELOG.md`**:
+   - Replace `(TBD)` with the actual release date
+   - Change link to point to the release tag
+
+## Release Steps
+
+### 1. Create Release Commit
+
+```bash
+# Ensure you're on main branch and up to date
+git checkout main
+git pull origin main
+
+# Update version in __init__.py
+# Update CHANGELOG.md with release date
+# Commit changes
+git add sphinx_exercise/__init__.py CHANGELOG.md docs/source/releases/v1.1.0.md
+git commit -m "Release v1.1.0"
+```
+
+### 2. Create Git Tag
+
+```bash
+git tag -a v1.1.0 -m "Release version 1.1.0 - Internationalization support"
+```
+
+### 3. Push to GitHub
+
+```bash
+git push origin main
+git push origin v1.1.0
+```
+
+### 4. Create GitHub Release
+
+1. Go to https://github.com/executablebooks/sphinx-exercise/releases/new
+2. Select tag: `v1.1.0`
+3. Release title: `v1.1.0 - Internationalization Support`
+4. Description: Copy content from `docs/source/releases/v1.1.0.md`
+5. Click "Publish release"
+
+### 5. Publish to PyPI
+
+```bash
+# Clean previous builds
+rm -rf dist/ build/ *.egg-info
+
+# Build distribution
+python -m build
+
+# Upload to PyPI (requires PyPI credentials)
+python -m twine upload dist/*
+```
+
+### 6. Update Documentation
+
+The documentation should automatically build from the new tag on ReadTheDocs. Verify at:
+https://ebp-sphinx-exercise.readthedocs.io/en/latest/
+
+### 7. Post-Release
+
+1. Update `docs/source/releases/index.md` to include v1.1.0
+2. Create new "Unreleased" section in CHANGELOG.md for future changes
+3. Announce release on relevant channels
+
+## Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for new functionality in a backward compatible manner (this release)
+- **PATCH** version for backward compatible bug fixes
+
+## Release Highlights for Announcement
+
+**sphinx-exercise v1.1.0** is now available! 🎉
+
+This release adds comprehensive internationalization support:
+- ✨ Support for 27 languages including Chinese, Japanese, Korean, Arabic, and Hindi
+- 🌍 Automatic language detection from Sphinx configuration
+- 📚 Enhanced documentation with i18n examples and contribution guides
+- 🛠️ JSON-based translation system for easy community contributions
+
+Install or upgrade: `pip install --upgrade sphinx-exercise`
+
+Full release notes: https://github.com/executablebooks/sphinx-exercise/releases/tag/v1.1.0

docs/source/index.md

@@ -5,6 +5,7 @@
 
 install
 syntax
+releases/index
 developer
 developer-design
 ```
@@ -32,6 +33,10 @@ The **solution** directive
 1. supports options such as `class`, `label`, and `hidden`
 2. can be referenced through `ref` role
 
+**Internationalization**:
+
+`sphinx-exercise` supports 27 languages including Chinese, Japanese, Korean, Arabic, Hindi, Spanish, French, German, and more. The extension automatically uses the appropriate language based on your Sphinx project's `language` configuration.
+
 (getting-started)=
 ## Getting Started
 

docs/source/releases/index.md

@@ -0,0 +1,11 @@
+# Release Notes
+
+This section contains detailed release notes for sphinx-exercise versions.
+
+```{toctree}
+:maxdepth: 1
+
+v1.1.0
+```
+
+For a complete list of all changes across versions, see the [CHANGELOG](https://github.com/executablebooks/sphinx-exercise/blob/main/CHANGELOG.md).

docs/source/releases/v1.1.0.md

@@ -0,0 +1,99 @@
+# Release v1.1.0
+
+**Release Date**: TBD
+
+This release adds comprehensive internationalization (i18n) support to sphinx-exercise, enabling the extension to display exercise and solution labels in 27 different languages.
+
+## ✨ New Features
+
+### Internationalization Support
+
+The extension now supports **27 languages** with automatic language detection:
+
+**East Asian**: Chinese (zh_CN), Japanese (ja), Korean (ko)
+
+**South Asian**: Bengali (bn), Hindi (hi), Tamil (ta)
+
+**Middle Eastern**: Arabic (ar), Turkish (tr)
+
+**European**: Czech (cs), Dutch (nl), French (fr), German (de), Greek (el), Hungarian (hu), Italian (it), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Ukrainian (uk)
+
+**Southeast Asian**: Indonesian (id), Malay (ms), Vietnamese (vi)
+
+### Automatic Language Detection
+
+The extension automatically detects your Sphinx project's language configuration and applies the appropriate translations:
+
+```python
+# conf.py
+language = 'zh_CN'  # Chinese
+```
+
+```yaml
+# _config.yml (Jupyter Book)
+sphinx:
+  config:
+    language: ja  # Japanese
+```
+
+### Translation Examples
+
+With language configured, directive labels automatically translate:
+
+- **Spanish**: "Exercise" → "Ejercicio", "Solution to" → "Solución a"
+- **Chinese**: "Exercise" → "练习", "Solution to" → "解答"
+- **Japanese**: "Exercise" → "練習", "Solution to" → "解答"
+- **French**: "Exercise" → "Exercice", "Solution to" → "Solution de"
+- **German**: "Exercise" → "Übung", "Solution to" → "Lösung zu"
+- **Arabic**: "Exercise" → "تمرين", "Solution to" → "الحل لـ"
+- **Hindi**: "Exercise" → "अभ्यास", "Solution to" → "समाधान"
+
+## 👌 Improvements
+
+- **JSON-based translations**: Source translations stored in easy-to-edit JSON format
+- **Alphabetical organization**: All language entries sorted alphabetically for maintainability
+- **Automated build process**: Script to generate `.po` and `.mo` files from JSON sources
+- **Enhanced documentation**: Comprehensive guides for using and contributing translations
+
+## 📚 Documentation Updates
+
+- Added internationalization section to [syntax guide](../syntax.md#internationalization-i18n)
+- Updated README with i18n feature highlights
+- Created releases documentation structure
+- Enhanced translation README with contribution workflow
+- Added Copilot instructions for maintainers
+
+## 🛠️ Infrastructure
+
+- Added `.github/copilot-instructions.md` for project maintenance guidelines
+- Created `docs/releases/` structure for release documentation
+- Improved translation contribution workflow
+
+## 🙏 Contributing Translations
+
+We welcome contributions for additional languages or improvements to existing translations!
+
+Translation files are maintained in `sphinx_exercise/translations/jsons/` as JSON files for easy editing. See the [translation guide](https://github.com/executablebooks/sphinx-exercise/tree/main/sphinx_exercise/translations) for details on how to contribute.
+
+## 📦 Installation
+
+Install or upgrade via pip:
+
+```bash
+pip install --upgrade sphinx-exercise
+```
+
+For development installation:
+
+```bash
+git clone https://github.com/executablebooks/sphinx-exercise
+cd sphinx-exercise
+pip install -e .
+```
+
+## 🔗 Links
+
+- [Full Changelog](https://github.com/executablebooks/sphinx-exercise/blob/main/CHANGELOG.md)
+- [Documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
+- [GitHub Repository](https://github.com/executablebooks/sphinx-exercise)
+- [Issue Tracker](https://github.com/executablebooks/sphinx-exercise/issues)