1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
# 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**
```bash
# Upload en.json to POEditor
```
2. **Translate in POEditor**
- Use POEditor's web interface
- Invite translators
- Track progress per language
3. **Export translations**
```bash
# Download from POEditor as JSON
# Save to translations/{language_code}.json
# Example: translations/es.json, translations/fr.json
```
4. **Test translations**
```bash
# Set your locale and restart shell
export LANG=es_ES.UTF-8
qs -p .
```
#### Method 2: Manual Translation
1. **Copy template**
```bash
cp translations/template.json translations/es.json
```
2. **Fill in translations**
```json
{
"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**
```bash
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:
```json
[
{
"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**
```bash
export LANG=es_ES.UTF-8
export LC_ALL=es_ES.UTF-8
```
2. **Restart shell**
```bash
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:
```bash
# 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
|