# Localization Guide

# Localization Guide

This guide explains how translations work in KyuubiSoft mods, how to add your own, and how to manage multiple languages.

## How i18n Works

KyuubiSoft mods use a **file-first pattern** for localization. When the system looks up a translation key, it checks in this order:

1. **Custom file** — `localization/custom_en-US.json` (your additions, never overwritten)
2. **Base file** — `localization/en-US.json` (shipped with the mod, replaced on updates)
3. **English** — if a key is missing in the player's language, the English text is used

This means your custom translations always take priority, and you can override any base translation by adding the same key to your custom file. Core also reads extra files named `custom_<lang>_<anything>.json` (in file-name order).

## Key Conventions

Each mod follows consistent naming patterns for localization keys:

### Quest Book
| Pattern | Usage |
|---------|-------|
| `quest.<questId>.name` | Quest display name |
| `quest.<questId>.description` | Quest description |
| `quest.<questId>.obj.<objectiveId>` | Objective text |
| `chapter.<chapterId>.name` | Chapter name |
| `chapter.<chapterId>.description` | Chapter description |

### Achievements
| Pattern | Usage |
|---------|-------|
| `achievements.name.<achievementId>` | Achievement name |
| `achievements.desc.<achievementId>` | Achievement description |
| `achievements.title.<titleId>` | Title display text |
| `achievements.book.cat.<categoryId>` | Category name |
| `lootbag.name.<lootbagId>` | Lootbag name |

### Core
| Pattern | Usage |
|---------|-------|
| `citizen.name.<citizenId>` | NPC name, shown on name tags and in NPC chat lines in each viewer's language |
| `shop.ui.cat.<category>` | Shop category label |

A shop's `title` and an entry's `displayName` can be plain text or any language key you define (e.g. `shop.example.title`).

### Info Hub
Info Hub pages keep their texts in the Info Hub files and admin window — see [Info Hub Localization](https://wiki.kyuubisoft.com/hytale/info-hub/localization/).

## Adding Translations

### Step 1: Create Your Custom File

In the mod's `localization/` folder, create a file named `custom_en-US.json`:

```
mods/kyuubisoft_questbook/localization/custom_en-US.json
```

### Step 2: Add Your Keys

```json
{
  "quest.my_quest.name": "The Lost Artifact",
  "quest.my_quest.description": "Find the ancient artifact hidden in the forest ruins.",
  "quest.my_quest.obj.find_artifact": "Search the Forest Ruins"
}
```

### Step 3: Add Other Languages (Optional)

Create `custom_de-DE.json` for German:

```json
{
  "quest.my_quest.name": "Das verlorene Artefakt",
  "quest.my_quest.description": "Finde das alte Artefakt, das in den Waldruinen versteckt ist.",
  "quest.my_quest.obj.find_artifact": "Durchsuche die Waldruinen"
}
```

### Step 4: Reload

```
/ksadmin reload
```

Your new translations are now active.

## Per-Player Language

Since Core 2.8.0 there is **one language choice for all KS mods**. A player sets it once — in `/kssettings` (Language page), with `/kslang` or in the language row of any KS window — and every KS mod, HUD and chat message follows at once.

```
/kslang          — Show your language and the available languages in chat
/kslang de-DE    — German
/kslang auto     — Follow the game language again
```

The language a player sees is chosen in this order:

1. The player's own choice (only if players may choose)
2. The server's default language for players
3. The game language of the player's client (closest available language)
4. English (`en-US`)

Admins set the default language and whether players may choose their own in the **Language** tab of `/ksadmin`. When players may not choose, `/kslang` only shows the language the server set. The choices are stored in `mods/kslang/prefs.json`, shared by all KS mods.

Core ships all 9 languages: en-US, de-DE, es-ES, fr-FR, it-IT, pl-PL, pt-BR, ru-RU, tr-TR. Players with Portuguese (Portugal) get the Brazilian Portuguese texts.

If a key has no translation in the player's language, the English text is used.

## Localization Version

Base localization files use a `_localization_version` field:

```json
{
  "_localization_version": 3,
  "quest.name.example": "Example Quest"
}
```

When a mod update ships a newer version, the mod replaces its base file by itself and keeps the old one as a backup (for example `en-US.json.backup-v38`). That is why your own texts belong in the `custom_` files — they are always read directly and never replaced.

:::note[For mod authors]
When adding new keys to a **base** localization file, bump `_localization_version` (and the version the mod expects). Otherwise servers that already have the file keep the old one and show raw keys for the new texts.
:::

## Overriding Base Translations

You can override any base translation by adding the same key to your custom file. For example, to change the name of a built-in quest:

**Base file** (`en-US.json`):
```json
{
  "quest.name.starter_quest": "A New Beginning"
}
```

**Your custom file** (`custom_en-US.json`):
```json
{
  "quest.name.starter_quest": "Welcome to the Adventure"
}
```

The custom file takes priority, so players will see "Welcome to the Adventure".

## Mod Editor Localization

The [Mod Editor](https://wiki.kyuubisoft.com/hytale/guides/mod-editor-workflow/) includes a localization tab where you can:

- View all translation keys for your content side by side
- Edit translations for multiple languages at once
- See which keys are missing translations
- Export localization files as part of your quest pack

This is especially useful when managing large amounts of content across multiple languages.

## Tips

- **Always use custom files** for your own content. Never edit the base localization files directly — they may be overwritten on update.
- **Use descriptive key names** that include the content type and ID, following the conventions above.
- **Test both languages** after adding translations to catch missing keys early.
- **Keep keys consistent** — if you add a quest, make sure all three keys (name, desc, objective desc) exist in all language files.