Class MiniMessageTranslator

java.lang.Object
net.kyori.adventure.text.minimessage.translation.MiniMessageTranslator
All Implemented Interfaces:
Translator
public abstract class MiniMessageTranslator extends Object implements Translator
A Translator implementation that translates strings using MiniMessage.

To use this feature, you should extend this class, implementing the getMiniMessageString(String, Locale) method to return the MiniMessage string for a given key and locale. After that, you can use the translator as-is using translate(TranslatableComponent, Locale), or automatically (depending on the implementing platform) using the GlobalTranslator.

This system supports arguments using <arg:0> tags (or argument, where 0 is the index of the argument to use). Alternatively, you can use named arguments by creating the translatable component using returned ComponentLike instances provided by the methods available in the Argument utility class. The provided name will be available for use in a tag as <name>, in addition to the index-based arg tag. These tags will use Tag.selfClosingInserting(Component) to create self-closing tags that insert a component representation of the argument. This can also be used to add tag instances using Argument.tag(String, Tag).

By default, the target will be a Pointered instance that solely contains the Locale of the translation. The locale can be obtained from the target using the Identity.LOCALE pointer. You can override the target by using Argument.target(Pointered).

You can also make arbitrary tag resolvers available to the deserialization process by using the tagResolver methods on Argument. Note that these tag resolvers will not be available using the <arg:0> index-based standard tag and will not cause the index to be incremented. It is therefore recommended that you put these last in the translatable component arguments to avoid potential confusion.

An example of how you might construct a translatable component would be:

Component.translatable(
  "my.translation.key", // the translation key, you'd return the MiniMessage string by implementing getMiniMessageString
  Component.text("hello"), // available as <arg:0> or <argument:0>
  Argument.string("today", "monday"), // available as <arg:1>, <argument:1> or <today>
  Argument.tag("danger", Tag.styling(NamedTextColor.RED)), // available as <arg:1>, <argument:1> or <red>, can be closed if needed
  Argument.tagResolver(StandardTags.pride()) // you can even add arbitrary tag resolvers!
);

For an easier way to create a MiniMessage translator, see MiniMessageTranslationStore.

Since:
4.20.0
See Also:

  • Constructor Details

    • MiniMessageTranslator

      public MiniMessageTranslator()
      Constructor for a MiniMessageTranslator using the default MiniMessage instance.
      Since:
      4.20.0
      See Also:

    • MiniMessageTranslator

      public MiniMessageTranslator(MiniMessage miniMessage)
      Constructor for a MiniMessageTranslator using a specific MiniMessage instance.
      Parameters:
      miniMessage - the MiniMessage instance
      Since:
      4.20.0
      See Also:

  • Method Details

    • getMiniMessageString

      protected abstract @Nullable String getMiniMessageString(String key, Locale locale)
      Returns a raw MiniMessage string for the given key.

      If no string is found for the given key, returning null will use the translatable component's fallback (or the key itself).

      Parameters:
      key - the key
      locale - the locale
      Returns:
      the resulting MiniMessage string
      Since:
      4.20.0

    • translate

      public final @Nullable MessageFormat translate(String key, Locale locale)
      Description copied from interface: Translator
      Gets a message format from a key and locale.

      When used in the GlobalTranslator, this method is called only if Translator.translate(TranslatableComponent, Locale) returns null.

      Specified by:
      translate in interface Translator
      Parameters:
      key - a translation key
      locale - a locale
      Returns:
      a message format or null to skip translation

    • translate

      public final @Nullable Component translate(TranslatableComponent component, Locale locale)
      Description copied from interface: Translator
      Gets a translated component from a translatable component and locale.

      Care should be taken to ensure you do not unintentionally remove the children or style of component. This can be avoided by copying over the children/style using the following code as an example:

      final Component myNewComponent = ...; // get your component here
return myNewComponent
  .append(component.children()) // ensure it has the original components children as well
  .applyFallbackStyle(component.style()); // apply a "fallback" style
      Specified by:
      translate in interface Translator
      Parameters:
      component - a translatable component
      locale - a locale
      Returns:
      a translated component or null to use Translator.translate(String, Locale) instead (if available)