How I Designed a 4-Layer i18n Architecture for Minecraft's Standard UI in Spigot

m.b — Tue, 12 May 2026 22:07:21 +0000

Introduction

This article is an implementation note on how I organized the i18n architecture for TreasureRun, a Minecraft Spigot plugin project.

When building multilingual messages in a Spigot plugin, custom plugin messages are relatively straightforward to manage with files such as languages/*.yml or messages.yml.

However, Minecraft's built-in standard UI text and system messages cannot be fully controlled by a Spigot plugin alone.

Examples include:

Standard text resolved by the Minecraft client's language files
Translatable components included in server-to-client packets
Text that can be supplemented through ResourcePack lang JSON files
Client-side language state that may need Fabric runtime sync
Login screens, settings screens, and other areas that the server cannot reach

Instead of trying to handle everything inside Spigot, TreasureRun separates the problem into four responsibilities:

ProtocolLib boundary layer
Server-side ResourcePack
Fabric runtime language sync
Pure Java packet localizer

This article explains how I separated Minecraft-dependent boundaries from pure i18n logic and made the core packet localization logic testable without starting a Minecraft server.

Background: Spigot alone cannot fully control Minecraft standard UI

Localizing custom messages in a Spigot plugin is not difficult by itself.

For example, a plugin can manage its own messages with files such as:

languages/ja.yml
languages/en.yml
languages/de.yml
languages/fr.yml
languages/ojp.yml

For custom game messages, the plugin can simply look up the player's selected language and return the corresponding string.

Minecraft's standard UI is different.

Minecraft has built-in translation keys that are resolved by the client-side language files.

Server-to-client JSON components can also include a translate key, such as:

{
  "translate": "multiplayer.player.left",
  "with": [
    {
      "text": "PlayerName"
    }
  ]
}

This kind of text cannot be handled just by replacing calls to sendMessage() on the Spigot side.

Understanding the problem

Minecraft text belongs to different layers, and the way it can be controlled depends on where it is owned.

Type	Main owner	Can Spigot alone control it?
Custom plugin messages	Spigot plugin	Yes
Some chat, title, and ActionBar packet messages	Server-to-client packet	Partially
Minecraft standard translation keys	Client lang JSON	Difficult with Spigot alone
Lang keys that ResourcePack can override	ResourcePack	Partially
Runtime client language state	Fabric Mod	Requires client-side support
Login screen and settings UI	Minecraft client	Basically no

In other words, Minecraft standard UI i18n is not just a translation file problem.

It is also a boundary design problem: I needed to identify which layer owns each piece of text.

Solution: separating the system into four layers

TreasureRun separates Minecraft standard UI i18n into four layers.

The following diagram shows the overall structure.

flowchart TD
    A["Minecraft Client<br/>Player UI"] --> B["Server-side ResourcePack<br/>Minecraft standard lang JSON"]
    A --> C["Fabric runtime sync<br/>Client-side language state / built-in ResourcePack"]

    D["Spigot Plugin<br/>TreasureRun game logic"] --> E["ProtocolLib Boundary Layer<br/>PacketEvent / Player / WrappedChatComponent"]
    E --> F["Pure Java Packet Localizer<br/>PacketI18nJsonLocalizer"]
    F --> G["Translator Callback<br/>languages/*.yml"]
    G --> F
    F --> E
    E --> A

    H["lang-map.yml<br/>TreasureRun lang code ↔ Minecraft locale code"] --> B
    H --> C
    H --> D

    I["JUnit Tests<br/>Boundary / Delegation / Pure i18n"] --> F
    I --> E

In this design, Minecraft / Bukkit / ProtocolLib dependent code is kept inside the ProtocolLib Boundary Layer.

The JSON component parsing, translation key mapping, placeholder extraction, and translator callback handling are separated into the Pure Java Packet Localizer.

ResourcePack and Fabric runtime sync complement the client-side display and language state. lang-map.yml acts as a single source of truth for mapping TreasureRun language codes to Minecraft locale codes.

This separation allows the core packet i18n logic to be tested with JUnit without starting a Minecraft server.

Layer	Responsibility
ProtocolLib boundary layer	Observes server-to-client packets and writes modified JSON components back
Server-side ResourcePack	Supplements Minecraft standard translation keys with lang JSON files
Fabric runtime sync	Complements client-side language state and built-in ResourcePack behavior
Pure Java packet localizer	Parses packet JSON, maps translation keys, extracts placeholders, and remains testable

The important point is separating Minecraft-dependent boundary code from pure i18n logic.

Layer 1: ProtocolLib boundary layer

The ProtocolLib boundary layer handles packet events, player lookup, packet type checks, and reading/writing WrappedChatComponent.

This layer depends heavily on Bukkit, ProtocolLib, and the Minecraft runtime.

If JSON parsing and translation logic are written directly in this layer, the logic becomes difficult to test without running a Minecraft server.

In TreasureRun, the ProtocolLib listener is treated as a boundary adapter. The actual JSON localization logic is delegated to the pure Java side.

Process	Owned by
Receive `PacketEvent`	ProtocolLib boundary layer
Look up the player's language	ProtocolLib boundary layer
Extract JSON from `WrappedChatComponent`	ProtocolLib boundary layer
Find `translate` keys in JSON	Pure Java localizer
Extract placeholders	Pure Java localizer
Convert the result back into a JSON text component	Pure Java localizer
Write the result back to the packet	ProtocolLib boundary layer

Layer 2: Server-side ResourcePack

The ResourcePack layer supplements Minecraft standard translation keys as lang JSON files.

ResourcePacks can affect standard translation keys that are resolved on the Minecraft client side.

In TreasureRun, I placed language JSON files in the ResourcePack based on Minecraft 1.20.1 standard translation keys.

Example paths:

resourcepacks/treasurerun-i18n-pack/assets/minecraft/lang/ja_jp.json
resourcepacks/treasurerun-i18n-pack/assets/minecraft/lang/en_us.json
resourcepacks/treasurerun-i18n-pack/assets/minecraft/lang/ojp_jp.json

The ResourcePack is sent to the player after joining the server.

However, ResourcePack is not a complete solution.

For example, it cannot fully guarantee control over:

Login UI
Authentication screens
Client settings screens
Fully client-local UI
Text shown before the server sends packets or ResourcePacks

So I do not describe this project as fully controlling the entire Minecraft UI.

More accurately, it is a practical layered design for localizing the parts that can realistically be reached after a player joins the server.

Layer 3: Fabric runtime language sync

ResourcePack alone cannot always handle runtime client language state.

For this reason, the Fabric Mod side handles runtime language sync.

In TreasureRun, the Fabric side is responsible for:

Registering built-in ResourcePack support
Reading lang-map.yml
Receiving the selected language code from the server
Mapping TreasureRun language codes to Minecraft locale codes
Complementing the client-side language state

A key point is that the server does not send huge translation JSON files for all languages every time.

Instead, the server basically sends the selected language code.

The translation resources themselves live on the ResourcePack / Fabric Mod side.

This keeps the communication payload small and makes lang-map.yml the single source of truth for language mapping.

Layer 4: Pure Java packet localizer

The most important part of this design is the pure Java packet localizer.

TreasureRun separates packet JSON localization into a class named PacketI18nJsonLocalizer.

This class does not depend on Bukkit, ProtocolLib, Fabric, or Minecraft runtime APIs.

It only knows:

Raw JSON string
Selected language code
Translator callback

Conceptually, its responsibility looks like this:

PacketI18nJsonLocalizer.localizeJson(
    rawJson,
    lang,
    translator
);

The pure Java localizer finds translate keys inside JSON components and maps Minecraft standard translation keys to TreasureRun i18n keys.

For example:

multiplayer.player.left

can be handled as:

minecraft.packet.multiplayer.player.left

Then it extracts placeholders and passes them to the translator callback.

Because this class is independent from the Minecraft runtime, it can be tested with JUnit.

Boundary tests

This design is not just separated in theory. It is also protected by tests.

Two representative tests are:

1. Pure i18n package boundary test

This test verifies that plugin.i18n does not import Bukkit, ProtocolLib, Fabric, or Minecraft runtime APIs.

In other words, it checks that the pure i18n package is not contaminated by platform dependencies.

This works as an architectural fitness function.

2. ProtocolLib listener delegation test

This test verifies that the ProtocolLib listener delegates JSON parsing to PacketI18nJsonLocalizer instead of directly owning the parsing logic.

This helps keep the packet boundary layer separate from the testable pure Java logic.

`lang-map.yml` as the single source of truth

TreasureRun centralizes the mapping between TreasureRun language codes and Minecraft locale codes in lang-map.yml.

Example:

mappings:
  ja:        ja_jp
  en:        en_us
  de:        de_de
  fr:        fr_fr
  es:        es_es
  ojp:       ojp_jp
  asl_gloss: asl_us

With this design, adding a new language does not require adding another Java switch statement.

The intended flow for adding a new language is:

Add one line to lang-map.yml
Add languages/<lang>.yml
Add <minecraft_locale>.json to the ResourcePack
Add <minecraft_locale>.json to the Fabric side
Let CI verify the consistency

This keeps language expansion configuration-driven instead of hard-coding every language in Java.

CI checks

As the number of i18n files grows, localization systems become easier to break.

TreasureRun uses GitHub Actions to run checks such as:

Java compile
YAML syntax check
Required key check
Referenced key check
Duplicate key check
Suspect key check
ResourcePack SHA1 check
i18n expansion check

These checks are run with a combination of Gradle tests and custom verification scripts.

For example, the checks verify whether referenced translation keys are actually defined, whether duplicate or suspicious keys remain, and whether the ResourcePack SHA1 matches the generated artifact.

For multilingual systems, adding translations is only one part of the problem.

It is just as important to detect broken states early.

Runtime verification

At runtime, I checked the system through logs such as:

ResourcePack sent
ResourcePack accepted
ResourcePack loaded
PacketI18n translate audit, monitored through PacketI18nJsonLocalizer
PacketI18n replace, handled through PacketI18nJsonLocalizer
Translation missing: 0
I18n Missing key warning: 0

The important point is that I did not just check whether it “seemed to work.”

I wanted to see which layer worked and how far the system actually reached.

What this design can do

This design makes it possible to:

Manage custom plugin messages with languages/*.yml
Supplement Minecraft standard translation keys through ResourcePack lang JSON
Observe translatable components in server-to-client packets
Replace some packet JSON based on the player's selected language
Complement runtime language sync on the Fabric side
Test the pure Java localizer without starting a Minecraft server
Detect broken i18n configuration through CI

What this design cannot do

There are still things this design cannot fully control.

A Spigot plugin alone cannot guarantee control over:

Login UI
Authentication screens
Client settings screens
Fully client-local UI
Text displayed before packets or ResourcePacks are sent
Text fully owned by the Minecraft client internally

So the scope of this project is:

This is not a system that fully translates the entire Minecraft UI. It is a layered design that separates Spigot-limited Minecraft standard UI boundaries into ProtocolLib, ResourcePack, Fabric, and a pure Java localizer, focusing on the parts that can realistically be reached after joining the server.

What I learned

The biggest lesson from this implementation was that i18n is not only translation work.

In a platform like Minecraft, I had to ask questions such as:

Is this text owned by the server?
Is it owned by the client?
Can it be observed in packets?
Can it be supplemented with a ResourcePack?
Does it need help from a Fabric Mod?
Is it effectively outside the server side's control?

In that sense, i18n was also a boundary design problem.

In TreasureRun, I separated Minecraft-dependent boundaries from pure logic so that the core i18n behavior could be tested as a normal Java component.

Conclusion

Spigot alone cannot fully control Minecraft standard UI text.

TreasureRun separates the problem into four layers:

ProtocolLib boundary layer
Server-side ResourcePack
Fabric runtime language sync
Pure Java packet localizer

With this separation, Minecraft-dependent boundary code stays inside adapter-like layers, while pure packet JSON localization logic can be tested with JUnit.

This design is based on the constraints of Minecraft as a platform.

The key was deciding which parts should be handled on the server side, which parts should be handled by ResourcePack or Fabric, and which parts are simply outside the practical reach of a Spigot plugin.

i18n was not just about adding more translation files.

It was about identifying which layer owns each piece of text and designing around the boundaries that can actually be controlled.

Forem: m.b