Localization

The Season Pass uses a file-first localization system with automatic version management. Nine languages are bundled by default.

File Location

configs/kyuubisoft_seasonpass/localization/
├── en-US.json    # English (default)
├── de-DE.json    # German
├── fr-FR.json    # French
├── es-ES.json    # Spanish
├── pt-BR.json    # Portuguese (Brazil)
├── ru-RU.json    # Russian
├── pl-PL.json    # Polish
├── tr-TR.json    # Turkish
└── it-IT.json    # Italian

Language Setting

Set the active language in config.json:

{
  "language": "en-US"
}

File-First Pattern

The plugin checks localization/{lang}.json on disk
If the file doesn’t exist, it extracts the default from the JAR
Missing keys fall back to en-US
User edits to the file are preserved across updates

Version Management

Each localization file contains a _localization_version field:

{
  "_localization_version": "9",
  "seasonpass.ui.title": "Season Pass",
  ...
}

When the plugin ships new keys (version bump), it:

Creates a backup of the existing file (e.g., en-US.json.backup-v8)
Replaces the file with the new version from the JAR
Updates the _localization_version field
Previous user edits are preserved in the backup file

:::info Version Bump Required When adding new i18n keys to a custom build, you must bump the _localization_version number. Otherwise, deployed files will NOT be updated (file-first pattern skips files that already exist). :::

Key Categories

Commands (`seasonpass.cmd.*`)

Key	Default (en-US)
`seasonpass.cmd.players_only`	This command is for players only
`seasonpass.cmd.no_permission`	You don’t have permission
`seasonpass.cmd.player_not_found`	Player not found
`seasonpass.cmd.season_info`	Season info message
`seasonpass.cmd.no_active_season`	No active season
`seasonpass.cmd.premium_already`	You already have premium
`seasonpass.cmd.premium_disabled`	Premium is disabled
`seasonpass.cmd.premium_purchased`	Premium purchased
`seasonpass.cmd.premium_insufficient`	Not enough currency
`seasonpass.cmd.opening`	Opening Season Pass…

UI (`seasonpass.ui.*`)

Key	Default (en-US)
`seasonpass.ui.title`	Season Pass
`seasonpass.ui.tab_tiers`	Tiers
`seasonpass.ui.tab_challenges`	Challenges
`seasonpass.ui.tab_shop`	Shop
`seasonpass.ui.tab_history`	History
`seasonpass.ui.tab_settings`	Settings
`seasonpass.ui.free_track`	Free
`seasonpass.ui.premium_track`	Premium
`seasonpass.ui.bonus_track`	Bonus
`seasonpass.ui.season_ends_in`	Season ends in: {0}
`seasonpass.ui.xp_progress`	{0} / {1} XP
`seasonpass.ui.token_balance`	{0} Tokens
`seasonpass.ui.premium_badge`	PREMIUM

Tiers (`seasonpass.tier.*`)

Key	Default (en-US)
`seasonpass.tier.tier_up`	Tier Up! You reached Tier {0}
`seasonpass.tier.claim`	Claim now
`seasonpass.tier.claimed`	Claimed
`seasonpass.tier.locked`	Locked
`seasonpass.tier.premium_locked`	Premium Only
`seasonpass.tier.reward_claimed`	Reward claimed!
`seasonpass.tier.not_reached`	Tier not reached yet
`seasonpass.tier.need_premium`	Premium pass required

Challenges (`seasonpass.challenge.*`)

Key	Default (en-US)
`seasonpass.challenge.kill_mobs`	Kill {0} mobs
`seasonpass.challenge.kill_specific`	Kill {0} {1}
`seasonpass.challenge.break_blocks`	Break {0} blocks
`seasonpass.challenge.break_specific`	Break {0} {1}
`seasonpass.challenge.place_blocks`	Place {0} blocks
`seasonpass.challenge.harvest`	Harvest {0} crops
`seasonpass.challenge.travel`	Travel {0} blocks
`seasonpass.challenge.discover_zone`	Discover {0} zones
`seasonpass.challenge.play_time`	Play for {0} minutes
`seasonpass.challenge.complete`	Challenge completed!

