Translations — Code Structure

File location

All translation files are located in core/src/main/resources/lang/ and organized by domain:

lang/
├── errors.{lang}.json              # Error messages
├── global.{lang}.json              # Global prefixes (info, warning, error, debug)
├── messages.{lang}.json            # General gameplay messages
├── area/
│   └── messages.{lang}.json        # Area CRUD messages
├── commands/
│   ├── area.{lang}.json            # /le area command descriptions
│   ├── clipboard.{lang}.json       # /le clipboard command descriptions
│   ├── component.{lang}.json       # /le component command descriptions
│   ├── componentinfo.{lang}.json   # /le info command & component inspector texts
│   ├── editor.{lang}.json          # /le editor command description
│   ├── help.{lang}.json            # /le help command description
│   ├── lang.{lang}.json            # /le lang command descriptions
│   ├── schematics.{lang}.json      # /le schematic command descriptions
│   └── stats.{lang}.json           # /le stats command descriptions
├── race/                          # Race builder
├── shortcutbar/                    # Editor hotbar & GUI menu translations
│   ├── shortcutbar.{lang}.json
│   ├── elevator.{lang}.json
│   ├── lock-key_chest.{lang}.json
│   ├── music_block.{lang}.json
│   ├── range.{lang}.json
│   ├── rotation.{lang}.json
│   ├── area_configuration/
│   ├── color_selection/
│   ├── component_configuration/
│   ├── delete_area/
│   ├── place_component/
│   ├── sync/
│   └── victory_area/
└── stats/
    ├── gui.{lang}.json             # Statistics GUI menu
    └── messages.{lang}.json        # Statistics chat messages

Naming convention

Each file follows the pattern <domain>.<languageCode>.json (e.g., errors.en.json, errors.fr.json).

Translation codes inside a file follow a hierarchical snake_case pattern:

errors.<domain>.<what> — e.g. errors.area.too_small_exception
messages.<action> — e.g. messages.create_area_success
<feature>.command.<verb>.<part> — e.g. component.command.look.area_id
items.<name>.{name,description} — e.g. items.portal_surface.description

Place new entries next to thematically related codes, not at the bottom of the file.

Supported languages (25)

ar (Arabic), bn (Bengali), cs (Czech), da (Danish), de (German), el (Greek), en (English, default), es (Spanish), fi (Finnish), fr (French), hi (Hindi), hu (Hungarian), it (Italian), ja (Japanese), ko (Korean), nl (Dutch), no (Norwegian), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese).

Translation completeness — required everywhere

Every translation code MUST exist in every <domain>.<languageCode>.json file of its domain. The plugin emits a "Translations are missing" warning at startup for any code missing from a language file. The same warning fires for the opposite case: a key still present in non-en files but removed from en.json. When you remove a key, remove it from every language file too.

Translate for real in each language. Never leave the English string as a placeholder in non-English files. en.json is itself a real translation that ships to English players. If you're unsure about a language, translate as best you can and flag those languages so a reviewer can spot-check.

Modifying a published translation value — `forceUpdatePluginVersion`

When you change the value of a translation code that already shipped in a prior release, you must add forceUpdatePluginVersion to that entry — otherwise admins who already installed the plugin keep their previously-loaded value and your edit has no effect on live servers.

TranslationLib writes its JSON into plugins/<plugin>/lang/ on first load and then treats the admin's stored copy as authoritative. forceUpdatePluginVersion tells the library: for any server upgrading from a plugin version strictly lower than X, overwrite the admin's stored value.

{
  "code": "area.command.victory",
  "translation": "§a§lVictory!",
  "forceUpdatePluginVersion": "8.26.1"
}

Rules:

Value to write: current gradle.properties with -SNAPSHOT stripped (e.g. 8.26.1-SNAPSHOT → "8.26.1"). Never include -SNAPSHOT — the release tooling strips it, and the value must match the final published version.
Apply in every language file you edit (en + all non-en).
Bundle the value change and forceUpdatePluginVersion in the same Edit so you cannot ship one without the other.
Not needed for brand-new codes — those are written on first load.
If the entry already has a forceUpdatePluginVersion, overwrite it with the current version. If the existing one is higher than the current version, stop and ask — someone else is mid-flight on the same key.

`defaultForceUpdatePluginVersion`

Files often start with a defaultForceUpdatePluginVersion at the top. Do not bump that — it force-overwrites every unmarked key, trampling unrelated admin customisations. Always mark the single entry you changed via the per-entry forceUpdatePluginVersion.

Mid-feature staging workflow

When introducing or modifying translations as part of a larger feature/fix, do not edit the 25 language files inline. Instead:

Buffer each entry into .translation-staging.json at the project root (gitignored).
At end-of-task — after the Java implementation is stable, before build/commit — write all staged entries to the language files in one batched pass (one Edit per file containing every staged entry).

