Handling Translations

Normally, plugin developers must handle message formatting themselves. While ByteLib automatically loads language files, formatting messages typically requires additional work.

As well, the underlying BoostedYAML library only returns primitives, and many Paper methods that previously accepted these are now deprecated (for example, Player#sendMessage(String message)).

ByteLib provides a MiniMessage-based Translator utility to simplify working with translations and formatted text. This utility automatically handles pulling text from your language file and running it through a MiniMessage deserializer.

Getting started

Inject Translator into any class that needs to send translated or formatted messages.

public class SomeClass {
    private final Translator translator;

    @Inject
    public SomeClass(Translator translator) {
        this.translator = translator;
    }
}
        

The Translator utility contains two primary methods: tr() and title().

`tr()`

public Component tr(String key, TagResolver... resolvers);

The tr() method retrieves a translation from the active language file and automatically processes MiniMessage formatting tags.

The first parameter is the translation key from the language file. Optional TagResolver parameters can be supplied to dynamically replace MiniMessage tags.

TagResolver is part of the Adventure API. Refer to the Adventure documentation for details about creating and using resolvers.

The returned value is a fully formatted Adventure Component.

`title()`

public Title title(String keyBase, Title.Times times, TagResolver... resolvers);
        

The title() method is a convenience utility that constructs Adventure Title objects using values from the language file. This removes a small amount of boilerplate when creating titles in your plugin.

Title entries must follow the following structure in your language file:

# lang/[langFile].yml
titleKey:
    title: Title value
    subtitle: Subtitle value
        

In the example above, titleKey would be passed as the keyBase parameter.

The Title.Times parameter controls the fade-in, stay, and fade-out durations when displaying the title.

Like tr(), this method also supports optional TagResolver parameters.

Special Translation Keys

Many plugins include a message prefix to identify messages from the plugin and provide a consistent in-game style.

ByteLib includes a built-in MiniMessage TagResolver that replaces <prefix> tags with the value of the prefix entry from the language file.

If the prefix key does not exist, the tag will resolve to an empty string.

language-version: 1 prefix: <blue>[My Prefix]</blue> some-message: <prefix> This is a message! some-other-message: <prefix> This will be prefixed, too!

11 March 2026