Text and Translations

Whenever Minecraft displays text in-game, it's probably defined using a Text 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 Text object, and can be converted to and from using Text.Serializer.

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

Text Literals

The simplest way to create a Text 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 Text.of or Text.literal methods, which both act slightly differently. Text.of accepts nulls as input, and will return a Text instance. In contrast, Text.literal should not be given a null input, but returns a MutableText, this being a subclass of Text that can be easily styled and concatenated. More about this later.

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

Translatable Text

When you want to provide multiple translations for the same string of text, you can use the Text.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 = Text.translatable("my_mod.text.hello");

// Similarly to literals, translatable text can be easily made mutable.
MutableText mutable = Text.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 text codec. For more information on codecs, see the Codec page.

Gson gson = new Gson();
MutableText mutable = Text.translatable("my_mod.text.bye");
String json = gson.toJson(TextCodecs.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 Text class, again, use the codec.

String jsonString = "...";
Text deserialized = TextCodecs.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 formattings using the Formatting enum on the MutableText class:

MutableText result = Text.literal("Hello World!")
  .formatted(Formatting.AQUA, Formatting.BOLD, Formatting.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