Translation and displayed text customization

discord-mcbe provides messages for the different places where it displays information. When you want to change a message, you can customize it through translation_overrides in the config file without editing the code.

How to customize displayed text

Use the setting that matches what you want to change:

What you want to change	Setting
The Bot and console language	language (an available locale)
One specific message	translation_overrides

To change one specific message, add its replacement to translation_overrides as follows:

{
  "language": "en-US",
  "translation_overrides": {
    "minecraft.message": "§b[Chat]§r <%0§r> %1§r",
    "discord.join": "🎉 %0 joined the game!",
    "command.help.commands": "Available commands:"
  }
}

Tips

• Edit only the translation_overrides section of your existing config.json; do not delete the rest of the configuration.
• Use keys shown in the table below. A misspelled or unknown key is rejected by configuration validation.
• Preserve placeholders such as %0; they are where values such as player names and message text are inserted.
• Set the entire value to "$key" to reuse another translation in the same locale (for example, "command.help.silent.description": "$common.silent.description"). If the target is absent in that locale, en-US is used. Missing targets and cycles cause an error.
• Minecraft messages can use color codes such as §a. Discord messages are interpreted as Discord Markdown, so format characters matter.
• Restart discord-mcbe after changing the configuration.

Translation key list

Find the key you want to change in the table. Its language selector is independent from the docs site’s display language.

