72 lines
1.7 KiB
Markdown
72 lines
1.7 KiB
Markdown
# Localization Guide
|
|
|
|
Draugnorak uses key-based localization files in `lang/`.
|
|
|
|
## File Layout
|
|
|
|
- `lang/en.ini`: source English catalog used at runtime fallback.
|
|
- `lang/en.template.ini`: copy this to start a new language.
|
|
- `lang/<code>.ini`: translator file (examples: `es.ini`, `pt-BR.ini`).
|
|
|
|
Language preference is saved to `draugnorak.dat` in the appdata config directory.
|
|
|
|
## Create a New Translation
|
|
|
|
1. Copy `lang/en.template.ini` to `lang/<code>.ini`.
|
|
2. Edit `[meta]`:
|
|
- `code`
|
|
- `name`
|
|
- `native_name`
|
|
3. Translate only values (right side of `=`). Never change keys.
|
|
4. Keep placeholders exactly as written, for example `{arg1}` or `{language}`.
|
|
|
|
## Placeholder Rules
|
|
|
|
- You may move placeholders in the sentence.
|
|
- Do not rename or remove placeholders.
|
|
- Example:
|
|
- English: `Language set to {language}.`
|
|
- Spanish: `Idioma establecido en {language}.`
|
|
|
|
## Validate Translation Files
|
|
|
|
Run:
|
|
|
|
```bash
|
|
python3 scripts/validate_i18n_catalog.py
|
|
```
|
|
|
|
This checks:
|
|
- missing keys
|
|
- extra keys
|
|
- placeholder mismatches
|
|
|
|
## Audit Untranslated Strings
|
|
|
|
Run:
|
|
|
|
```bash
|
|
python3 scripts/audit_untranslated_strings.py
|
|
```
|
|
|
|
This checks likely user-facing string literals that are not passed through translation wrappers.
|
|
|
|
Use `scripts/i18n_audit_allowlist.txt` for intentional exceptions. Keep this list small and explain each exception with a comment.
|
|
|
|
## Regenerate English Catalog
|
|
|
|
When text changes in code, regenerate English source/template catalogs:
|
|
|
|
```bash
|
|
python3 scripts/generate_i18n_catalog.py
|
|
```
|
|
|
|
This updates:
|
|
- `lang/en.ini`
|
|
- `lang/en.template.ini`
|
|
|
|
## Runtime Behavior
|
|
|
|
- Missing key in selected language: falls back to English.
|
|
- Missing key in English catalog: key text is spoken/displayed.
|