# Localization

# Localization

**Version:** 1.12.1 · **Localization file version:** 18

KyuubiSoft Pets ships 9 languages, all complete since 1.12.1. Most chat messages, every reply of `/kspetadmin` and the texts of the compendium, the pickup filter, the pet HUD and the admin window come from one JSON file per language on the server, so you can change them. A few messages, such as the usage lines of the player commands `/kspet`, `/kscombatpet` and `/ksmount`, are fixed English text in the plugin.

## Files

The language files live in the plugin's data folder:

```
mods/kyuubisoft_pets/localization/
  en-US.json
  de-DE.json
  fr-FR.json
  es-ES.json
  pt-BR.json
  it-IT.json
  pl-PL.json
  tr-TR.json
  ru-RU.json
```

They are written on the first start. Each file is a flat JSON object of `"key": "text"` pairs plus the field `"_localization_version": "18"`.

| Code | Language | Coverage in 1.12.1 |
|------|----------|--------------------|
| `en-US` | English | Complete (498 texts) |
| `de-DE` | Deutsch | Complete (498 texts) |
| `fr-FR` | Français | Complete (498 texts) |
| `es-ES` | Español | Complete (498 texts) |
| `pt-BR` | Português (BR) | Complete (498 texts) |
| `it-IT` | Italiano | Complete (498 texts) |
| `pl-PL` | Polski | Complete (498 texts) |
| `tr-TR` | Türkçe | Complete (498 texts) |
| `ru-RU` | Русский | Complete (498 texts) |

Before 1.12.1, the seven languages other than English and German lacked 143 texts (compendium, pickup filter window, and the newer combat pet, HUD, revival, restore and reroll messages), which were shown in English. 1.12.1 translated them and added 89 texts for `/kspetadmin` and the restore reasons.

:::note
Some windows are partly fixed English text and are not in the language files: the classic pet menu, the layouts of the collection and bestiary windows, the combat pet and mount pages, the scroll windows, the HUD position names and the chat answers of `/kslang`. See [UI Pages](./ui-pages).
:::

## Updates and backups

The plugin checks the nine bundled files on every start and on `/kspetadmin reload`:

- A missing file is written from the jar.
- A file with a lower `_localization_version` than the plugin's (a file without the field counts as version 1) is copied to `<lang>.json.backup-v<old>` and replaced by the new file from the jar. Example: `fr-FR.json.backup-v13`.
- A file with version 18 or higher is left as it is.

1.12.1 raised the version to 18, so on the first start with 1.12.1 every older bundled file is backed up and replaced once.

:::caution
Your own changes to a bundled file survive restarts and reloads, but not a plugin update that raises the version. After such an update, copy your changes back from the `.backup-v<old>` file. Never lower `_localization_version`, or the file is replaced at the next start.
:::

Language files you added yourself (any other file name) are never replaced.

## How a player's language is chosen

1. **The language the player picked** with `/kslang` or in the KS settings window (`/kssettings`, with KyuubiSoft Core), if the player picked one and the server lets players choose. It is stored in `mods/kslang/prefs.json` and shared by all KyuubiSoft mods.
2. **Otherwise the server's default player language**, if the server set one.
3. **Otherwise the language the game client reports**, matched to the closest bundled language (for example `de-AT` uses `de-DE`).
4. **Otherwise `en-US`.**

The default player language and the "players may choose" switch are set in the Language tab of Core's `/ksadmin` hub (KyuubiSoft Core 2.8.0 or newer) and stored in the same shared file, so every KyuubiSoft mod uses them. When players may not choose, a stored choice is kept but ignored until choosing is allowed again.

For each text the plugin then uses:

1. the text from that language's file,
2. if the file does not exist or has no such key: the English text from `en-US.json`,
3. if that is missing too: the key itself (for example `pet.compendium.title`).

A change with `/kslang` applies to the next chat message and the next window that opens; the player does not need to rejoin. The HUD switches with its next update.

## /kslang and the shared language choice

`/kslang` is the language command of all KyuubiSoft mods. The first KyuubiSoft mod that loads registers it; Pets brings its own copy, so the command also exists on a server that only runs Pets.

| Command | Effect |
|---------|--------|
| `/kslang <code>` | Picks a language, for example `/kslang de-DE` (`/kslang dede` works too) |
| `/kslang auto` or `/kslang reset` | Removes the choice; the client language is used again |
| `/kslang` | Answers in chat: the current language (chosen or taken from the game), the available codes and how to change it |

