Class LanguageManager

java.lang.Object
dev.ua.theroer.magicutils.lang.LanguageManager
public class LanguageManager extends Object
Platform-agnostic language manager.

  • Constructor Details

    • LanguageManager

      public LanguageManager(Object platformOrPlugin, ConfigManager configManager)
      Create a language manager, resolving a Platform from the provided platform or legacy plugin instance.
      Parameters:
      platformOrPlugin - platform abstraction or Bukkit plugin
      configManager - config manager for loading language files

    • LanguageManager

      public LanguageManager(Platform platform, ConfigManager configManager)
      Create a language manager bound to a specific platform.
      Parameters:
      platform - platform abstraction
      configManager - config manager for loading language files

  • Method Details

    • init

      public void init(String defaultLanguage)
      Initialise language manager and load default language (plus fallback if different).
      Parameters:
      defaultLanguage - language code to load first

    • loadLanguage

      public boolean loadLanguage(String languageCode)
      Load a language file into memory.
      Parameters:
      languageCode - language code to load
      Returns:
      true if successfully loaded

    • setLanguage

      public boolean setLanguage(String languageCode)
      Switch the current language for the manager.
      Parameters:
      languageCode - language code to set
      Returns:
      true if language is now active

    • putCustomMessage

      public void putCustomMessage(String languageCode, String key, String value)
      Add or update a custom message for a specific language (or current language when null). Saves the language file immediately.
      Parameters:
      languageCode - target language or null for current
      key - message key
      value - message text (null removes the key)

    • registerTranslations

      public void registerTranslations(Map<String, Map<String,String>> translationsByLanguage)
      Register bundled plugin translations for multiple languages. Registered values are merged into already-loaded languages immediately and applied automatically to any language loaded later. Existing custom message values are preserved to avoid overwriting user overrides from disk.
      Parameters:
      translationsByLanguage - language -> (message key -> message text)

    • registerTranslations

      public void registerTranslations(String languageCode, Map<String,String> translations)
      Register bundled plugin translations for a single language. Registered values are merged into already-loaded languages immediately and applied automatically to any language loaded later. Existing custom message values are preserved to avoid overwriting user overrides from disk.
      Parameters:
      languageCode - language code to attach translations to
      translations - message key -> message text

    • registerBundledTranslations

      public int registerBundledTranslations(String namespace)
      Loads every /lang/<namespace>/<code>.json file the classpath exposes and registers them as bundled translations for this language manager. Plugins use this to ship default translations alongside their jar without each plugin re-implementing resource loading.

      Existing custom (user-edited) values on disk are preserved. Files are scanned via BundledTranslations.availableNamespacedCodes(String).

      Parameters:
      namespace - plugin namespace (e.g. "leavepulse")
      Returns:
      number of language codes that contributed at least one key

    • setFallbackLanguage

      public void setFallbackLanguage(String languageCode)
      Set fallback language used when a key is missing in the current language.
      Parameters:
      languageCode - fallback language code

    • getAvailableLanguages

      public Set<String> getAvailableLanguages()
      List languages available on disk or already loaded.
      Returns:
      set of language codes found on disk or loaded in memory

    • getLanguageInfos

      public Map<String, LanguageInfo> getLanguageInfos()
      Get metadata for every available language.
      Returns:
      metadata for each available language

    • getMessage

      public String getMessage(String key)
      Resolve a message in the current language.
      Parameters:
      key - message key
      Returns:
      resolved message or key if missing

    • getMessageFor

      public String getMessageFor(Audience audience, String key)
      Resolve a message in the audience's preferred language.
      Parameters:
      audience - target audience (may be null → falls back to current language)
      key - message key
      Returns:
      resolved message or key if missing

    • getMessageIn

      public String getMessageIn(String languageCode, String key)
      Resolve a message in a specific language code.
      Parameters:
      languageCode - language code to use
      key - message key
      Returns:
      resolved message or key if missing

    • hasMessage

      public boolean hasMessage(String key)
      Parameters:
      key - message key
      Returns:
      true if the current language (or fallback chain) has this key

    • hasMessageIn

      public boolean hasMessageIn(String languageCode, String key)
      Parameters:
      languageCode - language code
      key - message key
      Returns:
      true if this language (or the fallback chain) has the key

    • setPlayerLanguage

      public boolean setPlayerLanguage(UUID playerId, String languageCode)
      Assign a preferred language for a player.
      Parameters:
      playerId - player UUID
      languageCode - language code to set (null/empty clears preference)
      Returns:
      true if updated

    • setPlayerLanguage

      public boolean setPlayerLanguage(Audience audience, String languageCode)
      Assign a preferred language for an Audience.
      Parameters:
      audience - audience with id
      languageCode - language code to set
      Returns:
      true if updated

    • setPlayerLanguage

      public boolean setPlayerLanguage(Object player, String languageCode)
      Assign a preferred language for a player-like object (expects getUniqueId()).
      Parameters:
      player - player object
      languageCode - language code to set
      Returns:
      true if updated

    • clearPlayerLanguage

      public void clearPlayerLanguage(UUID playerId)
      Remove stored language preference for a player.
      Parameters:
      playerId - player UUID

    • setAutoDetectedPlayerLanguage

      public boolean setAutoDetectedPlayerLanguage(UUID playerId, String languageCode)
      Assign an auto-detected language for a player based on client locale data.

      Auto-detected languages are used only when no explicit player language override exists.

      Parameters:
      playerId - player UUID
      languageCode - locale tag or language code to resolve
      Returns:
      true if a supported language was stored or cleared

    • setAutoDetectedPlayerLanguage

      public boolean setAutoDetectedPlayerLanguage(Audience audience, String languageCode)
      Assign an auto-detected language for an Audience.
      Parameters:
      audience - audience with id
      languageCode - locale tag or language code to resolve
      Returns:
      true if updated

    • clearAutoDetectedPlayerLanguage

      public void clearAutoDetectedPlayerLanguage(UUID playerId)
      Remove stored auto-detected language for a player.
      Parameters:
      playerId - player UUID

    • clearAutoDetectedPlayerLanguage

      public void clearAutoDetectedPlayerLanguage(Object player)
      Remove stored auto-detected language for an arbitrary player object.
      Parameters:
      player - player object

    • clearPlayerLanguage

      public void clearPlayerLanguage(Object player)
      Remove stored language preference for an arbitrary player object.
      Parameters:
      player - player object

    • getPlayerLanguage

      public String getPlayerLanguage(UUID playerId)
      Get stored language for a player or current language if none.
      Parameters:
      playerId - player UUID
      Returns:
      language code

    • getPlayerLanguage

      public String getPlayerLanguage(Object player)
      Get stored language for a player-like object.
      Parameters:
      player - player object
      Returns:
      language code

    • getPlayerLanguages

      public Map<UUID,String> getPlayerLanguages()
      Snapshot of stored player language preferences.
      Returns:
      snapshot of player language preferences

    • getAutoDetectedPlayerLanguages

      public Map<UUID,String> getAutoDetectedPlayerLanguages()
      Snapshot of auto-detected player language preferences.
      Returns:
      snapshot of auto-detected player language preferences

    • resolveSupportedLanguageCode

      public String resolveSupportedLanguageCode(String languageCode)
      Resolve a supported language code from a client locale tag or language code.
      Parameters:
      languageCode - client locale tag or language code
      Returns:
      supported language code, or null when no supported match exists

    • bindClientLocaleSync

      public ListenerSubscription bindClientLocaleSync()
      Binds automatic player locale synchronization to the manager platform.
      Returns:
      subscription that removes the registered listeners

    • bindClientLocaleSync

      public ListenerSubscription bindClientLocaleSync(Platform targetPlatform)
      Binds automatic player locale synchronization to the provided platform.
      Parameters:
      targetPlatform - platform to subscribe to
      Returns:
      subscription that removes the registered listeners

    • reload

      public void reload()
      Reload all loaded languages from disk.

    • saveCustomMessages

      public void saveCustomMessages(String languageCode, Map<String,String> customMessages)
      Persist custom messages into the language file.
      Parameters:
      languageCode - language to modify
      customMessages - map of keys to values to persist

    • addMagicUtilsMessages

      public void addMagicUtilsMessages()
      Persist currently loaded MagicUtils messages (ensures defaults exist).

    • loadLanguageAsync

      public CompletableFuture<Boolean> loadLanguageAsync(String languageCode)
      Load a language asynchronously to avoid blocking the main thread.
      Parameters:
      languageCode - language code to load
      Returns:
      future that completes with true if loaded successfully

    • loadLanguageSmart

      public CompletableFuture<Boolean> loadLanguageSmart(String languageCode)
      Load a language and return a future that completes when loading finishes.
      Parameters:
      languageCode - language code to load
      Returns:
      future that completes with true if loaded successfully

    • setLanguageAsync

      public CompletableFuture<Boolean> setLanguageAsync(String languageCode)
      Switch active language asynchronously.
      Parameters:
      languageCode - language code
      Returns:
      future that completes with true if active language is set

    • setLanguageSmart

      public CompletableFuture<Boolean> setLanguageSmart(String languageCode)
      Switch active language, auto-switching to async when on sensitive threads.
      Parameters:
      languageCode - language code
      Returns:
      future that completes with true if active language is set

    • reloadAsync

      public CompletableFuture<Void> reloadAsync()
      Reload all loaded languages asynchronously.
      Returns:
      future that completes after reload

    • reloadSmart

      public CompletableFuture<Void> reloadSmart()
      Reload all loaded languages, auto-switching to async on sensitive threads.
      Returns:
      future that completes after reload