Implement i18n audit/localization cleanup and sync libstorm submodule

translate.md

@@ -0,0 +1,206 @@
+# How To Translate Draugnorak (Beginner Guide)
+
+This guide is for first-time translators.
+You do not need to know programming.
+
+## What You Are Editing
+
+Draugnorak stores text in translation files inside the `lang/` folder.
+
+Important files:
+- `lang/en.template.ini` -> a clean template you copy from.
+- `lang/en.ini` -> English source text used by the game as fallback.
+- `lang/<your-language-code>.ini` -> your translation file.
+
+Example language codes:
+- `es` for Spanish
+- `fr` for French
+- `de` for German
+- `pt-BR` for Brazilian Portuguese
+
+## Before You Start
+
+You need:
+1. A plain text editor (VS Code, Notepad++, Kate, etc.).
+2. This project folder on your machine.
+3. Basic comfort editing text files.
+
+## Step 1: Make Your Translation File
+
+1. Open the `lang` folder.
+2. Copy `en.template.ini`.
+3. Rename the copy to your language code, for example:
+   - `es.ini`
+
+You now have a file like `lang/es.ini`.
+
+## Step 2: Fill In Language Metadata
+
+At the top of the file, find:
+
+```ini
+[meta]
+code=en
+name=English
+native_name=English
+```
+
+Change these values for your language.
+
+Example for Spanish:
+
+```ini
+[meta]
+code=es
+name=Spanish
+native_name=Espanol
+```
+
+Notes:
+- `code` should match your filename (`es.ini` -> `code=es`).
+- `name` can be in English.
+- `native_name` should be in your own language (what speakers call it).
+
+## Step 3: Translate Only the Right Side
+
+Every line is `key=value`.
+
+Example:
+
+```ini
+msg.528fb1c4e5fb=New Game
+```
+
+You only translate the value after `=`:
+
+```ini
+msg.528fb1c4e5fb=Nuevo juego
+```
+
+Do NOT change:
+- the key (`msg.528fb1c4e5fb`)
+- section names like `[messages]`
+- file structure
+
+## Step 4: Keep Placeholders Exactly As Written
+
+Some messages contain placeholders like:
+- `{arg1}`
+- `{arg2}`
+- `{language}`
+- `{count}`
+
+Example:
+
+```ini
+system.language.selected=Language set to {language}.
+```
+
+Good translation:
+
+```ini
+system.language.selected=Idioma configurado en {language}.
+```
+
+Rules:
+- Keep placeholder names exactly the same.
+- You can move them in the sentence.
+- Do not remove them.
+- Do not rename them.
+
+Bad examples:
+- `... {lang}` (wrong name)
+- missing placeholder entirely
+
+## Step 5: Keep Escapes Intact
+
+Some values may contain escaped characters:
+- `\n` = new line
+- `\t` = tab
+
+If you see these, keep them unless you know exactly why to change them.
+
+## Step 6: Save as UTF-8
+
+Use UTF-8 encoding so accented and non-Latin characters are stored correctly.
+
+Most modern editors use UTF-8 by default.
+
+## Step 7: Validate Your Translation
+
+From the project root, run:
+
+```bash
+python3 scripts/validate_i18n_catalog.py
+```
+
+What this checks:
+- missing keys
+- extra keys
+- placeholder mismatches
+
+If it prints `OK`, your file structure is valid.
+If it prints `FAIL`, read the listed errors and fix them.
+
+## Step 8: Test In-Game
+
+On first launch, the game asks for language selection if no saved language preference exists.
+Choose your language and check menus/messages.
+
+If language was already saved before, you may need to remove or edit the saved preference file so first-run selection appears again.
+(Preference is stored in `draugnorak.dat` under the appdata config directory.)
+
+## Common Mistakes
+
+1. Editing keys instead of values.
+2. Deleting `{arg1}` placeholders.
+3. Renaming section headers.
+4. Saving in a non-UTF-8 encoding.
+5. Forgetting to run validator script.
+
+## Translation Style Tips
+
+1. Prefer clear, simple text over literal word-for-word translation.
+2. Keep gameplay warnings short and urgent.
+3. Keep menu labels concise.
+4. Keep terminology consistent (same item name everywhere).
+
+## Example Mini Translation
+
+Original:
+
+```ini
+msg.528fb1c4e5fb=New Game
+msg.802aa6576577=Load Game
+msg.f83b6fe3aebf=Exit
+```
+
+Spanish example:
+
+```ini
+msg.528fb1c4e5fb=Nuevo juego
+msg.802aa6576577=Cargar partida
+msg.f83b6fe3aebf=Salir
+```
+
+## If You Are Unsure About a Line
+
+If one sentence is unclear:
+1. Leave it in English for now.
+2. Add a comment above it using `;`.
+3. Continue the rest.
+
+Example:
+
+```ini
+; Need context: is this shown during combat or menu?
+msg.abcdef123456=Original English text
+```
+
+## Submitting Your Translation
+
+Share these files:
+1. Your language file, for example `lang/es.ini`.
+2. Optional notes for unclear lines.
+
+That is all you need to contribute a translation.