Minecraft Custom Translations Resource Pack Guide

Written for Minecraft 26.3.

A minecraft custom translations resource pack stores text in language files, so your item names and messages can change per player language. You write a key and a string in assets/<namespace>/lang/en_us.json, then refer to the key from a translatable text component.

Before you start

• A resource pack. See Pack basics.

• A namespace, for example mypack, and a plan for your key names such as item.mypack.wand.

Add a language file

1. Create assets/mypack/lang/en_us.json.

2. Fill it with keys and strings, as below.

3. Add more files for other languages if you need them.

{
  "item.mypack.wand": "Spark Wand",
  "mypack.welcome": "Welcome, %s!",
  "subtitles.mypack.chime": "Chime rings"
}

The file is one flat JSON object. Keys are the identifiers you choose and values are the text. Locale codes are lowercase with an underscore: en_us, de_de, pt_br.

Use a key in game

A translatable component has a translate key. Use with to fill slots: %s takes the next argument, and %2$s takes the second.

/tellraw @a {"translate":"mypack.welcome","with":["Alex"]}

For a custom item name, give the item a translatable item_name. See custom items for the full command.

/give @p stick[item_name={translate:"item.mypack.wand"}]

Fallbacks

Each player sees text in their own selected language. If the key is missing in a language, the game falls back to the component's fallback text when you set one. If there is none, it shows the raw key.

{"translate":"mypack.welcome","fallback":"Welcome!"}

That makes fallback useful for players who decline your pack. They see the fallback text rather than mypack.welcome.

Check it worked

1. Reload with F3 + T.

2. Run the /tellraw command. You should see the English text.

3. Switch the game language in Options. A language without your file should still show text if you set fallback.

Common problems

The raw key appears in chat

The file is missing, the key is misspelled, or the pack is not loaded for that player.

The whole file is ignored

A trailing comma or a missing quote breaks the JSON. Validate it before uploading.

A non-English player sees the key

Add their locale file, or set a fallback on the component. We have not verified whether the game uses en_us for custom keys, so do not rely on it.

The key clashes with vanilla

Start your own keys with your namespace so they never match a vanilla key.

Use translatable text only for text the pack controls. Players without the pack see the key or the fallback, never your lang file.

Subtitles for custom sounds use the same files: see sounds.