An unknown code prints the list of available codes. When the server sets the language for everyone ("players may choose" switched off), `/kslang` says so instead of storing a choice. `/kslang <code>` accepts the languages whose files were in the localization folder when the server started (on the very first start, the nine bundled ones). Exact syntax: [Commands](./commands).

The shared folder `mods/kslang/` (next to `mods/kyuubisoft_pets/`) holds:

| File | Content |
|------|---------|
| `prefs.json` | Player UUID to language code, for players who picked a language |
| `mods.json` | The KyuubiSoft mods that use the shared choice (Pets registers itself as "Pets") |

Pets re-reads `prefs.json` at most every 5 seconds, so a choice made through another KyuubiSoft mod shows up in Pets shortly after.

## Editing texts

1. Open `mods/kyuubisoft_pets/localization/<code>.json` with a text editor and save it as UTF-8 (some texts contain characters like `·` and `→`).
2. Change only the texts on the right side. Keep the keys and `"_localization_version": "18"`.
3. Run `/kspetadmin reload` (or click **Reload** in the [admin window](./admin-panel)), or restart the server.
4. Keep a copy of your changes for the next plugin update (see [Updates and backups](#updates-and-backups)).

## Adding a language

1. Copy `en-US.json` to a new file named after the language code, for example `nl-NL.json`. The file name without `.json` is the code.
2. Translate the texts. Keep the keys.
3. Restart the server. `/kspetadmin reload` loads the texts too, but `/kslang` only accepts codes that existed at startup.
4. Players with a client that reports `nl-NL` get it automatically; everybody else can pick it with `/kslang nl-NL`.

Files whose name starts with `custom_` or contains `.backup` are not loaded as languages. When a later plugin version adds new keys, they show in English in your language until you add them.

## Placeholders

Texts can contain `{0}`, `{1}`, `{2}` ... (the shipped files use up to `{4}`). The plugin replaces each one with a value as plain text, for example:

```json
"pet.level_up": "Your pet {0} reached level {1}!"
```

- You may move placeholders, use one twice or leave one out.
- There is no other syntax: no `{0,number}`, and apostrophes need no escaping.
- The values arrive already formatted: stat values like `+1.5%`, HUD counts grouped for the player's language (`11,206` in English, `11.206` in German).
- `pet.admin.ui.decimal` is not a sentence but the decimal separator of the admin window (`.` in English, `,` in the other bundled languages).

## Key families

Counts from `en-US.json` in 1.12.1 (498 texts plus `_localization_version`). Since 1.12.1 every family is in all nine bundled files.

| Family | Texts | Used for |
|--------|------:|----------|
| `pet.admin.ui.*` | 180 | Admin window. `pet.admin.ui.bl.*` (37) is the blacklist section, `pet.admin.ui.pl.*` (25) the player pets section, the rest navigation, buttons, messages and the create section |
| `pet.admin.*` (without `ui`) | 89 | Every reply of `/kspetadmin`: usage lines, help, errors, results of the subcommands and the `inspect` output |
| `pet.compendium.*` | 70 | Pet Compendium: tabs, filters, rows, stats, buttons, stage, reroll dice tooltips |
| `pet.filter.ui.*` | 38 | Pickup filter window |
| `pet.combat.*` | 17 | Combat pet chat messages, `/kscombatpet stats`, defeat, recovery and AFK notices |
| `pet.hud.*` | 13 | Pet HUD: kind, level, XP, items, kills, buffs, recovery card |
| `pet.scroll.*` | 12 | Scroll names and scroll error messages |
| `pet.restore.*` | 11 | Messages about items replaced with `/kspetadmin restore`, and the reasons a restore can fail |
| `mount.*` | 8 | Mount chat messages |
| `pet.filter.*` (without `ui`) | 6 | Chat replies of `/kspet filter ...` |
| `pet.stats.*` | 5 | `/kspet stats` |
| `pet.rarity.*` | 5 | Rarity names (Common to Legendary) |
| `pet.reroll_all.*`, `pet.refine_all.*` | 5 + 3 | Reroll All / Refine All windows and messages |
| `pet.bestiary.*` | 4 | Bestiary window |
| `pet.collection.*` | 3 | Collection texts |
| `pet.reroll.*`, `pet.refine.*` | 3 + 2 | Reroll and refine messages |
| `pet.revive.*` | 3 | Battle Pet Revival Scroll messages |
| other `pet.*` | 21 | General messages: prefix, summon, dismiss, rename, level-up, pickup, discovery, missing item, module disabled, pet limit, removed pets, egg |

The complete, current list is always `en-US.json` in your localization folder.