Shop (`seasonpass.shop.*`)

Key	Default (en-US)
`seasonpass.shop.title`	Season Shop
`seasonpass.shop.cost`	{0} Tokens
`seasonpass.shop.buy`	Buy
`seasonpass.shop.sold_out`	SOLD
`seasonpass.shop.purchased`	Purchased {0}!
`seasonpass.shop.not_enough_tokens`	Not enough tokens
`seasonpass.shop.daily_rotation`	Daily Rotation
`seasonpass.shop.refreshes_in`	Refreshes in: {0}

Admin (`seasonpass.admin.*`)

Key	Default (en-US)
`seasonpass.admin.season_started`	Season {0} started
`seasonpass.admin.season_ended`	Season ended
`seasonpass.admin.season_paused`	Season paused
`seasonpass.admin.season_resumed`	Season resumed
`seasonpass.admin.config_reloaded`	Configuration reloaded
`seasonpass.admin.xp_granted`	Granted {0} XP to {1}
`seasonpass.admin.tokens_granted`	Granted {0} tokens to {1}
`seasonpass.admin.premium_granted`	Premium granted to {0}
`seasonpass.admin.premium_revoked`	Premium revoked from {0}
`seasonpass.admin.tier_set`	Set {0}‘s tier to {1}
`seasonpass.admin.player_reset`	Reset {0}‘s season data

Settings (`seasonpass.settings.*`)

Key	Default (en-US)
`seasonpass.settings.title`	Season Pass Settings
`seasonpass.settings.hud_enabled`	Show HUD Tracker
`seasonpass.settings.hud_position`	HUD Position
`seasonpass.settings.xp_notifications`	XP Notifications
`seasonpass.settings.xp_all`	All
`seasonpass.settings.xp_large`	Large only
`seasonpass.settings.xp_off`	Off
`seasonpass.settings.xp_notif.all`	All
`seasonpass.settings.xp_notif.large`	Large only
`seasonpass.settings.xp_notif.none`	Off
`seasonpass.settings.tier_notifications`	Tier Up Notifications
`seasonpass.settings.challenge_notifications`	Challenge Notifications
`seasonpass.settings.save`	Save Settings
`seasonpass.settings.saved`	Settings saved!

Boosters (`seasonpass.booster.*`)

Key	Default (en-US)
`seasonpass.booster.activated`	XP Booster activated! {0}x for {1} minutes.
`seasonpass.booster.expired`	Your XP Booster has expired.
`seasonpass.booster.active_multiplier`	{0}x XP \| {1}
`seasonpass.booster.status`	Booster: {0}x ({1} remaining)
`seasonpass.booster.replaced`	Your previous booster was replaced with a new one.

Events (`seasonpass.event.*`)

Key	Default (en-US)
`seasonpass.event.started`	DOUBLE XP EVENT! {0}x XP for {1} minutes!
`seasonpass.event.ended`	The Double XP Event has ended.
`seasonpass.event.status`	Event: {0}x XP ({1} remaining)
`seasonpass.event.warning_5min`	The Double XP Event ends in 5 minutes!

Prestige (`seasonpass.prestige.*`)

Key	Default (en-US)
`seasonpass.prestige.button`	PRESTIGE
`seasonpass.prestige.achieved`	PRESTIGE! You reached Prestige Level {0}!
`seasonpass.prestige.level`	Prestige {0}
`seasonpass.prestige.xp_boost`	+{0}% XP Boost from Prestige
`seasonpass.prestige.max_reached`	Maximum Prestige Level reached!
`seasonpass.prestige.disabled`	Prestige is not enabled for this season.
`seasonpass.prestige.badge`	P{0}

Claim All (`seasonpass.claim_all.*`)

Key	Default (en-US)
`seasonpass.claim_all.button`	Claim All ({0})
`seasonpass.claim_all.success`	Claimed {0} rewards!
`seasonpass.claim_all.nothing`	No rewards available to claim.

Season Status (`seasonpass.season.*`)

