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:

1. ProtocolLib boundary layer
2. Server-side ResourcePack
3. Fabric runtime language sync
4. 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.

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.

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.

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:

1. Add one line to lang-map.yml
2. Add languages/<lang>.yml
3. Add <minecraft_locale>.json to the ResourcePack
4. Add <minecraft_locale>.json to the Fabric side
5. 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:

1. ProtocolLib boundary layer
2. Server-side ResourcePack
3. Fabric runtime language sync
4. 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.