Developer Hub Help

Working with translations

Learn how to support multiple languages in your plugin with MiniMessage definitions. This extends Paper's internationalization guide. For more detailed information, refer to the documentation.

Common Misusage

  • When switching from strings to translatable components, be aware of this important difference:

  • Component.translatable("key","argument 0"); // "argument 0" will be the fallback translation
    Component.translatable("key",Component.text("argument 0"));

Provide Translations 🌍

Learn how to provide translations for your plugin. This improves your development experience by eliminating inline formatting in your code.

plugin.feature.key=text with argument <arg:0> essentials.teleport.to-player=<prefix>Du wurdest zu <arg:0> teleportiert. essentials.teleport.to-location=<prefix>Du bist nun auf <arg:0>

To define messages as shown above, follow this guide:

Create a Resource Bundle 📖

  1. Select src/main/resources, press Alt+Insert, select Directory and name it lang

  2. In src/main/resources/lang, create a new file named messages_de_DE.properties and (optionally) messages_en_US.properties

    resource_bundle.png

  3. Open Settings by pressing Strg+Alt+S or by clicking File | Settings

  4. Navigate to Editor | File Encodings

  5. Select UTF-8 in Default encoding for properties files

    file_encodings.png

Set up a custom MiniMessage instance

  1. Create a new MiniMessage instance that supports the prefix, hl, ex, and ss tags.

  2. Since PREFIX is a constant not set by any configuration, define a MiniMessage constant:

  3. public static final Component PREFIX = MiniMessage.miniMessage().deserialize("&lt;color:#7c86ff&gt;Essentials&lt;/color&gt; &lt;color:#52525c&gt;»&lt;/color&gt; &lt;color:#cad5e2&gt;"); public static final TextColor HIGHLIGHT = TextColor.color(0x00bcff); public static final MiniMessage MINI_MESSAGE = MiniMessage.builder() .editTags(builder -> { builder.tag("prefix", Tag.inserting(PREFIX)); builder.tag("hl", Tag.styling(HIGHLIGHT)); builder.tag("ss", Tag.styling(TextColor.color(0x7bf1a8))); builder.tag("ex", Tag.styling(TextColor.color(0xff6467))); }).build();

Load Resource Bundles into the GlobalTranslator

  • In your JavaPlugin class implementation, define this method:

    This loads the German Resource Bundle from your plugin resources:

    private void loadLocales() { MiniMessageTranslationStore translationStore = MiniMessageTranslationStore .create( new NamespacedKey(this, "messages"), MINI_MESSAGE // insert your custom instance ); for (Locale locale : List.of(Locale.GERMANY)) { ResourceBundle bundle = ResourceBundle.getBundle( "lang.messages", locale, getClassLoader(), UTF8ResourceBundleControl.get() ); translationStore.registerAll(locale, bundle, false); } GlobalTranslator.translator().addSource(translationStore); // Sets German as the fallback for any undefined language translationStore.defaultLocale(Locale.GERMANY); }
29 September 2025
Code Style ConventionsAbout