Key	Value	Inherited from
minecraft.connect	§9[discord-mcbe]§r §7Connected to %0§r
minecraft.message	§9[Discord]§r <%0§r> %1§r
minecraft.message.withAttachments	§9[Discord]§r <%0§r> §o§7(%1 files)§r
minecraft.reply	§9[Discord]§r <%0§r> §7[Reply: <%1§r§7> %2]§r %3§r
minecraft.reply.withAttachments	§9[Discord]§r <%0§r> §7[Reply: <%1§r§7> %2]§r §o§7(%3 files)§r
discord.ready	Connection server has started
discord.connect	Connected to the world
discord.disconnect	Disconnected from the world
discord.chat	<%0> %1
discord.chat.multipleWorlds	[%0] <%1> %2
discord.join	%0 joined the game
discord.leave	%0 left the game
discord.panel.uptime	Uptime
command.error.catch	❌ An error has occurred while processing Interaction
command.error.noworlds	Not connected to world
command.error.nopermission	You don't have permission to use this command
command.ping.description	Check the connection status with the world
command.help.description	Show the available commands
command.help.commands	List of commands:
command.help.silent.description	Whether to send the result only to yourself
command.list.description	Displays the number of players connected to the world
command.list.silent.description	Whether to send the result only to yourself
command.list.world.description	Specify the world to display the number of players
command.list.players	Player Count
command.panel.description	Manage status panels
command.panel.create.description	Create a new status panel
command.panel.create.success	Status panel created in channel %0
command.panel.show.description	Show the status panel
command.panel.show.notFound	Status panel is not configured yet
command.command.description	Send a command to the world
command.command.command.description	The command to execute
command.command.raw.description	Display the return value of the command in JSON format
command.command.silent.description	Whether to send the result only to yourself
command.command.world.description	Specify the world to execute the command in
command.command.sending	Sending command...
console.login	Logged in as %0
console.socket.ready	[Local] SocketBridge server is listening on port: %0
console.socket.command	[Local] Enter one of the following commands in Minecraft to connect:
console.script.ready	[BDS] Bridge server is listening on port: %0
console.update.available	A new version of %0 is available: v%2 (current: v%1)
console.connect	[%0] Connected to the world
console.disconnect	[%0] Disconnected from the world
console.join	[%0] %1 joined the game
console.leave	[%0] %1 left the game
console.message	[Discord | %0] <%1> %2
console.message.withAttachments	[Discord | %0] <%1> (%2 files)
console.reply	[Discord | %0] <%1> [Reply: <%2> %3] %4
console.reply.withAttachments	[Discord | %0] <%1> [Reply: <%2> %3] (%4 files)
console.command	[Discord | %0] <%1> %2
console.chat	[%0] <%1> %2
common.silent.description	Whether to send the result only to yourself
common.duration	%0h %1m %2s
common.noOnlineWorlds	There are currently no online worlds.
common.worldNotFound	World %0 not found
death.attack.anvil	%0 was squashed by a falling anvil
death.attack.arrow	%0 was shot by %1
death.attack.arrow.item	%0 was shot by %1 using %2
death.attack.bullet	%0 was sniped by %1
death.attack.cactus	%0 was pricked to death
death.attack.cactus.player	%0 walked into a cactus whilst trying to escape %1
death.attack.dehydration	%0 died from dehydration
death.attack.drown	%0 drowned
death.attack.drown.player	%0 drowned whilst trying to escape %1
death.attack.explosion	%0 blew up
death.attack.explosion.by.bed	%0 was killed by [Intentional Game Design]
death.attack.explosion.player	%0 was blown up by %1
death.attack.fall	%0 hit the ground too hard
death.attack.fallingBlock	%0 was squashed by a falling block
death.attack.fireball	%0 was fireballed by %1
death.attack.fireball.item	%0 was fireballed by %1 using %2
death.attack.fireworks	%0 went off with a bang
death.attack.flyIntoWall	%0 experienced kinetic energy
death.attack.generic	%0 died
death.attack.indirectMagic	%0 was killed by %1 using magic
death.attack.indirectMagic.item	%0 was killed by %1 using %2
death.attack.inFire	%0 went up in flames
death.attack.inFire.player	%0 walked into fire whilst fighting %1
death.attack.inWall	%0 suffocated in a wall
death.attack.lava	%0 tried to swim in lava
death.attack.lava.player	%0 tried to swim in lava to escape %1
death.attack.lightningBolt	%0 was struck by lightning
death.attack.maceSmash.player	%0 was smashed by %1
death.attack.maceSmash.player.item	%0 was smashed by %1 with %2
death.attack.magic	%0 was killed by magic
death.attack.magma	%0 discovered the floor was lava
death.attack.magma.player	%0 walked on danger zone due to %1
death.attack.mob	%0 was slain by %1
death.attack.mob.item	%0 was slain by %1 using %2
death.attack.onFire	%0 burned to death
death.attack.onFire.player	%0 was burnt to a crisp whilst fighting %1
death.attack.outOfWorld	%0 fell out of the world
death.attack.player	%0 was slain by %1
death.attack.player.item	%0 was slain by %1 using %2
death.attack.spit	%0 was spitballed by %1
death.attack.starve	%0 starved to death
death.attack.sulfurCube.hot	%0 died because not just the floor is lava
death.attack.sweetBerry	%0 was poked to death by a sweet berry bush
death.attack.thorns	%0 was killed trying to hurt %1
death.attack.thrown	%0 was pummeled by %1
death.attack.thrown.item	%0 was pummeled by %1 using %2
death.attack.trident	%0 was impaled to death by %1
death.attack.wither	%0 withered away
death.attack.freeze	%0 froze to death
death.attack.sonicBoom	%0 was obliterated by a sonically-charged shriek
death.attack.sonicBoom.player	%0 was obliterated by a sonically-charged shriek whilst trying to escape %1
death.attack.stalactite	%0 was skewered by a falling stalactite
death.attack.stalagmite	%0 was impaled on a stalagmite
death.fell.accident.generic	%0 fell from a high place
death.fell.accident.ladder	%0 fell off a ladder
death.fell.accident.vines	%0 fell off some vines
death.fell.accident.water	%0 fell out of the water
death.fell.assist	%0 was doomed to fall by %1
death.fell.assist.item	%0 was doomed to fall by %1 using %2
death.fell.finish	%0 fell too far and was finished by %1
death.fell.finish.item	%0 fell too far and was finished by %1 using %2
death.fell.killer	%0 was doomed to fall
entity.agent.name	Agent
entity.area_effect_cloud.name	Area Effect Cloud
entity.armadillo.name	Armadillo
entity.armor_stand.name	Armor Stand
entity.arrow.name	Arrow
entity.bat.name	Bat
entity.bee.name	Bee
entity.blaze.name	Blaze
entity.boat.name	Boat
entity.bogged.name	Bogged
entity.breeze.name	Breeze
entity.breeze_wind_charge_projectile.name	Wind Charge
entity.cat.name	Cat
entity.cave_spider.name	Cave Spider
entity.chicken.name	Chicken
entity.cow.name	Cow
entity.creaking.name	Creaking
entity.creeper.name	Creeper
entity.dolphin.name	Dolphin
entity.goat.name	Goat
entity.panda.name	Panda
entity.donkey.name	Donkey
entity.dragon_fireball.name	Dragon Fireball
entity.drowned.name	Drowned
entity.egg.name	Egg
entity.elder_guardian.name	Elder Guardian
entity.ender_crystal.name	Ender Crystal
entity.ender_dragon.name	Ender Dragon
entity.enderman.name	Enderman
entity.endermite.name	Endermite
entity.ender_pearl.name	Ender Pearl
entity.evocation_illager.name	Evoker
entity.evocation_fang.name	Evoker Fang
entity.eye_of_ender_signal.name	Eye of Ender
entity.falling_block.name	Falling Block
entity.fireball.name	Fireball
entity.fireworks_rocket.name	Firework Rocket
entity.fishing_hook.name	Fishing Hook
entity.fish.clownfish.name	Clownfish
entity.fox.name	Fox
entity.cod.name	Cod
entity.pufferfish.name	Pufferfish
entity.salmon.name	Salmon
entity.tropicalfish.name	Tropical Fish
entity.axolotl.name	Axolotl
entity.ghast.name	Ghast
entity.glow_squid.name	Glow Squid
entity.piglin_brute.name	Piglin Brute
entity.guardian.name	Guardian
entity.hoglin.name	Hoglin
entity.horse.name	Horse
entity.husk.name	Husk
entity.ravager.name	Ravager
entity.iron_golem.name	Iron Golem
entity.item.name	Item
entity.leash_knot.name	Leash Knot
entity.lightning_bolt.name	Lightning Bolt
entity.lingering_potion.name	Lingering Potion
entity.llama.name	Llama
entity.trader_llama.name	Trader Llama
entity.llama_spit.name	Llama Spit
entity.magma_cube.name	Magma Cube
entity.minecart.name	Minecart
entity.chest_minecart.name	Minecart with Chest
entity.command_block_minecart.name	Minecart with Command Block
entity.furnace_minecart.name	Minecart with Furnace
entity.hopper_minecart.name	Minecart with Hopper
entity.tnt_minecart.name	Minecart with TNT
entity.mule.name	Mule
entity.mooshroom.name	Mooshroom
entity.moving_block.name	Moving Block
entity.npc.name	NPC
entity.ocelot.name	Ocelot
entity.ominous_item_spawner.name	Ominous Item Spawner
entity.painting.name	Painting
entity.parrot.name	Parrot
entity.phantom.name	Phantom
entity.pig.name	Pig
entity.piglin.name	Piglin
entity.pillager.name	Pillager
entity.player.name	Player
entity.polar_bear.name	Polar Bear
entity.rabbit.name	Rabbit
entity.sheep.name	Sheep
entity.shulker.name	Shulker
entity.shulker_bullet.name	Shulker Bullet
entity.silverfish.name	Silverfish
entity.skeleton.name	Skeleton
entity.skeleton_horse.name	Skeleton Horse
entity.stray.name	Stray
entity.slime.name	Slime
entity.small_fireball.name	Small Fireball
entity.sniffer.name	Sniffer
entity.snowball.name	Snowball
entity.snow_golem.name	Snow Golem
entity.spider.name	Spider
entity.splash_potion.name	Potion
entity.squid.name	Squid
entity.strider.name	Strider
entity.tnt.name	Block of TNT
entity.thrown_trident.name	Trident
entity.tripod_camera.name	Tripod Camera
entity.turtle.name	Turtle
entity.unknown.name	Unknown
entity.vex.name	Vex
entity.villager.name	Villager
entity.villager.armor	Armorer
entity.villager.butcher	Butcher
entity.villager.cartographer	Cartographer
entity.villager.cleric	Cleric
entity.villager.farmer	Farmer
entity.villager.fisherman	Fisherman
entity.villager.fletcher	Fletcher
entity.villager.leather	Leatherworker
entity.villager.librarian	Librarian
entity.villager.shepherd	Shepherd
entity.villager.tool	Tool Smith
entity.villager.weapon	Weapon Smith
entity.villager.mason	Mason
entity.villager.unskilled	Unskilled Villager
entity.villager_v2.name	Villager
entity.vindicator.name	Vindicator
entity.wandering_trader.name	Wandering Trader
entity.wind_charge_projectile.name	Wind Charge
entity.witch.name	Witch
entity.wither.name	Wither
entity.wither_skeleton.name	Wither Skeleton
entity.wither_skull.name	Wither Skull
entity.wither_skull_dangerous.name	Wither Skull
entity.wolf.name	Wolf
entity.xp_orb.name	Experience Orb
entity.xp_bottle.name	Bottle o' Enchanting
entity.zoglin.name	Zoglin
entity.zombie.name	Zombie
entity.zombie_horse.name	Zombie Horse
entity.zombie_pigman.name	Zombified Piglin
entity.zombie_villager.name	Zombie Villager
entity.zombie_villager_v2.name	Zombie Villager
entity.frog.name	Frog
entity.tadpole.name	Tadpole
entity.warden.name	Warden
entity.allay.name	Allay
entity.chest_boat.name	Boat with Chest
entity.camel.name	Camel
entity.chest_raft.name	Raft with Chest
entity.happy_ghast.name	Happy Ghast
entity.copper_golem.name	Copper Golem
entity.sulfur_cube.name	Sulfur Cube
entity.nautilus.name	Nautilus
entity.zombie_nautilus.name	Zombie Nautilus
entity.parched.name	Parched
entity.camel_husk.name	Camel Husk

