# Localization

Quests ships with **9 languages**: English (`en-US`), German (`de-DE`), Spanish (`es-ES`), French (`fr-FR`), Italian (`it-IT`), Polish (`pl-PL`), Brazilian Portuguese (`pt-BR`), Russian (`ru-RU`) and Turkish (`tr-TR`). Server owners can change any text, add their own keys and add new languages.

---

## Player language

Every player sees Quests in their own language:

- `/kslang <code>` or `/kslang auto` (from KyuubiSoft Core) sets the language for **all** KS mods at once. `/kslang` alone shows the current language and the available codes in chat.
- The shared KS settings window (`/kssettings`) has a language page with the same choice.
- The Questbook settings show the current language; **Change** opens that language page.

Core's admin hub decides the default language for players and whether players may choose their own. See [Core](https://wiki.kyuubisoft.com/hytale/core/).

The `language` field in Quests' `config.json` is the server language of Quests (console and fallback texts).

---

## File structure

Translation files live in the `localization/` folder of the data folder:

```
mods/kyuubisoft_questbook/
  localization/
    en-US.json                  <-- shipped (updated with the mod)
    de-DE.json                  <-- shipped
    ... (9 shipped languages)
    custom_en-US.json           <-- your overrides (never overwritten)
    custom_de-DE.json           <-- your overrides
    custom_en-US.json.example   <-- template
    custom_de-DE.json.example   <-- template
```

Shipped files are replaced when the mod ships a newer version (`_localization_version`). The old file is kept as `<lang>.json.backup-v<N>`, so you can compare it with your edits. Custom files are **never touched** by updates.

:::tip
Put your own texts and changes into `custom_<lang>.json`. Edits in the shipped files are lost when the next version replaces them.
:::

---

## Editing texts in game

The [admin window](./admin-panel) edits texts per language:

- The quest editor's **Texts** section has name, description and objective texts for every language. A missing language shows the English text in grey and is never saved as a translation.
- NPC profiles have default, "not ready" and proximity texts per language.
- Chapter and tier names can be translated in their editors.
- The **General** settings tab lists the languages with their completeness and can **add a language** (a code like `nl-NL`). New languages appear at once in every translation chip.

The window saves your texts into the custom files.

---

## Key patterns

Translation keys are dot-separated, for example:

```json title="custom_en-US.json"
{
  "questbook.nav.daily": "Daily",
  "questbook.btn.claim": "Claim reward",
  "quest.my_quest.name": "My Custom Quest"
}
```

Common prefixes: `questbook.*` (Questbook, quest giver and delivery windows), `quest.*` (quests, objectives, HUD texts), `npc.*` (NPC profile dialogs), `qadmin.*` and `qprofile.*` (admin window), `error.*` (error messages). Placeholders use numbered (`{0}`, `{1}`) or named (`{amount}`) syntax.

The shipped `en-US.json` is the full reference of every key.

---

## Texts for your own quests

Quest names and descriptions can be written inline per language:

```json title="custom/custom_quests.json"
{
  "quests": [
    {
      "id": "my_quest",
      "name": { "en-US": "My Quest", "de-DE": "Meine Quest" },
      "description": { "en-US": "Do the thing.", "de-DE": "Mach die Sache." }
    }
  ]
}
```

Or use keys and define them in your custom locale files:

```json title="localization/custom_en-US.json"
{
  "quest.my_quest.name": "My Custom Quest",
  "quest.my_quest.description": "Complete the custom objective."
}
```

Custom translations are loaded **after** the shipped ones, so they override matching keys.

---

## Language fallback

1. The player's language, with custom overrides merged in
2. English (`en-US`)
3. If a text exists in only one language (for example a quest you wrote only in German), that language is used instead of the raw key (since 2.1.0)
4. The raw key

---

## Adding a new language

Use **Add language** in the General tab of the admin window, or:

1. Create `localization/<code>.json` (for example `nl-NL.json`) and translate the keys from `en-US.json`.
2. Run `/ksquestadmin reload`.

Missing keys fall back to English.

---

## Reload

After editing a localization file by hand, run:

```
/ksquestadmin reload
```

No restart is needed.