DankMaterialShell/quickshell/translations/WORKFLOW.md

Translation Workflow for DankMaterialShell

POEditor Integration Guide

Initial Setup

1. Create POEditor Project

   • Go to https://poeditor.com
   • Create new project "DankMaterialShell"
   • Add languages you want to support (es, fr, de, etc.)

2. Import Source Strings

   • Upload en.json as the source language
   • POEditor will detect 336 translatable strings
   • Format: Key-Value JSON

Translation Workflow

Method 1: Using POEditor (Recommended)

1. Upload source file

   # Upload en.json to POEditor
   

2. Translate in POEditor

   • Use POEditor's web interface
   • Invite translators
   • Track progress per language

3. Export translations

   # Download from POEditor as JSON
   # Save to translations/{language_code}.json
   # Example: translations/es.json, translations/fr.json
   

4. Test translations

   # Set your locale and restart shell
   export LANG=es_ES.UTF-8
   qs -p .
   

Method 2: Manual Translation

1. Copy template

   cp translations/template.json translations/es.json
   

2. Fill in translations

   {
     "term": "Settings",
     "context": "Modals/Settings/SettingsModal.qml:147",
     "reference": "Modals/Settings/SettingsModal.qml:147",
     "comment": "",
     "translation": "Configuración"
   }
   

3. Upload to POEditor (optional)

Updating Translations After Code Changes

1. Re-extract strings

   cd translations
   python3 extract_translations.py
   

2. Upload updated en.json to POEditor

   • POEditor will detect new/removed strings
   • Preserves existing translations

3. Download updated translations

Translation File Format

POEditor-compatible JSON format:

[
  {
    "term": "source string in English",
    "context": "file:line where it appears",
    "reference": "full/path/to/file.qml:123",
    "comment": "optional context for translators",
    "translation": "translated string"
  }
]

Supported Languages

The shell will auto-detect your system locale. Supported format:

• es.json → Spanish (es_ES, es_MX, etc.)
• fr.json → French (fr_FR, fr_CA, etc.)
• de.json → German
• zh.json → Chinese
• ja.json → Japanese
• pt.json → Portuguese
• etc.

Testing Translations

1. Change system locale

   export LANG=es_ES.UTF-8
   export LC_ALL=es_ES.UTF-8
   

2. Restart shell

   qs -p .
   

3. Verify translations appear correctly

File Structure

translations/
├── en.json              # Source language (English)
├── template.json        # Empty template for new languages
├── es.json              # Spanish translation
├── fr.json              # French translation
├── extract_translations.py  # Auto-extraction script
├── README.md            # Technical documentation
└── WORKFLOW.md          # This file

Translation Statistics

• Total strings: 336 unique terms
• Most translated components:
  • Settings UI: 202 strings (60%)
  • Weather: 25 strings (7%)
  • System monitors: Various
  • Modals: 43 strings (13%)

POEditor API Integration (Advanced)

For automated sync, use POEditor's API:

# Export from POEditor
curl -X POST https://api.poeditor.com/v2/projects/export \
  -d api_token="YOUR_TOKEN" \
  -d id="PROJECT_ID" \
  -d language="es" \
  -d type="key_value_json"

# Import to POEditor
curl -X POST https://api.poeditor.com/v2/projects/upload \
  -d api_token="YOUR_TOKEN" \
  -d id="PROJECT_ID" \
  -d updating="terms_translations" \
  -d language="es" \
  -F file=@"translations/es.json"

Best Practices

1. Context matters: Use the reference field to understand where strings appear
2. Test before committing: Always test translations in the actual UI
3. Keep synchronized: Re-extract after significant UI changes
4. Preserve formatting: Keep placeholders like %1, {0} intact
5. Cultural adaptation: Some strings may need cultural context, not just literal translation

Troubleshooting

Translations not loading?

• Check file exists: ~/.config/DankMaterialShell/translations/{language_code}.json
• Verify JSON syntax: python3 -m json.tool translations/es.json
• Check console for errors: qs -v -p .

Wrong language loading?

• Check system locale: echo $LANG
• Verify file naming: Must match locale prefix (es_ES → es.json)

Missing strings?

• Re-run extraction: python3 extract_translations.py
• Compare with en.json to find new strings