draugnorak/translate.md

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:

[meta]
code=en
name=English
native_name=English

Change these values for your language.

Example for Spanish:

[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:

msg.528fb1c4e5fb=New Game

You only translate the value after =:

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:

system.language.selected=Language set to {language}.

Good translation:

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:

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:

msg.528fb1c4e5fb=New Game
msg.802aa6576577=Load Game
msg.f83b6fe3aebf=Exit

Spanish example:

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:

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