Class Messages

java.lang.Object
dev.ua.theroer.magicutils.lang.Messages
public final class Messages extends Object
Global entry point for resolving and sending localized messages.

Three flavours of API:

  • getRaw(String), get(String), send(Object, String) — direct methods covering 95% of call sites. Accept any sender-like object (Audience / Player / null) and any placeholder shape (Map / varargs key-value pairs / positional args).
  • query(String) — fluent builder for the rare cases that need explicit language pinning, manual escape control, or are otherwise too complex for one call.
  • view(String) — same surface but resolved against a named per-plugin scope.

Rendering rules:

  • getRaw(String) returns a plain string. Placeholders are substituted but their values are not tag-escaped, so a translation containing <red>{name}</red> will interpret {name} as MiniMessage text on later parsing. Use this when callers control the placeholder values.
  • get(String) produces a Component via MiniMessage and always escapes placeholder values, so untrusted user input cannot inject tags.
  • send(Object, String) resolves like get(String) and dispatches the component to the audience, in the audience's preferred language.

Plugin-specific overrides:

  • Method Details

    • setLanguageManager

      public static void setLanguageManager(LanguageManager manager)
      Sets the default (global) language manager.
      Parameters:
      manager - language manager or null to clear

    • getLanguageManager

      public static LanguageManager getLanguageManager()
      Returns:
      the default language manager, or null

    • register

      public static void register(String scope, LanguageManager manager)
      Registers a scoped (per-plugin) language manager.
      Parameters:
      scope - scope identifier (typically plugin/mod name)
      manager - language manager, or null to unregister

    • unregister

      public static void unregister(String scope)
      Unregisters a scoped language manager.
      Parameters:
      scope - scope identifier

    • getLanguageManager

      public static LanguageManager getLanguageManager(String scope)
      Parameters:
      scope - scope identifier
      Returns:
      scoped language manager or null

    • view

      public static MessagesView view(String scope)
      Parameters:
      scope - scope identifier
      Returns:
      scoped view for message resolution

    • view

      public static MessagesView view(LanguageManager manager)
      Parameters:
      manager - language manager to bind the view to
      Returns:
      view bound directly to the manager

    • getRaw

      public static String getRaw(String key)
      Resolves a key against the default language manager.
      Parameters:
      key - message key
      Returns:
      resolved string, or the key itself when no manager is set

    • getRaw

      public static String getRaw(@Nullable @Nullable Object recipient, String key)
      Resolves a key in the recipient's preferred language.
      Parameters:
      recipient - Audience, platform sender, or null
      key - message key
      Returns:
      resolved string

    • getRaw

      public static String getRaw(@Nullable @Nullable Object recipient, String key, Object... args)
      Resolves a key with placeholder substitution.

      args accepts any shape supported by MsgFmt.apply(String, Object...): a single Map, an Iterable, an array, key-value pairs ("name", value, "count", 5), or positional values.

      Parameters:
      recipient - Audience, platform sender, or null
      key - message key
      args - placeholder values
      Returns:
      resolved string with placeholders applied

    • get

      public static net.kyori.adventure.text.Component get(String key)
      Resolves a key and parses the result as MiniMessage.
      Parameters:
      key - message key
      Returns:
      adventure component

    • get

      public static net.kyori.adventure.text.Component get(@Nullable @Nullable Object recipient, String key)
      Resolves a key in the recipient's preferred language and parses as MiniMessage.
      Parameters:
      recipient - Audience, platform sender, or null
      key - message key
      Returns:
      adventure component

    • get

      public static net.kyori.adventure.text.Component get(@Nullable @Nullable Object recipient, String key, Object... args)
      Resolves a key with placeholders (values escaped before parsing) and returns an adventure component.
      Parameters:
      recipient - Audience, platform sender, or null
      key - message key
      args - placeholder values
      Returns:
      adventure component

    • send

      public static void send(@Nullable @Nullable Object recipient, String key)
      Resolves a key in the recipient's language and sends it as an Adventure component.
      Parameters:
      recipient - Audience, platform sender, or null (no-op)
      key - message key

    • send

      public static void send(@Nullable @Nullable Object recipient, String key, Object... args)
      Resolves a key with placeholders (values escaped) and sends the component to the recipient.
      Parameters:
      recipient - Audience, platform sender, or null (no-op)
      key - message key
      args - placeholder values

    • isOverride

      public static boolean isOverride(@Nullable @Nullable String configured, String key)
      Returns true when configured represents a real override — i.e. it is non-blank and differs from the bundled English default for key.

      Useful for plugins where users may keep an English default in config without realising it: comparing against the bundled value lets you tell "user kept the default" from "user wants this exact English text even on Ukrainian clients".

      Parameters:
      configured - user-configured value (may be null/blank)
      key - message key the configured value parallels
      Returns:
      true if configured should be treated as an override

    • resolveOverride

      public static String resolveOverride(@Nullable @Nullable Object recipient, @Nullable @Nullable String configured, String key, Object... args)
      Returns configured (with placeholders applied) when it is an override; otherwise falls back to localizing key for the recipient.
      Parameters:
      recipient - Audience, platform sender, or null
      configured - optional user-configured override
      key - message key
      args - placeholder values
      Returns:
      resolved string

    • query

      public static MessageQuery query(String key)
      Starts a fluent message resolution against the default manager.
      Parameters:
      key - message key
      Returns:
      builder

    • exists

      public static boolean exists(String key)
      Parameters:
      key - message key
      Returns:
      true if the default manager has an entry for this key

    • currentLanguage

      public static String currentLanguage()
      Returns:
      active language code or "en" when no manager is set

    • getCurrentLanguage

      public static String getCurrentLanguage()
      Returns:
      active language code (legacy alias for currentLanguage()).