# Localization

# Localization

The plugin ships every text in 9 languages and shows each player the book, the HUD, messages, item names and dates in their own language. Broadcasts reach every player in their own language as well.

## Supported Languages

| Language | Code |
|----------|------|
| English | `en-US` |
| German | `de-DE` |
| Spanish | `es-ES` |
| French | `fr-FR` |
| Italian | `it-IT` |
| Polish | `pl-PL` |
| Portuguese (Brazil) | `pt-BR` |
| Russian | `ru-RU` |
| Turkish | `tr-TR` |

The localization version of 3.1.6 is **18**. With 3.1.2 the Turkish and French texts got their special letters back (about 1,100 Turkish and 550 French texts), so updated servers receive the shipped language files again; your `custom_<lang>.json` files stay untouched.

## Choosing the language

- **Players** choose their language for all KyuubiSoft mods in the shared settings window `/kssettings` (KyuubiSoft Core 2.8.0+) or with `/kslang <code>` / `/kslang auto`. The language line in the book settings opens the same page. One choice applies to every KyuubiSoft mod.
- **The server** sets its language, the default for new players and whether players may choose in `/kssettings`. The admin window of Achievements links there instead of having its own language field.

## Language Files

```
mods/kyuubisoft_achievements/localization/
├── en-US.json ... tr-TR.json     # shipped texts (replaced when a newer version ships)
├── custom_<lang>.json            # your own texts (never overwritten)
└── custom_en-US.json.example, custom_de-DE.json.example
```

Translations are loaded in this order; later files win:

1. `localization/<lang>.json` - shipped translations
2. `localization/custom_<lang>.json` - your overrides and additions

:::tip
Always put your own texts into `custom_<lang>.json`. The shipped files are replaced when a new version brings newer texts.
:::

Since 3.0.0, translation edits made with the KyuubiSoft web editor are also saved into `custom_<lang>.json`, so they survive updates. The admin window keeps texts per language in the editor itself (a missing language is shown in grey and never saved).

## Key Structure

| Key | Used for |
|-----|----------|
| `achievements.name.<id>` | Achievement name |
| `achievements.desc.<id>` | Achievement description |
| `achievements.title.<titleId>` | Title name |
| `achievements.hint.<id>` | Optional hint for a hidden achievement |
| `achievements.book.cat.<category>` | Category name in the book |
| `lootbag.name.<id>`, `lootbag.desc.<id>` | Lootbag name and description |
| `lootbag.rarity.<rarity>` | Rarity name (common, uncommon, rare, epic, legendary) |
| `achievements.book.*`, `achievements.hud.*`, `achievements.settings.*`, `rewards.ui.*` | Book, HUD, settings and rewards texts |
| `aadmin.*` | Admin window |

Item names come from the game's own translations.

### Example: custom translation file

**localization/custom_en-US.json:**
```json
{
  "achievements.name.my_custom_achievement": "My Custom Achievement",
  "achievements.desc.my_custom_achievement": "Mine 100 blocks of any type",
  "achievements.title.my_custom_title": "Stonebreaker",
  "achievements.hint.secret_easter_egg": "Look behind the waterfall.",
  "lootbag.name.my_custom_bag": "Treasure Chest",
  "lootbag.desc.my_custom_bag": "Contains rare treasures!"
}
```

**localization/custom_de-DE.json:**
```json
{
  "achievements.name.my_custom_achievement": "Mein eigener Erfolg",
  "achievements.desc.my_custom_achievement": "Baue 100 Blöcke beliebiger Art ab"
}
```

### Fallback Behavior

If a text is missing in the player's language, a fallback language is used (in the end English). If an achievement has no name at all, its `id` is shown as a readable name (`my_custom_achievement` becomes "My Custom Achievement").

## Placeholders

Texts use numbered placeholders: `{0}` is the first value, `{1}` the second, and so on.

```json
{
  "achievements.trigger.mine_target": "Mine {0} {1}"
}
```

## Applying changes

Reload with `/ksadmin reload` (KyuubiSoft Core) after editing translation files by hand.