Staging entry shape:

[
  {
    "operation": "add",
    "domain": "area/messages",
    "code": "messages.area_resize_success",
    "en": "§7Area §6{0}§7 resized to §6{1}x{2}x{3}§7.",
    "context": "Sent once after a successful resize via the area edit menu. {0}=area name (admin string, may contain spaces); {1}/{2}/{3}=new X/Y/Z dimensions in blocks. Not sent on cancel or invalid resize."
  }
]

The context field is mandatory — it tells translators when the code fires, what each {N} semantically represents and what tone to use, so non-English translations don't drift into wrong literals. The plugin will warn "Translations are missing" between staging and flush; that is expected and disappears once the flush runs.

⚠️ Orphan check: if .translation-staging.json exists at the start of a session, stop and decide whether to flush it (write staged entries to language files) or discard it (git clean the file). A stale staging file from a previous session must never be silently merged with new work.

⚠️ Never commit the staging file — it must be flushed first.

For one-off ad-hoc changes (1–2 codes, no other translation work in flight), it's still fine to edit the language files directly without staging.

Style conventions (Minecraft formatting codes)

Use the role-based prefix for every new code; reset with §r whenever a style shouldn't bleed into the next text chunk.

Role	Style	Example
Error	`§c` prefix	`"§cThe area is too small."`
Warning	`§6` prefix	`"§6Warning: …"`
Debug	`§e` prefix	`"§eDebug: …"`
Item name	`§f` (often `§l` bold)	`"§fPlace cube creation button"`
Item description	`§7`, `\n§7` per line	`"§7Creates a button.\n§7Right-click to use."`
Interpolated param	`§6{N}`	`"§7Area ID: §6{0}"`
Label : value	`§l§f<label>§r§8: §6<value>`	`"§8 - §l§fArea ID§r§8: §6{0}"`

These conventions apply to new codes. Older entries that are uncolored or inconsistent don't need to be retrofitted, but don't follow them as a model either — converge on the table above.

MessageFormat placeholders and escaping

The plugin uses Java's MessageFormat for parameter substitution:

{0}, {1}, … are positional placeholders. The Java caller passes parameters in order: TranslationUtils.sendTranslatedMessage(player, "code", arg0, arg1).
Every language file must keep the same indices in the same semantic roles. Word order may differ (e.g. Japanese), but every {N} must be present in every translation. Same count, same meaning.
'{0}' renders as the literal {0} (single quotes escape the placeholder).
A single quote is written '' — e.g. French apostrophes are doubled: l''aire. Un-doubling them breaks the format string at runtime.

Editing safety — Edit tool only

Never edit translation files with Write, sed, -replace, or any full rewrite. The 25 files mix CRLF/LF line endings and with/without UTF-8 BOM. Full rewrites silently corrupt Arabic / Bengali / Greek / Hindi / Japanese / Korean / Russian / Ukrainian / Chinese glyphs into mojibake that still parses as JSON but renders as ??? in-game.

Use Edit only, one file at a time (or batched per file when staging-flushing multiple entries).

Adding a new language

To add a built-in language:

Create a *.<lang>.json counterpart for each existing *.en.json file (currently ~30 files).
Set the language block with the correct languageCode, language name, and "isDefault": false.
Update ConfigData.CONFIG_HEADER to list the new language.
Update the wiki pages: Installation/Config.md and Installation/Translations.md.

Translation library

The plugin uses TranslationLib (fr.skytale.translationlib) which auto-discovers translation files from the lang/ resource directory. No manual registration is needed when adding new files.

AI assistant skills

Four Claude Code skills under .claude/skills/ automate the most repetitive translation operations and enforce the rules above:

Skill	Purpose
`stage-translation`	Buffer a new or modified code into `.translation-staging.json` mid-feature (preferred path for ≥ 3 codes per task)
`flush-translation-staging`	At end-of-task, write all staged entries to every language file in one batched pass; auto-applies `forceUpdatePluginVersion` for `modify` entries
`add-translation-code`	Add a single brand-new code directly into all 25 language files (ad-hoc, 1–2 codes)
`modify-translation-value`	Change a published code value directly with `forceUpdatePluginVersion` (ad-hoc, 1–2 codes)

See AI Prompts and Skills for the full list.

File location​

Naming convention​

Supported languages (25)​

Translation completeness — required everywhere​

Modifying a published translation value — forceUpdatePluginVersion​

defaultForceUpdatePluginVersion​

Mid-feature staging workflow​

Style conventions (Minecraft formatting codes)​

MessageFormat placeholders and escaping​

Editing safety — Edit tool only​

Adding a new language​

Translation library​

AI assistant skills​