Translation Guide

IronOS supports multiple languages through JSON configuration files. All translations are stored in the Translations/ directory and can be contributed via pull requests.

Translation Files

Each language has its own JSON file in the format:

Translations/translation_LANG_CODE.json

For example:

translation_EN.json - English
translation_DE.json - German
translation_ZH_CN.json - Simplified Chinese
translation_FR.json - French

Adding a New Translation

1. Create Translation File

Copy the English translation as a template:

cd Translations
cp translation_EN.json translation_NEW.json

Replace NEW with your language code (e.g., IT for Italian, PT for Portuguese).

2. Edit Translation File

The JSON file contains key-value pairs for all translatable strings. The structure looks like:

{
  "languageCode": "EN",
  "languageName": "English",
  "messages": {
    "SettingsCalibrationDone": "Calibration done!",
    "SettingsCalibrationWarning": "Ensure the tip is at room temperature before proceeding!",
    "SettingsResetWarning": "Are you sure to reset settings to default values?"
  },
  "characters": {
    "SettingRightChar": "R",
    "SettingLeftChar": "L",
    "SettingAutoChar": "A"
  }
}

Important fields:

languageCode - Your language code (must match filename)
languageName - Native name of the language
messages - All translatable UI strings
characters - Single character abbreviations

3. Font Support

IronOS uses bitmap fonts. If your language requires characters not in the base font:

The translation system will automatically include required glyphs from the Wen Quan Yi font
For languages with large character sets (CJK), compression is automatically applied
Font maps are generated during the build process

4. Test Your Translation

Build firmware with your new translation:

cd source
make -j8 model=Pinecil firmware-NEW

Replace NEW with your language code and Pinecil with your device model.

5. Update Translation Files

After editing translations, regenerate the translation files:

cd Translations
python3 make_translation.py

This will:

Generate font maps for all languages
Validate translation JSON files
Create required C++ source files

6. Update Documentation

If you’ve edited translation definitions, also update the settings menu documentation:

cd Translations  
python3 gen_menu_docs.py

Updating Existing Translations

1. Edit the JSON File

Open the appropriate translation_XX.json file and update the strings you want to change.

2. Test Your Changes

Build and test the firmware:

cd source
make -j8 model=YOUR_MODEL firmware-YOUR_LANG

3. Validate Changes

Run the translation test:

cd Translations
python3 make_translation_test.py

Contributing Translations

Via Pull Request (Recommended)

Fork the IronOS repository
Create a new branch for your translation:
```
git checkout -b add-translation-XX
```
Add or update the translation JSON file

Commit your changes:

git add Translations/translation_XX.json
git commit -m "Add XX translation" 

Push to your fork and create a pull request
GitHub Actions will automatically build firmware with your translation

Testing Without Local Build Environment

If you don’t want to set up the build environment:

Fork the repository on GitHub
Edit the translation file directly in GitHub’s web interface
Create a pull request
GitHub Actions will build the firmware for you
Download the artifacts to test on your device

All translation contributions must be submitted via GitHub pull requests. Translations sent via issues, discussions, or email will not be accepted.