Skip to content

Commit 1198ee0

Browse files
mmckymmcky
committed
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
1 parent 568df6c commit 1198ee0

File tree

42 files changed

+423
-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.

42 files changed

+423
-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: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
# Changelog
22

3+
## [Unreleased]
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+
323

424
## [v0.4.1](https://github.com/executablebooks/sphinx-exercise/tree/v0.4.1) (2023-1-23)
525

‎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

‎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: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Release Notes
2+
3+
This section contains detailed release notes for sphinx-exercise versions.
4+
5+
```{toctree}
6+
:maxdepth: 1
7+
8+
unreleased
9+
```
10+
11+
## Quick Links
12+
13+
- [Latest Release](https://github.com/executablebooks/sphinx-exercise/releases/latest)
14+
- [All Releases](https://github.com/executablebooks/sphinx-exercise/releases)
15+
- [Changelog](https://github.com/executablebooks/sphinx-exercise/blob/main/CHANGELOG.md)

‎docs/source/releases/unreleased.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Unreleased Changes
2+
3+
This document tracks changes that have been merged but not yet released.
4+
5+
## Internationalization Support
6+
7+
### New Features
8+
9+
`sphinx-exercise` now includes comprehensive internationalization (i18n) support, allowing the extension to display exercise and solution labels in 27 different languages.
10+
11+
#### Supported Languages
12+
13+
The extension now supports the following languages:
14+
15+
- **East Asian**: Chinese, Japanese, Korean
16+
- **South Asian**: Bengali, Hindi, Tamil
17+
- **Middle Eastern**: Arabic, Turkish
18+
- **European**: Czech, Dutch, French, German, Greek, Hungarian, Italian, Norwegian, Polish, Portuguese, Romanian, Russian, Spanish, Swedish, Ukrainian
19+
- **Southeast Asian**: Indonesian, Malay, Vietnamese
20+
21+
#### Automatic Language Detection
22+
23+
The extension automatically detects your Sphinx project's language configuration and applies the appropriate translations. Simply set the `language` option in your `conf.py`:
24+
25+
```python
26+
# For Spanish
27+
language = 'es'
28+
29+
# For Chinese
30+
language = 'zh_CN'
31+
32+
# For Japanese
33+
language = 'ja'
34+
```
35+
36+
For Jupyter Book projects, configure in `_config.yml`:
37+
38+
```yaml
39+
sphinx:
40+
config:
41+
language: zh_CN # For Chinese
42+
```
43+
44+
#### Translation Examples
45+
46+
With language configured, the directive labels automatically translate:
47+
48+
- **Spanish**: "Exercise" → "Ejercicio", "Solution to" → "Solución a"
49+
- **Chinese**: "Exercise" → "练习", "Solution to" → "解答"
50+
- **Japanese**: "Exercise" → "練習", "Solution to" → "解答"
51+
- **French**: "Exercise" → "Exercice", "Solution de" → "Solution de"
52+
- **German**: "Exercise" → "Übung", "Solution to" → "Lösung zu"
53+
54+
### Contributing Translations
55+
56+
We welcome contributions for additional languages or improvements to existing translations. The 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.
57+
58+
### Documentation Updates
59+
60+
- Added internationalization section to [syntax guide](../syntax.md#internationalization-i18n)
61+
- Updated README with i18n feature highlights
62+
- Enhanced translation documentation with contribution guidelines
63+
64+
---
65+
66+
For the complete list of changes, see the [CHANGELOG](https://github.com/executablebooks/sphinx-exercise/blob/main/CHANGELOG.md).

‎docs/source/syntax.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -468,3 +468,62 @@ This is an example of how to introduce custom CSS.
468468
469469
This is an example of how to introduce custom CSS.
470470
```
471+
472+
## Internationalization (i18n)
473+
474+
`sphinx-exercise` includes built-in support for internationalization across 27 languages. The extension automatically detects your Sphinx project's language setting and displays "Exercise" and "Solution to" labels in the appropriate language.
475+
476+
### Supported Languages
477+
478+
The following languages are currently supported:
479+
480+
- Arabic (ar)
481+
- Bengali (bn)
482+
- Chinese (zh_CN)
483+
- Czech (cs)
484+
- Dutch (nl)
485+
- French (fr)
486+
- German (de)
487+
- Greek (el)
488+
- Hindi (hi)
489+
- Hungarian (hu)
490+
- Indonesian (id)
491+
- Italian (it)
492+
- Japanese (ja)
493+
- Korean (ko)
494+
- Malay (ms)
495+
- Norwegian (no)
496+
- Polish (pl)
497+
- Portuguese (pt)
498+
- Romanian (ro)
499+
- Russian (ru)
500+
- Spanish (es)
501+
- Swedish (sv)
502+
- Tamil (ta)
503+
- Turkish (tr)
504+
- Ukrainian (uk)
505+
- Vietnamese (vi)
506+
507+
### Configuring Language
508+
509+
To configure the language for your Sphinx project, set the `language` option in your `conf.py`:
510+
511+
```python
512+
# conf.py
513+
language = 'es' # For Spanish
514+
```
515+
516+
For Jupyter Book projects, set the language in `_config.yml`:
517+
518+
```yaml
519+
# _config.yml
520+
sphinx:
521+
config:
522+
language: es
523+
```
524+
525+
The exercise and solution directives will automatically use the appropriate translations. For example, with Spanish configured, "Exercise" will display as "Ejercicio" and "Solution to" as "Solución a".
526+
527+
### Contributing Translations
528+
529+
If you'd like to contribute translations for additional languages or improve existing ones, please see the [translation guide](https://github.com/executablebooks/sphinx-exercise/tree/main/sphinx_exercise/translations) in the repository.

‎sphinx_exercise/translations/README.md‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,48 @@
1-
JSONs created using GitHub Copilot Pro.
1+
# Translations for sphinx-exercise
22

3-
To convert to locale files run `_convert.py` in this folder.
3+
This directory contains internationalization (i18n) files for `sphinx-exercise`.
4+
5+
## Structure
6+
7+
- `jsons/` - Source translation files in JSON format
8+
- `Exercise.json` - Translations for "Exercise" label
9+
- `Solution.json` - Translations for "Solution to" label
10+
- `locales/` - Compiled locale files (`.po` and `.mo` files)
11+
- `_convert.py` - Script to generate locale files from JSON sources
12+
13+
## Supported Languages
14+
15+
Currently supporting 27 languages:
16+
17+
Arabic (ar), Bengali (bn), Chinese (zh_CN), Czech (cs), Dutch (nl), French (fr), German (de), Greek (el), Hindi (hi), Hungarian (hu), Indonesian (id), Italian (it), Japanese (ja), Korean (ko), Malay (ms), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tamil (ta), Turkish (tr), Ukrainian (uk), Vietnamese (vi)
18+
19+
## Adding or Updating Translations
20+
21+
To add a new language or update existing translations:
22+
23+
1. Edit the JSON files in `jsons/` directory
24+
- Add translations to both `Exercise.json` and `Solution.json`
25+
- Ensure the language symbol follows ISO 639-1 standard (or locale codes like `zh_CN`)
26+
- Keep entries alphabetically sorted by language name
27+
28+
2. Run the conversion script to generate `.po` and `.mo` files:
29+
```bash
30+
python _convert.py
31+
```
32+
33+
3. The script will:
34+
- Remove existing `.po` files
35+
- Generate new `.po` files from JSON sources
36+
- Compile `.mo` files using `msgfmt`
37+
38+
## Requirements
39+
40+
The `msgfmt` utility (from gettext) must be installed on your system to compile `.mo` files.
41+
42+
## Contributing
43+
44+
Contributions for new languages or improvements to existing translations are welcome! Please ensure:
45+
- Translations are accurate and culturally appropriate
46+
- Both `Exercise.json` and `Solution.json` are updated
47+
- The conversion script runs successfully
48+
- Documentation is updated to list the new language

‎sphinx_exercise/translations/jsons/Exercise.json‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,29 @@
11
[
22
{"language":"English","symbol":"en","text":"Exercise"},
3-
{"language":"Spanish","symbol":"es","text":"Ejercicio"},
4-
{"language":"French","symbol":"fr","text":"Exercice"},
3+
{"language":"Arabic","symbol":"ar","text":"تمرين"},
54
{"language":"Bengali","symbol":"bn","text":"অনুশীলনী"},
6-
{"language":"Russian","symbol":"ru","text":"Упражнение"},
7-
{"language":"Portuguese","symbol":"pt","text":"Exercício"},
8-
{"language":"Indonesian","symbol":"id","text":"Latihan"},
9-
{"language":"German","symbol":"de","text":"Übung"},
10-
{"language":"Vietnamese","symbol":"vi","text":"Bài tập"},
11-
{"language":"Tamil","symbol":"ta","text":"பயிற்சி"},
12-
{"language":"Italian","symbol":"it","text":"Esercizio"},
5+
{"language":"Chinese","symbol":"zh_CN","text":"练习"},
6+
{"language":"Czech","symbol":"cs","text":"Cvičení"},
137
{"language":"Dutch","symbol":"nl","text":"Opgave"},
8+
{"language":"French","symbol":"fr","text":"Exercice"},
9+
{"language":"German","symbol":"de","text":"Übung"},
1410
{"language":"Greek","symbol":"el","text":"Άσκηση"},
15-
{"language":"Polish","symbol":"pl","text":"Ćwiczenie"},
16-
{"language":"Ukrainian","symbol":"uk","text":"Вправа"},
11+
{"language":"Hindi","symbol":"hi","text":"अभ्यास"},
12+
{"language":"Hungarian","symbol":"hu","text":"Gyakorlat"},
13+
{"language":"Indonesian","symbol":"id","text":"Latihan"},
14+
{"language":"Italian","symbol":"it","text":"Esercizio"},
15+
{"language":"Japanese","symbol":"ja","text":"練習"},
16+
{"language":"Korean","symbol":"ko","text":"연습"},
1717
{"language":"Malay","symbol":"ms","text":"Latihan"},
18+
{"language":"Norwegian","symbol":"no","text":"Øvelse"},
19+
{"language":"Polish","symbol":"pl","text":"Ćwiczenie"},
20+
{"language":"Portuguese","symbol":"pt","text":"Exercício"},
1821
{"language":"Romanian","symbol":"ro","text":"Exercițiu"},
19-
{"language":"Czech","symbol":"cs","text":"Cvičení"},
20-
{"language":"Hungarian","symbol":"hu","text":"Gyakorlat"},
22+
{"language":"Russian","symbol":"ru","text":"Упражнение"},
23+
{"language":"Spanish","symbol":"es","text":"Ejercicio"},
2124
{"language":"Swedish","symbol":"sv","text":"Övning"},
22-
{"language":"Norwegian","symbol":"no","text":"Øvelse"}
25+
{"language":"Tamil","symbol":"ta","text":"பயிற்சி"},
26+
{"language":"Turkish","symbol":"tr","text":"Alıştırma"},
27+
{"language":"Ukrainian","symbol":"uk","text":"Вправа"},
28+
{"language":"Vietnamese","symbol":"vi","text":"Bài tập"}
2329
]

0 commit comments

Comments
 (0)