draugnorak/docs/localization.md

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:

python3 scripts/validate_i18n_catalog.py

This checks:

• missing keys
• extra keys
• placeholder mismatches

Audit Untranslated Strings

Run:

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:

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.