Skip to content

Localization

JonataOliveiraa edited this page Nov 14, 2026 · 1 revision
Basics

Every name and text your mod shows can be translated. As in tModLoader, the texts live in .hjson files in your mod's Localization/ folder, one file per language, and the game shows the player the one that matches their language.

Translations follow tModLoader: hjson files with keys like Mods.MyMod.Items.ShinyRock.DisplayName.

The files

Any .hjson file of the mod with a culture in its name counts (bin/ and obj/ aside). The part after the culture is a prefix put in front of every key in the file:

File Keys inside start at
Localization/en-US_Mods.MyMod.hjson Mods.MyMod.
Localization/pt-BR_Mods.MyMod.hjson Mods.MyMod.
Localization/en-US.hjson the root: write Mods: { MyMod: { ... } }
Localization/en-US/Mods.MyMod.Items.hjson Mods.MyMod.Items.

What hjson allows, and Bunny Loader reads: braces around the whole file are optional; no quotes around names or around a value that takes the rest of its line; #, // and /* */ comments; commas optional; "..." and '...' with \n, \t, \" escapes; multiline text between ''' lines, with the indentation of the opening ''' removed:

# Localization/en-US_Mods.MyMod.hjson
Greeting: Hello, {0}!
Items: {
	ShinyRock: {
		DisplayName: Shiny Rock
		Tooltip:
			'''
			It glows a little
			Right click to polish
			'''
	}
}

A value that takes the rest of its line ends only at the line's end: write { Name: "x" } with quotes when an object fits in one line.

The game's culture picks the text: the exact culture (pt-BR), then the same language, then en-US, then any. Changing the language in the game updates every text of the mods.

{$Key} inside a text is replaced by another text when the mod loads, as in tModLoader: a key of the mod ({$Mods.MyMod.NPCs.Slime.DisplayName}, or just {$NPCs.Slime.DisplayName} from inside Mods.MyMod), of a mod loaded before, or of the game ({$CommonItemTooltip.Whips}). {$Key@1} adds 1 to the {0}-style arguments of the text it brings in. A game text comes in the language the game had when the mod loaded. The phone lacks CommonItemTooltip.SummonTagDamage, which Bunny Loader adds.

In code

Call Gives
Language.GetTextValue("Mods.MyMod.Greeting", "Bunny") "Hello, Bunny!" (the arguments fill {0}, {1}...)
Language.GetText(key) the game's LocalizedText for the key
Language.GetOrRegister(key, () => "default") the LocalizedText; with the default when no file has it
Mod.GetLocalization("Greeting") Mods.MyMod.Greeting
this.GetLocalization("Glow") in a ModItem Mods.MyMod.Items.ShinyRock.Glow
this.GetLocalizedValue("Glow") its text
text.Value, text.Format(args) the text, and the text with {0}... filled

using Terraria.Localization; brings Language and LocalizedText, which are the game's own.

A ModBuff's DisplayName and Description can be overridden with another text, even another content's (ExampleMinecartBuff takes the item's name): they are read after every mod has loaded, not when the buff registers.

A ModItem's DisplayName and Tooltip are its GetLocalization("DisplayName") and GetLocalization("Tooltip"). Without a translation, the name is the class name split in words (ShinyRock → Shiny Rock) and the tooltip is empty. To use a text of the game instead, override them:

public override LocalizedText DisplayName => Language.GetText("ItemName.IronPickaxe");

When the texts work: GetLocalization(...).Value works from Load on. Language.GetTextValue looks the key up in the game's own table, and the mods' keys only enter it on the game thread: from SetStaticDefaults on.

The old format, Localization/<culture>.json with ItemName and ItemTooltip sections, is still read (a key of a .hjson wins).


← Sounds  ·  Global classes →

Clone this wiki locally