Package dev.itsharshxd.zentrix.api.locale

Interface LocaleService

public interface LocaleService
Access to Zentrix's active locale and text formatting pipeline.

Addons should use this service when they need messages to match the server's current Zentrix locale, prefix, small-caps setting, hex colors, and legacy color handling without depending on Zentrix internals.

Inline flags

A locale value may start with whitespace-separated flags, in any order and any combination. Every method here removes them before formatting, so they never reach a player:

  • !disabled - the owner asked for this text not to be delivered to chat or console. It stays available everywhere else, so a GUI, item, or title built from the same key still renders normally.
  • !no-prefix - never prepend the Zentrix prefix, even when the caller asked for a prefixed message.
  • !no-small-caps - keep the original capitalization regardless of the server's small-caps setting.

!no-prefix and !no-small-caps are applied by the formatting methods on their own. !disabled cannot be, because a returned string or component carries no way to say "do not send me" - so prefer send(Audience, String, Object...) and sendWithoutPrefix(Audience, String, Object...) for chat and console delivery. Only reach for isDisabled(String) when the message has to be assembled by hand, such as when click or hover components are appended to it.

Since:
1.5.0

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull String
    formatRaw(@NotNull String message, boolean includePrefix, Object... placeholders)
    Formats a raw addon-owned message through Zentrix's text pipeline.
    @NotNull net.kyori.adventure.text.Component
    formatRawComponent(@NotNull String message, boolean includePrefix, Object... placeholders)
    Formats a raw addon-owned message through Zentrix's text pipeline.
    @NotNull net.kyori.adventure.text.Component
    getComponent(@NotNull String key, Object... placeholders)
    Resolves a locale key as a prefixed Adventure component.
    @NotNull net.kyori.adventure.text.Component
    getComponentWithoutPrefix(@NotNull String key, Object... placeholders)
    Resolves a locale key as an unprefixed Adventure component.
    @NotNull String
    getCurrentLocale()
    Gets the active global Zentrix locale name, such as en.
    @NotNull String
    getMessage(@NotNull String key, Object... placeholders)
    Resolves a locale key as a prefixed legacy string.
    @NotNull String
    getMessageWithoutPrefix(@NotNull String key, Object... placeholders)
    Resolves a locale key as an unprefixed legacy string.
    default @NotNull String
    getRaw(@NotNull String key)
    One locale value exactly as the file holds it, with no formatting applied.
    default List<String>
    getStringList(@NotNull String key)
    The lines a list-valued locale key holds, unformatted.
    default boolean
    isDisabled(@NotNull String key)
    Returns whether a locale value carries the !disabled inline flag.
    default boolean
    isRawDisabled(@NotNull String message)
    Returns whether an addon-owned raw message carries the !disabled inline flag, so text from an addon's own config can support the flag the same way a Zentrix locale value does.
    default void
    send(@NotNull net.kyori.adventure.audience.Audience recipient, @NotNull String key, Object... placeholders)
    Sends a prefixed locale message to a player or the console, unless the value opted out with !disabled.
    default void
    sendWithoutPrefix(@NotNull net.kyori.adventure.audience.Audience recipient, @NotNull String key, Object... placeholders)
    Sends an unprefixed locale message to a player or the console, unless the value opted out with !disabled.

  • Method Details

    • getCurrentLocale

      @NotNull @NotNull String getCurrentLocale()
      Gets the active global Zentrix locale name, such as en.
      Returns:
      active locale name

    • getComponent

      @NotNull @NotNull net.kyori.adventure.text.Component getComponent(@NotNull @NotNull String key, Object... placeholders)
      Resolves a locale key as a prefixed Adventure component.
      Parameters:
      key - locale key
      placeholders - placeholder key/value pairs
      Returns:
      formatted component with the Zentrix prefix

    • getComponentWithoutPrefix

      @NotNull @NotNull net.kyori.adventure.text.Component getComponentWithoutPrefix(@NotNull @NotNull String key, Object... placeholders)
      Resolves a locale key as an unprefixed Adventure component.
      Parameters:
      key - locale key
      placeholders - placeholder key/value pairs
      Returns:
      formatted component without the Zentrix prefix

    • getMessage

      @NotNull @NotNull String getMessage(@NotNull @NotNull String key, Object... placeholders)
      Resolves a locale key as a prefixed legacy string.
      Parameters:
      key - locale key
      placeholders - placeholder key/value pairs
      Returns:
      formatted string with the Zentrix prefix

    • getMessageWithoutPrefix

      @NotNull @NotNull String getMessageWithoutPrefix(@NotNull @NotNull String key, Object... placeholders)
      Resolves a locale key as an unprefixed legacy string.
      Parameters:
      key - locale key
      placeholders - placeholder key/value pairs
      Returns:
      formatted string without the Zentrix prefix

    • getStringList

      @NotNull default List<String> getStringList(@NotNull @NotNull String key)
      The lines a list-valued locale key holds, unformatted.

      Everything a GUI shows more than one line of — item lore, click instructions, multi-line descriptions — is a list in the locale file. Each line still carries its & colour codes and placeholders, so run it through formatRawComponent(String, boolean, Object...) with whatever placeholders belong to it. An addon building a menu that has to look like a Zentrix one wants this rather than its own copy of the wording.

      A key that is missing, or holds a single value rather than a list, returns an empty list. So does a Zentrix build older than 1.6.0.

      Parameters:
      key - locale key
      Returns:
      the raw lines, never null
      Since:
      1.6.0

    • getRaw

      @NotNull default @NotNull String getRaw(@NotNull @NotNull String key)
      One locale value exactly as the file holds it, with no formatting applied.

      For the handful of locale entries that are data rather than text — a wrapping width, a separator — where running them through the colour pipeline would be wrong.

      Returns an empty string for a missing key, and on a Zentrix build older than 1.6.0.

      Parameters:
      key - locale key
      Returns:
      the raw value, never null
      Since:
      1.6.0

    • formatRawComponent

      @NotNull @NotNull net.kyori.adventure.text.Component formatRawComponent(@NotNull @NotNull String message, boolean includePrefix, Object... placeholders)
      Formats a raw addon-owned message through Zentrix's text pipeline.
      Parameters:
      message - raw message containing Zentrix placeholders/color codes
      includePrefix - whether to prepend the active Zentrix prefix
      placeholders - placeholder key/value pairs
      Returns:
      formatted component

    • formatRaw

      @NotNull @NotNull String formatRaw(@NotNull @NotNull String message, boolean includePrefix, Object... placeholders)
      Formats a raw addon-owned message through Zentrix's text pipeline.
      Parameters:
      message - raw message containing Zentrix placeholders/color codes
      includePrefix - whether to prepend the active Zentrix prefix
      placeholders - placeholder key/value pairs
      Returns:
      formatted legacy string

    • isDisabled

      default boolean isDisabled(@NotNull @NotNull String key)
      Returns whether a locale value carries the !disabled inline flag.

      Only chat and console delivery honors the flag. Every getter on this service keeps returning the formatted text, so the same key still works in GUIs, item text, titles, and subtitles.

      A Zentrix build older than 1.6.0 has no inline flags, so it reports every key as enabled.

      Parameters:
      key - locale key
      Returns:
      true when the value opts out of chat and console delivery
      Since:
      1.6.0

    • isRawDisabled

      default boolean isRawDisabled(@NotNull @NotNull String message)
      Returns whether an addon-owned raw message carries the !disabled inline flag, so text from an addon's own config can support the flag the same way a Zentrix locale value does.

      A Zentrix build older than 1.6.0 has no inline flags, so it reports every message as enabled.

      Parameters:
      message - raw message that may start with inline flags
      Returns:
      true when the message opts out of chat and console delivery
      Since:
      1.6.0

    • send

      default void send(@NotNull @NotNull net.kyori.adventure.audience.Audience recipient, @NotNull @NotNull String key, Object... placeholders)
      Sends a prefixed locale message to a player or the console, unless the value opted out with !disabled.
      Parameters:
      recipient - player, console, or any other Adventure audience
      key - locale key
      placeholders - placeholder key/value pairs
      Since:
      1.6.0

    • sendWithoutPrefix

      default void sendWithoutPrefix(@NotNull @NotNull net.kyori.adventure.audience.Audience recipient, @NotNull @NotNull String key, Object... placeholders)
      Sends an unprefixed locale message to a player or the console, unless the value opted out with !disabled.
      Parameters:
      recipient - player, console, or any other Adventure audience
      key - locale key
      placeholders - placeholder key/value pairs
      Since:
      1.6.0