Contributing Translations¶

We welcome community translations! This guide explains how to contribute new languages or improve existing translations to mkdocs-quiz.

Quick Start¶

To contribute a new language:

Fork the repository on GitHub
Create a translation file
Translate all strings
Verify completeness
Submit a pull request

Creating a New Translation¶

1. Initialize Translation File¶

cd mkdocs-quiz
mkdocs-quiz translations init <language_code> -o mkdocs_quiz/locales/<language_code>.po

Examples:

mkdocs-quiz translations init es -o mkdocs_quiz/locales/es.po
mkdocs-quiz translations init de -o mkdocs_quiz/locales/de.po
mkdocs-quiz translations init ja -o mkdocs_quiz/locales/ja.po

Note: The -o flag places the file in the plugin's locales directory. Without it, the file is created in your current directory.

2. Translate Strings¶

Edit the .po file with your translations. You can use:

Text editor - Any editor works with .po files
Poedit - Free GUI application for translation
Online tools - POEditor, Weblate, Crowdin

Example .po file structure:

msgid "Submit"
msgstr "送信"  # Your translation here

msgid "Correct answer!"
msgstr "正解！"

msgid "Question {n}"
msgstr "質問 {n}"  # Preserve placeholders like {n}

3. Verify Completeness¶

Run the validation tool to ensure all strings are translated:

mkdocs-quiz translations check

Expected output:

Checking translation files...

Language: es
  File: es.po
  Total strings: 21
  Translated: 21 (100.0%)
  Untranslated: 0
  Fuzzy: 0
  Status: ✓ Complete

If you see untranslated or fuzzy entries, edit the .po file to complete them.

4. Test Locally¶

Test your translation by building the docs site:

pip install -e ".[docs]"
mkdocs serve

Configure a test page to use your language:

---
quiz:
  language: es
---
<quiz>
¿Pregunta de prueba?
- [x] Sí
- [ ] No
</quiz>

5. Submit Pull Request¶

Once your translation is complete and tested:

Commit your changes: git add mkdocs_quiz/locales/<language>.po
Create a descriptive commit message: Add Spanish (es) translation
Push to your fork and open a pull request

Translation Guidelines¶

Tone and Style¶

Use the formal/informal tone appropriate for your language and educational contexts
Maintain consistency throughout the translation
Keep the tone friendly and encouraging (especially for feedback messages)

Technical Requirements¶

Preserve placeholders: Keep {n} and other placeholders intact
✅ "Question {n}" → "Pregunta {n}"
❌ "Question {n}" → "Pregunta número"
Keep it concise: Translations should fit UI elements
Buttons, labels, and short messages need to be brief
Longer messages (like intro text) have more flexibility
Character encoding: Ensure your .po file uses UTF-8 encoding
```
"Content-Type: text/plain; charset=UTF-8\n"
```

CLI Tools for Contributors¶

`mkdocs-quiz translations check`¶

Validates translation completeness and detects issues:

mkdocs-quiz translations check

This command is also run automatically in pre-commit hooks.

`mkdocs-quiz translations init`¶

Creates a new translation file from the template:

mkdocs-quiz translations init <language_code>

By default creates {language}.po in current directory. Use -o to specify output path.

`mkdocs-quiz translations update`¶

Extracts strings from source code and updates all translation files:

mkdocs-quiz translations update

Requires: pip install babel

This command:

Scans Python source files for translatable strings
Extracts strings to mkdocs_quiz/locales/mkdocs_quiz.pot template
Updates all .po files with new strings
Marks obsolete strings for removal
Preserves existing translations

Workflow for Adding New Strings¶

When new translatable text is added to the codebase:

Run mkdocs-quiz translations update to extract and sync strings
Translate new strings in each .po file
Remove obsolete entries (marked with #~)
Verify: mkdocs-quiz translations check

Technical Details¶

Translation File Format¶

MkDocs Quiz uses the standard gettext .po format:

.pot files are templates (extracted from source code)
.po files contain translations for specific languages
Format is compatible with all standard translation tools

How Translations Work¶

Build Time: Plugin loads translations when processing each page
Resolution: Language is determined from configuration and page context
Fallback: If a translation is missing, the English source string is used
JavaScript Delivery: Translations are embedded in generated HTML as JSON
Runtime: JavaScript uses translations for dynamic UI updates

File Locations¶

mkdocs_quiz/
  locales/
    mkdocs_quiz.pot   # Template (source strings)
    de.po             # German
    eo.po             # Esperanto
    es.po             # Spanish
    fr.po             # French
    hi.po             # Hindi
    id.po             # Indonesian
    ja.po             # Japanese
    ko.po             # Korean
    no.po             # Norwegian
    pt-BR.po          # Portuguese (Brazilian)
    sv.po             # Swedish
    zh.po             # Chinese (Simplified)

Note: English (en) does not have a .po file because English strings in the source code are used as the fallback.

FAQ¶

Do I need to translate the template (`.pot`) file?¶

No, only translate .po files. The .pot file is a template generated from source code.

What if I want to update an existing translation?¶

Fork the repo, edit the existing .po file, test your changes, and submit a PR.

Can I translate only part of the strings?¶

Incomplete translations are not accepted. All strings must be translated before submission.

What language codes should I use?¶

Follow MkDocs Material conventions: 2-letter ISO 639-1 codes (e.g., fr, de, es) with hyphens for regional variants (e.g., pt-BR, zh-TW).

How do I handle plural forms?¶

MkDocs Quiz currently doesn't use plural forms in translatable strings. All messages use singular or count-based phrasing.

Getting Help¶

If you have questions about contributing translations:

Open an issue on GitHub: https://github.com/ewels/mkdocs-quiz/issues
Check existing translations for reference
Ask in your pull request if you're unsure about something

Thank you for helping make mkdocs-quiz accessible to more people! 🌍