# 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.