Localization - Refinery WIKI

xyz.refineryteam.refinerycore.api.i18n.Messages is a per-player-locale message registry backed by YAML files in <datafolder>/lang/<locale>.yml. Each player sees messages in their client language automatically, falling back to a default locale and then to the raw key — so a missing translation degrades gracefully instead of crashing.

Message files

Ship one YAML file per locale inside your plugin jar and save it to the data folder before loading:

lang/en_us.yml

prefix: "<gradient:#A78BFA:#7F77DD>MyPlugin</gradient> <dark_gray>»</dark_gray> "
errors:
  no-permission: "<red>You can't do that."
  not-found: "<red>Player <white>%target%</white> wasn't found."

Keys are dotted config paths (errors.no-permission), values are MiniMessage strings, and an optional top-level prefix entry is prepended by the prefixed send helpers.

Setup

MyPlugin.java

public final class MyPlugin extends JavaPlugin implements RefineryPluginImplementation {

    private Messages messages;

    @Override
    public void onEnable() {
        saveResource("lang/en_us.yml", false);
        saveResource("lang/de_de.yml", false);

        messages = Messages.of(this);
        messages.load();
        messages.setDefaultLocale(Locale.US);
    }
}

load() reads every .yml in the lang folder and can be called again later to pick up edits (e.g. from a reload command). Missing files are left alone — you ship defaults via saveResource(...) yourself.

Sending messages

MyCommand.java

// Prefixed with the bundle's "prefix" entry:
messages.sendPrefixed(player, "errors.not-found",
    Placeholder.unparsed("target", name));

// Unprefixed:
messages.send(player, "errors.no-permission");

// Resolve without sending (e.g. for lore or broadcast building):
Component text = messages.component(player, "errors.not-found",
    Placeholder.unparsed("target", name));

Method	Description
`of(plugin)` / `of(plugin, folder)`	Creates a registry reading from `lang/` (or a custom sub-folder) inside the data folder
`load()`	Loads/reloads every `.yml` in the lang folder
`setDefaultLocale(Locale)`	Fallback locale used when a player’s locale has no bundle
`setLocale(UUID, Locale)` / `clearLocale(UUID)`	Per-player override (e.g. from a `/language` command)
`localeFor(Player)`	The effective locale: explicit override → client-reported locale → default
`component(Player, key, resolvers...)`	Resolves and formats a message as MiniMessage
`send(Audience, key, resolvers...)`	Sends a message; console audiences get the default locale
`sendPrefixed(Audience, key, resolvers...)`	Same, prepending the bundle’s `prefix` entry if present
`raw(Player, key)`	Resolves without MiniMessage parsing — for plain-text destinations like scoreboard lines or Discord
`exists(key)`	Whether the key exists in any loaded bundle
`availableLocales()`	All loaded locale codes (e.g. `["en_us", "de_de"]`)

Locale resolution

For each player, Messages checks (in order): an explicit per-player override, then the client-reported locale trying a full match (en_us) before a language-only match (en), then the default locale. Resolution of a key follows the same graceful chain: the player’s bundle → the default bundle → the raw key itself.

Pair Messages with Placeholders if you want %target%-style tokens resolved globally across plugins — the example above uses inline MiniMessage TagResolvers, which need no registration.

​Message files

​Setup

​Sending messages

​Locale resolution

Message files

Setup

Sending messages

Locale resolution