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
Section titled “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:
- Custom file —
localization/custom_en-US.json(your additions, never overwritten) - Base file —
localization/en-US.json(shipped with the mod, replaced on updates) - 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
Section titled “Key Conventions”Each mod follows consistent naming patterns for localization keys:
Quest Book
Section titled “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
Section titled “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 |
| 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
Section titled “Info Hub”Info Hub pages keep their texts in the Info Hub files and admin window — see Info Hub Localization.
Adding Translations
Section titled “Adding Translations”Step 1: Create Your Custom File
Section titled “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.jsonStep 2: Add Your Keys
Section titled “Step 2: Add Your Keys”{ "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)
Section titled “Step 3: Add Other Languages (Optional)”Create custom_de-DE.json for German:
{ "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
Section titled “Step 4: Reload”/ksadmin reloadYour new translations are now active.
Per-Player Language
Section titled “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 againThe language a player sees is chosen in this order:
- The player’s own choice (only if players may choose)
- The server’s default language for players
- The game language of the player’s client (closest available language)
- 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
Section titled “Localization Version”Base localization files use a _localization_version field:
{ "_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.
Overriding Base Translations
Section titled “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
Section titled “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.
- 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.