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