Package valorless.valorlessutils.translate

Class Translator

java.lang.Object
valorless.valorlessutils.translate.Translator
public class Translator extends Object
Handles loading, caching, and retrieving Minecraft item/block translation strings for a given Language.

On construction, the translator attempts to load the appropriate .lang file from the plugin's data folder. If the file is not present it will be downloaded from the ValorlessUtils GitHub repository. When no server version is available (e.g. during unit-tests or early startup) a bundled fallback file is used instead.

All translation keys follow the standard Minecraft namespaced-key format (e.g. "block.minecraft.stone").

See Also:

  • Constructor Details

    • Translator

      public Translator(Language language)
      Creates a new Translator and immediately loads translations for the given Language.
      Parameters:
      language - the language whose translation file should be loaded; must not be null.

    • Translator

      @Deprecated(since="Replaced by Translator(Language), will still work until removed.", forRemoval=true) public Translator(String key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use Translator(Language) instead. This constructor will be removed in a future release.
      Creates a new Translator and immediately loads translations for the language identified by key.
      Parameters:
      key - the language code (e.g. "en_us") used to look up the corresponding Language constant.

  • Method Details

    • translate

      public String translate(String translationKey)
      Returns the localised string for the given Minecraft translation key.

      If the language map has not been loaded (e.g. the language file could not be found or parsed), the original translationKey is returned unchanged so that callers always receive a non-null result.

      Parameters:
      translationKey - the Minecraft translation key to look up (e.g. "item.minecraft.diamond_sword").
      Returns:
      the localised display name, or translationKey itself if no mapping is available.

    • Translate

      @Deprecated(since="Replaced by translate()", forRemoval=true) public String Translate(String translationKey)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use translate(String) instead. This method will be removed in a future release.
      Returns the localised string for the given Minecraft translation key.
      Parameters:
      translationKey - the Minecraft translation key to look up.
      Returns:
      the localised display name, or translationKey if no mapping is available.

    • getLanguage

      public Language getLanguage()
      Returns the Language that is currently active for this translator.
      Returns:
      the active Language; never null.

    • GetLanguageKey

      @Deprecated(since="Replaced by getLanguage()", forRemoval=true) public String GetLanguageKey()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use getLanguage() and call Language.getCode() on the result instead. This method will be removed in a future release.
      Returns the language code for the currently active language (e.g. "en_us").
      Returns:
      the language code string.

    • loadFallbackLanguage

      public String loadFallbackLanguage()
      Reads the bundled fallback.lang resource from the plugin's data folder, copying it from the plugin JAR if it has not yet been extracted.

      This method is used when the server version cannot be determined (e.g. during early startup or in test environments).

      Returns:
      the raw JSON content of the fallback language file, or null if an I/O error occurs.

    • LoadFallbackLanguage

      @Deprecated(since="Replaced by loadFallbackLanguage(String)", forRemoval=true) public String LoadFallbackLanguage()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use loadFallbackLanguage() instead. This method will be removed in a future release.
      Reads the bundled fallback.lang resource from the plugin's data folder.
      Returns:
      the raw JSON content of the fallback language file, or null if an I/O error occurs.

    • fileExists

      public boolean fileExists(Language language)
      Checks whether the .lang file for the given Language already exists in the plugin's data folder for the current server version.

      The expected path is: <dataFolder>/languages/<serverVersion>/<languageCode>.lang.

      Parameters:
      language - the language whose file presence should be checked; must not be null.
      Returns:
      true if the file exists and can be found; false otherwise.

    • FileExists

      @Deprecated(since="Replaced by fileExists()", forRemoval=true) public boolean FileExists(String key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use fileExists(Language) instead. This method will be removed in a future release.
      Checks whether the .lang file for the language identified by key exists in the plugin's data folder for the current server version.
      Parameters:
      key - the language code (e.g. "en_us").
      Returns:
      true if the file exists; false otherwise.

    • setLanguage

      public void setLanguage(Language language)
      Switches the active language to language and reloads the translation map.

      After this call, subsequent translate(String) invocations will return strings in the new language.

      Parameters:
      language - the new language to use; must not be null.

    • SetLanguage

      @Deprecated(since="Replaced by setLanguage()", forRemoval=true) public void SetLanguage(String key)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use setLanguage(Language) instead. This method will be removed in a future release.
      Switches the active language to the one identified by key and reloads the translation map.
      Parameters:
      key - the language code (e.g. "en_us").

    • getLanguageFileContent

      public String getLanguageFileContent(Language language)
      Reads and returns the raw JSON content of the .lang file for the given Language from the plugin's data folder.

      The file is expected at: <dataFolder>/languages/<serverVersion>/<languageCode>.lang.

      Parameters:
      language - the language whose file should be read; must not be null.
      Returns:
      the file content as a String, or null if an I/O error occurs or the file does not exist.

    • downloadLanguage

      public String downloadLanguage(Language language)
      Downloads the .lang file for the specified Language from the ValorlessUtils GitHub repository and saves it to the plugin's data folder.

      The method tries the following branches in order until a successful download is achieved:

      1. main
      2. dev

      The remote URL pattern is: https://raw.githubusercontent.com/Valorless/ValorlessUtils/refs/heads/<branch>/languages/<serverVersion>/<languageCode>.lang.

      If all download attempts fail, loadFallbackLanguage() is returned as a last resort.

      Parameters:
      language - the language to download; must not be null.
      Returns:
      the raw JSON content of the downloaded language file, the content of the fallback language file if all downloads fail, or null if even the fallback cannot be read.