Skip to content

Localization Guide

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

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

Each mod follows consistent naming patterns for localization keys:

PatternUsage
quest.<questId>.nameQuest display name
quest.<questId>.descriptionQuest description
quest.<questId>.obj.<objectiveId>Objective text
chapter.<chapterId>.nameChapter name
chapter.<chapterId>.descriptionChapter description
PatternUsage
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
PatternUsage
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 pages keep their texts in the Info Hub files and admin window — see Info Hub Localization.

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

mods/kyuubisoft_questbook/localization/custom_en-US.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"
}

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"
}
/ksadmin reload

Your new translations are now active.

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.

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.

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”.

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.