Key	Default (en-US)
`seasonpass.season.active`	Active
`seasonpass.season.ended`	Ended
`seasonpass.season.paused`	Paused
`seasonpass.season.teaser`	Coming Soon
`seasonpass.season.not_started`	Not Started

XP Sources (`seasonpass.xp.*`)

Key	Default (en-US)
`seasonpass.xp.block_broken`	Block broken
`seasonpass.xp.block_placed`	Block placed
`seasonpass.xp.mob_kill`	Mob killed
`seasonpass.xp.pvp_kill`	PvP kill
`seasonpass.xp.playtime`	Playtime
`seasonpass.xp.zone_discovered`	Zone discovered
`seasonpass.xp.daily_login`	Daily login
`seasonpass.xp.login_streak`	Login streak
`seasonpass.xp.quest_completed`	Quest completed
`seasonpass.xp.achievement_unlocked`	Achievement unlocked
`seasonpass.xp.challenge`	Challenge reward
`seasonpass.xp.first_login_bonus`	First login bonus

Errors (`seasonpass.error.*`)

Key	Default (en-US)
`seasonpass.error.no_data`	Could not load your season data.
`seasonpass.error.save_failed`	Failed to save data.
`seasonpass.error.season_inactive`	No season is currently active.
`seasonpass.error.already_claimed`	Reward already claimed.
`seasonpass.error.tier_not_reached`	You haven’t reached this tier yet.
`seasonpass.error.premium_required`	Premium pass required.

Premium Content (`seasonpass.challenges.`, `seasonpass.shop.`)

Key	Default (en-US)
`seasonpass.challenges.premium_header`	PREMIUM CHALLENGES
`seasonpass.challenges.premium_locked`	Premium Pass required for bonus challenges
`seasonpass.shop.premium_header`	PREMIUM SHOP
`seasonpass.shop.premium_locked`	Premium Pass required for exclusive items
`seasonpass.cmd.premium_command_only`	The Premium Pass can only be granted by an admin.
`seasonpass.ui.premium_contact_admin`	Contact an admin to get the Premium Pass

Custom Translations

The Season Pass supports custom per-language translation overrides. Use the setCustomTranslation() API to set a custom value for any key. Custom translations are saved to custom_{lang}.json files in the localization folder (e.g., custom_en-US.json).

Adding a Custom Translation

Copy en-US.json and rename to your locale (e.g., fr-FR.json)
Translate all values (keep the keys unchanged)
Set "language": "fr-FR" in config.json
Reload with /spadmin reload

:::tip Partial Translations You don’t need to translate every key. Any missing key automatically falls back to the en-US value. :::

Localization

Localization

File Location

Language Setting

File-First Pattern

Version Management

Key Categories

Commands (seasonpass.cmd.*)

UI (seasonpass.ui.*)

Tiers (seasonpass.tier.*)

Challenges (seasonpass.challenge.*)

Shop (seasonpass.shop.*)

Admin (seasonpass.admin.*)

Settings (seasonpass.settings.*)

Boosters (seasonpass.booster.*)

Events (seasonpass.event.*)

Prestige (seasonpass.prestige.*)

Claim All (seasonpass.claim_all.*)

Season Status (seasonpass.season.*)

XP Sources (seasonpass.xp.*)

Errors (seasonpass.error.*)

Premium Content (seasonpass.challenges.*, seasonpass.shop.*)

Custom Translations

Adding a Custom Translation

Commands (`seasonpass.cmd.*`)

UI (`seasonpass.ui.*`)

Tiers (`seasonpass.tier.*`)

Challenges (`seasonpass.challenge.*`)

Shop (`seasonpass.shop.*`)

Admin (`seasonpass.admin.*`)

Settings (`seasonpass.settings.*`)

Boosters (`seasonpass.booster.*`)

Events (`seasonpass.event.*`)

Prestige (`seasonpass.prestige.*`)

Claim All (`seasonpass.claim_all.*`)

Season Status (`seasonpass.season.*`)

XP Sources (`seasonpass.xp.*`)

Errors (`seasonpass.error.*`)

Premium Content (`seasonpass.challenges.`, `seasonpass.shop.`)