For developers and contributors

How the translation system works

Translations are pairs of keys and values. Code refers to a key such as discord.join instead of embedding the displayed sentence directly.

Layer	Location	Purpose
Regular displayed text	projects/server/src/assets/locales/<locale>.json	Discord, console, Minecraft chat, and command descriptions
Minecraft-derived text	<locale>.generated.json	Death messages and entity names generated from Mojang language files
Runtime language	config.json → language	Selects an available locale
User overrides	config.json → translation_overrides	Replaces individual values in the selected language

At startup, discord-mcbe merges the regular and .generated.json files for the selected language, then applies translation_overrides. If a key is missing in the selected language, it falls back to the baseline locale (en-US); if the baseline also has no value, the key itself is displayed.

translation_overrides is not a nested per-language object; it is applied to the runtime map selected by config.language. If the Bot language changes, the same override value is applied to that language. For different text per language, change each source JSON.

config.translation_overrides can override keys that exist in the baseline locale (en-US). Extra keys found only in a locale file are not valid override targets. Inherited from is shown only when the selected language has no value and the value is supplied by the baseline locale.

Values can contain %0, %1, and other placeholders. They are replaced by arguments passed from the code in order. References written as $key retain the target’s placeholders.

Key: minecraft.message
Value: §9[Discord]§r <%0§r> %1§r
Result: §9[Discord]§r <Steve> hello§r

