Text and Translations 1.21.8

Comprehensive documentation for Minecraft's handling of formatted text and translations.

WARNING

This page is written for version 1.21.8. Documentation for older versions may be incomplete.

Whenever Minecraft displays text in-game, it's probably defined using a Component object. This custom type is used instead of a String to allow for more advanced formatting, including colors, boldness, obfuscation, and click events. They also allow easy access to the translation system, making it simple to translate any UI element into different languages.

If you've worked with datapacks or functions before, you may see parallels with the json text format used for displayNames, books, and signs among other things. As you can probably guess, this is just a json representation of a Component object, and can be converted to and from using Component.Serializer.

When making a mod, it is generally preferred to construct your Component objects directly in code, making use of translations whenever possible.

Literal Text Components

The simplest way to create a Component object is to make a literal. This is just a string that will be displayed as-is, by default without any formatting.

These are created using the Component.nullToEmpty or Component.literal methods, which both act slightly differently. Component.nullToEmpty accepts nulls as input, and will return a Component instance. In contrast, Component.literal should not be given a null input, but returns a MutableComponent, this being a subclass of Component that can be easily styled and concatenated. More about this later.

Text literal = Component.nullToEmpty("Hello, world!");
MutableComponent mutable = Component.literal("Hello, world!");
// Keep in mind that a MutableComponent can be used as a Text, making this valid:
Text mutableAsText = mutable;

Translatable Text Components

When you want to provide multiple translations for the same string of text, you can use the Component.translatable method to reference a translation key in any language file. If the key doesn't exist, the translation key is converted to a literal.

Text translatable = Component.translatable("my_mod.text.hello");

// Similarly to literals, translatable text can be easily made mutable.
MutableComponent mutable = Component.translatable("my_mod.text.bye");

The language file, en_us.json, looks like the following:

{
  "my_mod.text.hello": "Hello!",
  "my_mod.text.bye": "Goodbye :("
}

If you wish to be able to use variables in the translation, similar to how death messages allow you to use the involved players and items in the translation, you may add said variables as parameters. You may add however many parameters you like.

Text translatable = Component.translatable("my_mod.text.hello", player.getDisplayName());

You may reference these variables in the translation like so:

{
  "my_mod.text.hello": "%1$s said hello!"
}

In the game, %1$s will be replaced with the name of the player you referenced in the code. Using player.getDisplayName() will make it so that additional information about the entity will appear in a tooltip when hovering over the name in the chat message as opposed to using player.getName(), which will still get the name; however, it will not show the extra details. Similar can be done with itemStacks, using stack.toHoverableText().

As for what %1$s even means, all you really need to know is that the number corresponds to which variable you are trying to use. Let's say you have three variables that you are using.

Text translatable = Component.translatable("my_mod.text.whack.item", victim.getDisplayName(), attacker.getDisplayName(), itemStack.toHoverableText());

If you want to reference what, in our case, is the attacker, you would use %2$s because it's the second variable that we passed in. Likewise, %3$s refers to the itemStack. A translation with this many additional parameters might look like this:

{
  "my_mod.text.whack.item": "%1$s was whacked by %2$s using %3$s"
}

Serializing Text

As mentioned before, you can serialize text to JSON using the text codec. For more information on codecs, see the Codec page.

Gson gson = new Gson();
MutableComponent mutable = Component.translatable("my_mod.text.bye");
String json = gson.toJson(ComponentSerialization.CODEC.encodeStart(JsonOps.INSTANCE, mutable).getOrThrow());

This produces JSON that can be used datapacks, commands and other places that accept the JSON format of text instead of literal or translatable text.

Deserializing Text

Furthermore, to deserialize a JSON text object into an actual Component class, again, use the codec.

String jsonString = "...";
Component deserialized = ComponentSerialization.CODEC
		.decode(JsonOps.INSTANCE, gson.fromJson(jsonString, JsonElement.class))
		.getOrThrow()
		.getFirst();

Formatting Text

You may be familiar with Minecraft's formatting standards:

You can apply these formatting styles using the ChatFormatting enum on the MutableComponent class:

MutableComponent result = Component.literal("Hello World!")
  .withStyle(ChatFormatting.AQUA, ChatFormatting.BOLD, ChatFormatting.UNDERLINE);

Color	Name	Chat Code	MOTD Code	Hex Code
	Black black	§0	\u00A70	#000000
	Dark Blue dark_blue	§1	\u00A71	#0000AA
	Dark Green dark_green	§2	\u00A72	#00AA00
	Dark Aqua dark_aqua	§3	\u00A73	#00AAAA
	Dark Red dark_red	§4	\u00A74	#AA0000
	Dark Purple dark_purple	§5	\u00A75	#AA00AA
	Gold gold	§6	\u00A76	#FFAA00
	Gray gray	§7	\u00A77	#AAAAAA
	Dark Gray dark_gray	§8	\u00A78	#555555
	Blue blue	§9	\u00A79	#5555FF
	Green green	§a	\u00A7a	#55FF55
	Aqua aqua	§b	\u00A7b	#55FFFF
	Red red	§c	\u00A7c	#FF5555
	Light Purple light_purple	§d	\u00A7d	#FF55FF
	Yellow yellow	§e	\u00A7e	#FFFF55
	White white	§f	\u00A7f	#FFFFFF
	Reset	§r
	Bold	§l
	Strikethrough	§m
	Underline	§n
	Italic	§o
	Obfuscated	§k