Localization

Localization

Tagvyn uses Minecraft language JSON files for player-facing UI, messages, and title-item text.

Bundled languages

The repository currently bundles translations for:

• English (en_us)
• Korean (ko_kr)
• Japanese (ja_jp)
• Simplified Chinese (zh_cn)
• Traditional Chinese (zh_tw)
• Spanish (es_es)
• French (fr_fr)
• German (de_de)
• Brazilian Portuguese (pt_br)

The client language setting selects the visible translation. Translatable Components sent by the server are intentionally resolved on the client where appropriate so each player can see their own language.

Source of truth

Treat en_us.json as the key-set reference. CI validates that every bundled language has the same translation keys and matching %s placeholder counts.

When adding a new key:

1. add it to en_us.json;
2. add the same key to every bundled language file;
3. preserve placeholder count/order semantics;
4. run the normal build/CI validation.

Use translatable Components

Prefer:

Component.translatable("tagvyn.message.example", value)

over building a user-facing English string in Java.

For GUI labels:

Component.translatable("tagvyn.gui.example.label")

For user-facing item names/lore, continue using translatable Components so the same server-issued item can be displayed according to each client's language resources.

Do not translate stable identifiers

Never localize values that act as identifiers or protocol/storage keys, such as:

• title IDs (founder, vip, etc.);
• action IDs sent in internal packets;
• NBT/data-component marker keys;
• API method names;
• config keys;
• resource locations.

Translate only user-facing text.

GUI design and translation length

Do not assume English or Korean button text is representative of every language. German/French/Spanish labels can be substantially longer.

Tagvyn's current admin screens use scrolling and width-aware clipping to avoid forcing every translated control into a single viewport. New screens should follow the same rule:

• prefer a scrollable management panel for long forms;
• keep essential navigation such as Back fixed where practical;
• avoid overly narrow side-by-side buttons for long actions;
• clip non-critical preview/list text with ellipsis rather than drawing outside a panel;
• test with multiple GUI scales and at least one language with longer strings.

Placeholder safety

If English contains:

"tagvyn.message.example": "Updated %s for %s"

other languages must preserve the two substitution placeholders expected by code.

Do not delete a placeholder because a literal translation sounds natural without it. Either rewrite the sentence to use all required values or update code and all translations together as one API/UI change.

Adding a new language

Create the appropriate Minecraft locale file under:

src/main/resources/assets/tagvyn/lang/<locale>.json

Copy the full current key set from en_us and translate every player-facing value. Then ensure the CI validation script includes/discovers the new locale as intended.

First-join prompt

The first-join nickname prompt is a translatable Component. Keep it translatable rather than selecting a language server-side; the server normally does not know or need to enforce the client's UI language for this message.