Change regular displayed text

Edit these files for discord-mcbe-owned text such as Discord messages, console messages, Minecraft chat wrappers, and command descriptions:

projects/server/src/assets/locales/<locale>.json

Use the baseline locale (currently en-US) for keys and arguments. Keep the same keys in every locale and keep the placeholder count and %0-based numbering aligned. After adding or removing keys, regenerate the types and config schema:

pnpm --filter @discord-mcbe/server generate-lang-types
pnpm --filter @discord-mcbe/server generate-schema

About Minecraft death messages and entity names

death.* and entity.* belong in generated files:

projects/server/src/assets/locales/<locale>.generated.json

These files are generated by the extract-minecraft-lang script from the language files in Mojang/bedrock-samples. Mojang-style placeholders such as %1$s are converted to discord-mcbe’s zero-based %0 format. Do not edit these files manually.

pnpm --filter @discord-mcbe/server extract-minecraft-lang
pnpm --filter @discord-mcbe/server generate-lang-types
pnpm --filter @discord-mcbe/server generate-schema

Add non-Mojang, discord-mcbe-owned messages to the regular JSON for each locale.

Add a language

To add a language:

1. Add translations to projects/server/src/assets/locales/<locale>.json.
2. Add the locale to the locales variable in projects/server/scripts/extract-minecraft-lang.ts to extract its Minecraft translations.
3. Import and register the JSON files in templateMap in projects/server/src/util/i18n.ts.
4. Run generate-lang-types and generate-schema.
5. Verify that the translations are displayed correctly.