Skip to content

Commit 68b4b72

Browse files
mmckymmcky
authored
Add internationalization (i18n) support for 27 languages (#77)
* Add internationalization support for 27 languages - Add i18n support with 27 languages including Chinese, Japanese, Korean, Arabic, Hindi, and Turkish - Add comprehensive Copilot instructions for project maintenance - Create releases documentation structure in docs/releases/ - Update README and documentation with i18n features - Reorganize translation files with alphabetical sorting - Generate all .po and .mo locale files Features: - Automatic language detection from Sphinx config - JSON-based translation source files for easy contribution - Complete documentation with examples and contribution guide Languages supported: Arabic, Bengali, Chinese, Czech, Dutch, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Tamil, Turkish, Ukrainian, Vietnamese * Prepare release v1.1.0 - Update CHANGELOG with v1.1.0 release notes - Create comprehensive release notes in docs/source/releases/v1.1.0.md - Add RELEASE.md with step-by-step release checklist - Simplify releases documentation structure - Remove duplicate unreleased.md file Ready for release after version bump in __init__.py * Fix import ordering in directive.py and nodes.py - Move sphinx.locale imports to top of file - Fixes E402 pre-commit errors
1 parent 4b49053 commit 68b4b72

File tree

44 files changed

+568
-30
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+568
-30
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Copilot Instructions for sphinx-exercise
2+
3+
## General Guidelines
4+
5+
### Code Philosophy
6+
- **Simplicity First**: Pursue simple code with low complexity when making changes
7+
- **Maintainability**: Keep code modular and easy to understand
8+
- **Minimal Dependencies**: Avoid adding unnecessary dependencies
9+
10+
### Documentation Standards
11+
- **Do NOT create summary documents** when making changes
12+
- Instead, **update existing documents** where needed (README.md, docs/, etc.)
13+
- Keep documentation in sync with code changes
14+
15+
### Release Management
16+
- **Review Documentation**: Before making any releases, please review all documentation in `docs/`
17+
- **Update CHANGELOG.md**: Keep the CHANGELOG.md up to date with all significant changes
18+
- **Release Notes**: Maintain detailed release information in `docs/releases/`
19+
- Follow semantic versioning principles
20+
21+
### Release Information Structure
22+
Release documentation should be maintained in `docs/releases/` with the following structure:
23+
- One file per version (e.g., `v0.5.0.md`)
24+
- Link to releases from main documentation
25+
- Include migration guides for breaking changes
26+
27+
## Project-Specific Guidelines
28+
29+
### Internationalization (i18n)
30+
- Translation files are located in `sphinx_exercise/translations/`
31+
- JSON source files: `sphinx_exercise/translations/jsons/`
32+
- Compiled locale files: `sphinx_exercise/translations/locales/`
33+
- Use `_convert.py` to regenerate locale files from JSON sources
34+
- When adding new languages:
35+
1. Add translations to both `Exercise.json` and `Solution.json`
36+
2. Run `python sphinx_exercise/translations/_convert.py` to generate `.po` and `.mo` files
37+
3. Update documentation to mention new language support
38+
39+
### Testing
40+
- All changes should include appropriate tests
41+
- Test files are in `tests/` directory
42+
- Run tests before committing changes
43+
- Maintain test coverage
44+
45+
### Code Structure
46+
- Main extension code: `sphinx_exercise/`
47+
- Directives: `directive.py`
48+
- Transforms: `transforms.py` and `post_transforms.py`
49+
- LaTeX support: `latex.py`
50+
- Node definitions: `nodes.py`
51+
52+
### Documentation
53+
- Main docs: `docs/source/`
54+
- Build docs locally before committing documentation changes
55+
- Ensure all examples work correctly
56+
- Update syntax documentation when adding new features
57+
58+
## Workflow
59+
60+
1. **Before Starting**: Review relevant existing code and documentation
61+
2. **During Development**:
62+
- Write simple, clear code
63+
- Update tests as needed
64+
- Update existing documentation inline
65+
3. **Before Committing**:
66+
- Run tests
67+
- Review documentation changes
68+
- Update CHANGELOG.md if applicable
69+
4. **Before Releasing**:
70+
- Review all documentation in `docs/`
71+
- Create release notes in `docs/releases/`
72+
- Update CHANGELOG.md
73+
- Verify all tests pass

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,31 @@
11
# Changelog
22

3+
## [v1.1.0](https://github.com/executablebooks/sphinx-exercise/tree/v1.1.0) (TBD)
4+
5+
### New ✨
6+
7+
- Added internationalization (i18n) support for 27 languages
8+
- Added translations for Chinese, Japanese, Korean, Arabic, Hindi, Turkish, and expanded existing language support
9+
- Extension now automatically detects Sphinx project language setting and displays appropriate translations
10+
11+
### Improved 👌
12+
13+
- Reorganized and expanded translation files with alphabetical sorting
14+
- Enhanced translation documentation with comprehensive guides
15+
- Updated README and documentation to highlight internationalization features
16+
17+
### Documentation 📚
18+
19+
- Added internationalization section to syntax documentation
20+
- Updated README with i18n feature highlights
21+
- Improved translation README with detailed contribution guidelines
22+
- Created releases documentation structure in `docs/releases/`
23+
- Added Copilot instructions for project maintenance
24+
25+
26+
## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-XX-XX)
27+
28+
_No changelog available for this version._
329

430
## [v1.0.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.0.1) (2024-07-01)
531

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@
99
This package contains a [Sphinx](http://www.sphinx-doc.org/en/master/) extension
1010
for producing exercise and solution directives.
1111

12+
## Features
13+
14+
- **Automatic numbering** for exercises and solutions
15+
- **Cross-referencing** support with `ref` and `numref` roles
16+
- **Internationalization** support for 27 languages including Chinese, Japanese, Korean, Arabic, Hindi, and more
17+
- **HTML and PDF** output support
18+
- **Gated directive** syntax for including executable code and complex content
19+
- **Customizable styling** with class options and hidden directive support
1220

1321
## Get started
1422

‎RELEASE.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Release Checklist for v1.1.0
2+
3+
This document provides the step-by-step process to release version 1.1.0 of sphinx-exercise.
4+
5+
## Pre-Release Checklist
6+
7+
- [ ] All tests pass locally
8+
- [ ] All tests pass on CI
9+
- [ ] Documentation builds successfully
10+
- [ ] CHANGELOG.md is up to date with release date
11+
- [ ] Version number updated in `sphinx_exercise/__init__.py`
12+
- [ ] Release notes finalized in `docs/source/releases/v1.1.0.md`
13+
- [ ] All PRs for this release are merged
14+
15+
## Version Update
16+
17+
Update the version number in:
18+
19+
1. **`sphinx_exercise/__init__.py`**:
20+
```python
21+
__version__ = "1.1.0"
22+
```
23+
24+
2. **`CHANGELOG.md`**:
25+
- Replace `(TBD)` with the actual release date
26+
- Change link to point to the release tag
27+
28+
## Release Steps
29+
30+
### 1. Create Release Commit
31+
32+
```bash
33+
# Ensure you're on main branch and up to date
34+
git checkout main
35+
git pull origin main
36+
37+
# Update version in __init__.py
38+
# Update CHANGELOG.md with release date
39+
# Commit changes
40+
git add sphinx_exercise/__init__.py CHANGELOG.md docs/source/releases/v1.1.0.md
41+
git commit -m "Release v1.1.0"
42+
```
43+
44+
### 2. Create Git Tag
45+
46+
```bash
47+
git tag -a v1.1.0 -m "Release version 1.1.0 - Internationalization support"
48+
```
49+
50+
### 3. Push to GitHub
51+
52+
```bash
53+
git push origin main
54+
git push origin v1.1.0
55+
```
56+
57+
### 4. Create GitHub Release
58+
59+
1. Go to https://github.com/executablebooks/sphinx-exercise/releases/new
60+
2. Select tag: `v1.1.0`
61+
3. Release title: `v1.1.0 - Internationalization Support`
62+
4. Description: Copy content from `docs/source/releases/v1.1.0.md`
63+
5. Click "Publish release"
64+
65+
### 5. Publish to PyPI
66+
67+
```bash
68+
# Clean previous builds
69+
rm -rf dist/ build/ *.egg-info
70+
71+
# Build distribution
72+
python -m build
73+
74+
# Upload to PyPI (requires PyPI credentials)
75+
python -m twine upload dist/*
76+
```
77+
78+
### 6. Update Documentation
79+
80+
The documentation should automatically build from the new tag on ReadTheDocs. Verify at:
81+
https://ebp-sphinx-exercise.readthedocs.io/en/latest/
82+
83+
### 7. Post-Release
84+
85+
1. Update `docs/source/releases/index.md` to include v1.1.0
86+
2. Create new "Unreleased" section in CHANGELOG.md for future changes
87+
3. Announce release on relevant channels
88+
89+
## Version Numbering
90+
91+
This project follows [Semantic Versioning](https://semver.org/):
92+
93+
- **MAJOR** version for incompatible API changes
94+
- **MINOR** version for new functionality in a backward compatible manner (this release)
95+
- **PATCH** version for backward compatible bug fixes
96+
97+
## Release Highlights for Announcement
98+
99+
**sphinx-exercise v1.1.0** is now available! 🎉
100+
101+
This release adds comprehensive internationalization support:
102+
- ✨ Support for 27 languages including Chinese, Japanese, Korean, Arabic, and Hindi
103+
- 🌍 Automatic language detection from Sphinx configuration
104+
- 📚 Enhanced documentation with i18n examples and contribution guides
105+
- 🛠️ JSON-based translation system for easy community contributions
106+
107+
Install or upgrade: `pip install --upgrade sphinx-exercise`
108+
109+
Full release notes: https://github.com/executablebooks/sphinx-exercise/releases/tag/v1.1.0

‎docs/source/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
66
install
77
syntax
8+
releases/index
89
developer
910
developer-design
1011
```
@@ -32,6 +33,10 @@ The **solution** directive
3233
1. supports options such as `class`, `label`, and `hidden`
3334
2. can be referenced through `ref` role
3435

36+
**Internationalization**:
37+
38+
`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.
39+
3540
(getting-started)=
3641
## Getting Started
3742

‎docs/source/releases/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Release Notes
2+
3+
This section contains detailed release notes for sphinx-exercise versions.
4+
5+
```{toctree}
6+
:maxdepth: 1
7+
8+
v1.1.0
9+
```
10+
11+
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‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Release v1.1.0
2+
3+
**Release Date**: TBD
4+
5+
This release adds comprehensive internationalization (i18n) support to sphinx-exercise, enabling the extension to display exercise and solution labels in 27 different languages.
6+
7+
## ✨ New Features
8+
9+
### Internationalization Support
10+
11+
The extension now supports **27 languages** with automatic language detection:
12+
13+
**East Asian**: Chinese (zh_CN), Japanese (ja), Korean (ko)
14+
15+
**South Asian**: Bengali (bn), Hindi (hi), Tamil (ta)
16+
17+
**Middle Eastern**: Arabic (ar), Turkish (tr)
18+
19+
**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)
20+
21+
**Southeast Asian**: Indonesian (id), Malay (ms), Vietnamese (vi)
22+
23+
### Automatic Language Detection
24+
25+
The extension automatically detects your Sphinx project's language configuration and applies the appropriate translations:
26+
27+
```python
28+
# conf.py
29+
language = 'zh_CN' # Chinese
30+
```
31+
32+
```yaml
33+
# _config.yml (Jupyter Book)
34+
sphinx:
35+
config:
36+
language: ja # Japanese
37+
```
38+
39+
### Translation Examples
40+
41+
With language configured, directive labels automatically translate:
42+
43+
- **Spanish**: "Exercise" → "Ejercicio", "Solution to" → "Solución a"
44+
- **Chinese**: "Exercise" → "练习", "Solution to" → "解答"
45+
- **Japanese**: "Exercise" → "練習", "Solution to" → "解答"
46+
- **French**: "Exercise" → "Exercice", "Solution to" → "Solution de"
47+
- **German**: "Exercise" → "Übung", "Solution to" → "Lösung zu"
48+
- **Arabic**: "Exercise" → "تمرين", "Solution to" → "الحل لـ"
49+
- **Hindi**: "Exercise" → "अभ्यास", "Solution to" → "समाधान"
50+
51+
## 👌 Improvements
52+
53+
- **JSON-based translations**: Source translations stored in easy-to-edit JSON format
54+
- **Alphabetical organization**: All language entries sorted alphabetically for maintainability
55+
- **Automated build process**: Script to generate `.po` and `.mo` files from JSON sources
56+
- **Enhanced documentation**: Comprehensive guides for using and contributing translations
57+
58+
## 📚 Documentation Updates
59+
60+
- Added internationalization section to [syntax guide](../syntax.md#internationalization-i18n)
61+
- Updated README with i18n feature highlights
62+
- Created releases documentation structure
63+
- Enhanced translation README with contribution workflow
64+
- Added Copilot instructions for maintainers
65+
66+
## 🛠️ Infrastructure
67+
68+
- Added `.github/copilot-instructions.md` for project maintenance guidelines
69+
- Created `docs/releases/` structure for release documentation
70+
- Improved translation contribution workflow
71+
72+
## 🙏 Contributing Translations
73+
74+
We welcome contributions for additional languages or improvements to existing translations!
75+
76+
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.
77+
78+
## 📦 Installation
79+
80+
Install or upgrade via pip:
81+
82+
```bash
83+
pip install --upgrade sphinx-exercise
84+
```
85+
86+
For development installation:
87+
88+
```bash
89+
git clone https://github.com/executablebooks/sphinx-exercise
90+
cd sphinx-exercise
91+
pip install -e .
92+
```
93+
94+
## 🔗 Links
95+
96+
- [Full Changelog](https://github.com/executablebooks/sphinx-exercise/blob/main/CHANGELOG.md)
97+
- [Documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
98+
- [GitHub Repository](https://github.com/executablebooks/sphinx-exercise)
99+
- [Issue Tracker](https://github.com/executablebooks/sphinx-exercise/issues)

0 commit comments

Comments
 (0)