Text and Translations

Whenever Minecraft displays text ingame, 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 interface elements 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 :("
}

Serializing Text

As mentioned before, you can serialize text to JSON using the following serializer class:

MutableComponent mutable = Component.translatable("my_mod.text.bye");
String json = Component.Serializer.toJson(mutable);

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, you can use the fromJson method:

String jsonString = Component.Serializer.toJson(mutable);
MutableComponent deserialized = Component.Serializer.fromJson(jsonString);

Formatting Text

You may be familiar with Minecraft's formatting standards:

You can apply these formattings 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