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, may be updated)
3. JAR fallback — Built-in defaults inside the plugin JAR

This means your custom translations always take priority, and you can override any base translation by adding the same key to your custom file.

Key Conventions

Each mod follows consistent naming patterns for localization keys:

Quest Book

Pattern	Usage
quest.name.<questId>	Quest display name
quest.desc.<questId>	Quest description
quest.<questId>.obj.<objectiveId>.desc	Objective description
chapter.name.<chapterId>	Chapter name
chapter.desc.<chapterId>	Chapter description

Achievements

Pattern	Usage
achievement.name.<achievementId>	Achievement name
achievement.desc.<achievementId>	Achievement description
title.name.<titleId>	Title display text
lootbag.name.<lootbagId>	Lootbag name

Core

Pattern	Usage
citizen.name.<citizenId>	Citizen display name
shop.name.<shopId>	Shop name
shop.category.<categoryId>	Shop category name

Info Hub

Pattern	Usage
info.section.<sectionId>	Section title
info.entry.<entryId>	Entry content

Adding Translations

Step 1: Create Your Custom File

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

configs/kyuubisoft_questbook/localization/custom_en-US.json

Step 2: Add Your Keys

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

Step 3: Add Other Languages (Optional)

Create custom_de-DE.json for German:

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

Step 4: Reload

/ksadmin reload

Your new translations are now active.

Per-Player Language

Each player can choose their preferred language:

/kslang en-US    — English
/kslang de-DE    — German

The setting is stored per player and persists across sessions. All KyuubiSoft UI, quest text, achievement names, and other content will display in the chosen language — provided translations exist for that language.

If a key has no translation in the player’s language, the system falls back to en-US.

Localization Version

Base localization files use a _localization_version field:

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

Important: When adding new keys to base localization files (not custom), you must bump the _localization_version number. Otherwise, servers that already have the file will not pick up the new keys, because the file-first pattern sees the existing (older) file and skips the update.

This does not apply to custom_ files — those are always read directly.

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

{
  "quest.name.starter_quest": "A New Beginning"
}

Your custom file (custom_en-US.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 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.