Testo e Traduzioni 1.21.8

Documentazione esaustiva riguardo alla gestione di testo e traduzioni formattate in Minecraft.

WARNING

Questa pagina si applica alla versione 1.21.8. La documentazione delle versioni meno recenti potrebbe essere incompleta.

Ogni volta che Minecraft mostra testo nel gioco, è con tutta probabilità definito da un oggetto Component. Questo tipo personalizzato è preferito ad una String per permettere formattazione più avanzata, che comprende colori, grassetto, offuscamento, ed eventi ai clic. Permettono inoltre accesso più semplice al sistema di traduzione, rendendo semplice la traduzione di qualsiasi elemento dell'interfaccia.

Se hai mai lavorato con datapack o con funzioni prima d'ora, potresti notare similarità con il formato testo json usato per i displayName, i libri, e i cartelli tra le altre cose. Come probabilmente riuscirai ad indovinare, quella è solo una rappresentazione json di un oggetto Component, e può essere convertita tramite Component.Serializer.

Quando si crea una mod, si preferisce generalmente costruire i tuoi oggetti Component direttamente nel codice, sfruttando ove possibile le traduzioni.

Testo Letterale

Il modo più semplice di creare un oggetto Component è creare un testo letterale. Questa è proprio solo una stringa che verrà visualizzata com'è, senza alcuna formattazione predefinita.

Questi sono creati tramite i metodi Component.nullToEmpty o Component.literal, che agiscono in modi un po' diversi. Component.nullToEmpty accetta null come input, e restituirà un'istanza di Component. Viceversa, Component.literal deve non ricevere come input null, ma restituisce un MutableComponent, che è una sotto-classe di Component facilmente stilizzata e concatenata. Ne parleremo di più dopo.

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;

Testo Traducibile

Se volessi fornire traduzioni multiple della stessa stringa di testo, puoi usare il metodo Component.translatable per fare riferimento ad una chiave di traduzione in qualsiasi file lingua. Se la chiave di traduzione non esistesse, verrebbe convertita in testo letterale.

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");

Il file di lingua, en_us.json, ha il seguente aspetto:

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

Se volessi usare variabili nella traduzione, in maniera simile a come i messaggi di morte ti permettodo di usare i giocatori e gli oggetti coinvolti nella traduzione, puoi aggiungere queste variabili come parametri. Puoi aggiungerne quanti ne vuoi.

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

Puoi fare riferimento a queste variabili nella traduzione così:

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

Nel gioco, %1$s sarà sostituito dal nome del giocatore a cui hai fatto riferimento nel codice. Usare player.getDisplayName() farà in modo che certe informazioni aggiuntive sull'entità appaiano in un tooltip mentre si passa il mouse sopra al nome nel messaggio in chat, e ciò in contrasto con player.getName(), che mostrerà comunque il nome, ma non i dettagli aggiuntivi. Qualcosa di simile si può fare con gli itemStack, usando stack.toHoverableText().

Per quanto riguarda il significato di %1$s, ti basti sapere che il numero corrisponde a quale variabile provi ad usare. Immagina di usare tre variabili.

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

Se vuoi fare riferimento a ciò che, nel nostro caso, è l'attaccante, useresti %2$s perché è la seconda variabile che abbiamo passato. Allo stesso modo, %3$s fa riferimento all'itemStack. Una traduzione con questo numero di parametri aggiuntivi potrebbe avere questo aspetto:

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

Serializzare Testo

Come già accennato prima, puoi serializzare testo a JSON con il codec di testo. Per maggiori informazioni, vedi la pagina sui Codec.

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

Questo produce JSON che può essere usato in datapack, comandi e altri posti che accettano il formato JSON di testo invece che il formato letterale o traducibile.

Deserializzare Testo

Inoltre, per deserializzare un oggetto testo da JSON a un oggetto della classe Component, di nuovo, usa il codec.

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

Formattare Testo

Forse sei familiare con gli standard di formattazione di Minecraft:

Puoi applicare questi stili di formattazione usando l'enum ChatFormatting sulla classe MutableComponent:

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

Colore	Nome	Codice in Chat	Codice MOTD	Codice Hex
	Nero black	§0	\u00A70	#000000
	Blu Scuro dark_blue	§1	\u00A71	#0000AA
	Verde Scuro dark_green	§2	\u00A72	#00AA00
	Ciano Scuro dark_aqua	§3	\u00A73	#00AAAA
	Rosso Scuro dark_red	§4	\u00A74	#AA0000
	Viola Scuro dark_purple	§5	\u00A75	#AA00AA
	Oro gold	§6	\u00A76	#FFAA00
	Grigio gray	§7	\u00A77	#AAAAAA
	Grigio Scuro dark_gray	§8	\u00A78	#555555
	Blu blue	§9	\u00A79	#5555FF
	Verde green	§a	\u00A7a	#55FF55
	Ciano aqua	§b	\u00A7b	#55FFFF
	Rosso red	§c	\u00A7c	#FF5555
	Viola Chiaro light_purple	§d	\u00A7d	#FF55FF
	Giallo yellow	§e	\u00A7e	#FFFF55
	Bianco white	§f	\u00A7f	#FFFFFF
	Resetta	§r
	Grassetto	§l
	Barrato	§m
	Sottolineato	§n
	Corsivo	§o
	Offuscato	§k