Localization Guide

Datapacks are built for multi-language support from day one. JSON data files never contain raw display text — they store translation keys. The actual words live in language files under assets/languages/.

How It Works

Item JSON:
  "displayName": "items.materials.mypack.ores.iron"
                        ↓
Game looks up the key in the active language file:
  en_US.json → "Iron Ore"
  fr_FR.json → "Minerai de Fer"
                        ↓
Player sees text in their selected language

Language File Format

Language files are structured as sections (top-level keys) containing flat key-value maps:

{
  "items": {
    "items.materials.mypack.ores.iron":      "Iron Ore",
    "items.materials.mypack.ores.iron.desc": "A common ore used in basic forging."
  },
  "skills": {
    "skills.category.mypack.crafting.forging":      "Forging",
    "skills.category.mypack.crafting.forging.desc": "The art of smelting raw ore into metal ingots."
  }
}

Minimum Requirement

You must provide at least en_US.json. If a player's language file is missing a key, the game falls back to en_US.json. If the key is also missing there, the raw key string is displayed — a useful debugging signal.

Supported Locale Codes

Code	Language
en_US	English (United States) — default
fr_FR	French
de_DE	German
es_ES	Spanish
pt_BR	Portuguese (Brazil)
uk_UA	Ukrainian
zh_CN	Chinese (Simplified)
ja_JP	Japanese

Adding a Second Language

1. Create assets/languages/fr_FR.json
2. Copy all keys from en_US.json
3. Translate the values — keep all keys identical

Key Harvesting

The Data Helper auto-collects all displayName and description keys from all editors and merges them into the language table. Keys present in the data but missing from a translation file are flagged with a pending badge in the editor UI.

Tips

• Never translate keys — only translate values
• Use section headers to keep language files organized
• Keep descriptions to one or two sentences
• Always test by switching the game language before releasing