Package de.clickism.configured.localization

Class Localization

java.lang.Object
de.clickism.configured.localization.Localization
public class Localization extends Object
Localization class for managing localized messages.

  • Constructor Details

    • Localization

      public Localization(Function<String,File> fileGenerator, de.clickism.configured.format.ConfigFormat format)
      Creates a new Localization instance with the specified format and file generator.
      Parameters:
      fileGenerator - a function that generates a File based on the language code
      format - the format to use for localization files

  • Method Details

    • of

      public static Localization of(Function<String,String> pathGenerator)
      Creates a new Localization instance with the given path generator function. The format will be determined based on the file extension of the path generated for an empty language code.

      Available formats are:

      • .yml / .yaml: Standard YAML format
      • .json: Standard JSON format
      • .jsonc: JSON with comments

      WARNING: Make sure you have the correct format module (i.E: "configured-yaml") added to your project to use the desired format.

      Parameters:
      pathGenerator - a function that generates the path for the localization file based on the language code
      Returns:
      a new Localization instance
      Throws:
      IllegalArgumentException - if no format is found for the file extension

    • of

      public static Localization of(Function<String,String> pathGenerator, de.clickism.configured.format.ConfigFormat format)
      Creates a new Localization instance with the given path generator function and format.
      Parameters:
      pathGenerator - a function that generates the path for the localization file based on the language code
      format - the format to use for localization files
      Returns:
      a new Localization instance

    • fallbackLanguage

      public Localization fallbackLanguage(String language)
      Sets the fallback language to use.

      If the language file for the fallback language does not exist, it will not be generated.

      The fallback language will be used when the primary language file does not contain a translation for a given key.

      Parameters:
      language - the language code to use as the fallback language
      Returns:
      this Localization instance

    • fallbackLanguage

      @Nullable public @Nullable String fallbackLanguage()
      Gets the fallback language code.
      Returns:
      the fallback language code, or null if not set

    • language

      public Localization language(String language)
      Sets the language to use for localization.
      Parameters:
      language - the language code to use
      Returns:
      this Localization instance

    • language

      @Nullable public @Nullable String language()
      Gets the language code currently set for localization.
      Returns:
      the language code, or null if not set

    • version

      public Localization version(int version)
      Sets the version of the localization.

      See Config.version(int) for more information.

      Parameters:
      version - the version number to set
      Returns:
      this Localization instance

    • version

      @Nullable public @Nullable Integer version()
      Gets the version of the localization.
      Returns:
      the version number, or null if not set

    • registerKeysFor

      public <T extends Enum<T> & LocalizationKey> Localization registerKeysFor(Class<T> enumClass)
      Registers all keys from the given enum class that implements LocalizationKey.

      You only need to register keys if you want to update local files with newer keys when there is a version mismatch.

      For more information, see updateWithNewKeys(boolean).

      Type Parameters:
      T - the type of the enum, which must implement LocalizationKey
      Parameters:
      enumClass - the enum class containing localization keys
      Returns:
      this Localization instance

    • registerKey

      public Localization registerKey(LocalizationKey key)
      Registers a single localization key.

      You only need to register keys if you want to update local files with newer keys when there is a version mismatch.

      For more information, see updateWithNewKeys(boolean).

      Parameters:
      key - the localization key to register
      Returns:
      this Localization instance

    • updateWithNewKeys

      public Localization updateWithNewKeys(boolean updateWithNewKeys)
      Sets whether to update the localization files with new keys.

      WARNING: If you set this to true, make sure to register all localization keys via registerKeysFor(Class) for enums or registerKey(LocalizationKey) for individual keys. Otherwise, this is DESTRUCTIVE and will remove data unregistered for unregistered keys.

      This will only affect local files that are not deployed from the resource directory. If the localization files are not local and can be deployed from the resource directory, they will always be updated with new keys regardless of this setting.

      Parameters:
      updateWithNewKeys - whether to update the localization files with new keys
      Returns:
      this Localization instance

    • load

      public Localization load()
      Loads the localization files (config) based on the configured language and fallback language.

      If the config file for the current language or the fallback language does not exist, it will be deployed/generated.

      This method will try to load the fallback language if no language is set.

      If no language or fallback language is set, this method will not do anything.

      Returns:
      this Localization instance.

    • get

      public String get(LocalizationKey key, Object... params)
      Retrieves a localized string for the given key with the specified parameters.

      This method will replace placeholders in the localized string with the provided parameters in the exact order they were specified.

      Example: 

       enum Keys implements LocalizationKey {
    @Parameters({"user", "attempts"})
     WARN_LOGIN_ATTEMPTS;
 }
      You can then use this method to get the localized string: 
       localization.get(Keys.WARN_LOGIN_ATTEMPTS, "Clickism", 3);
      Which will replace the placeholder {user} with Clickism and {attempts} with 3.

      If more parameters are provided than there are placeholders in the localized string, the extra parameters will be ignored.

      If too few parameters are provided, the remaining placeholders will not be replaced and will remain in the string.

      Parameters:
      key - the localization key to retrieve the string for
      params - parameters to replace in the localized string, in the order they appear in the key's parameters
      Returns:
      the localized string with parameters replaced, or the localization key if no localization available

    • resourceProvider

      public Localization resourceProvider(Class<?> clazz, Function<String,String> pathGenerator)
      Sets the resource provider from which localization files can be deployed.

      If you set a resource provider, the localization file(s) for the current language will be deployed from the resource path generated via the given path generator function. The localization file(s) will be deployed to the file path generated by the file generator function passed to the constructor. See of(Function) for more information.

      The current version of the localization file will be added automatically to the deployed file if the version key is missing in the resource file.

      The path generator function should take a language code as input and return the path to the localization file for that language.

      For a path in your resources folder, i.E: main/java/.../resources/, make your path generator starts with / to ensure it starts from the root of the classpath.

      Example usage: .resourceDirectory(Main.class, lang -> "/locales/" + lang + ".yml");

      Parameters:
      clazz - the class from which the resource directory will be derived, usually the main class of your application.
      pathGenerator - a function that generates the path to the localization file given a language code.
      Returns:
      this Localization instance

    • parameterFormat

      public String parameterFormat()
      Retrieves the current parameter format used for placeholders in localized strings.
      Returns:
      the parameter format as a string

    • parameterFormat

      public Localization parameterFormat(String parameterFormat)
      Sets the format for parameter placeholders in localized strings. Only change this if you want to use a different format for parameters in your localization strings.

      Default is {%s}.

      Parameters:
      parameterFormat - the format string for parameter placeholders, where %s will be replaced by the parameter name.
      Returns:
      this Localization instance

    • deploySingleResource

      protected boolean deploySingleResource(Class<?> clazz, String resourcePath, String destinationPath)
      Deploys a single resource from the specified class's resources to a given destination path. The method copies the resource from the classpath to the specified file path on the filesystem.

      If the resource does not exist or an error occurs during the copy process, the method logs the error and returns false. If the operation is successful, it returns true.

      Parameters:
      clazz - the class from whose resources the resource will be retrieved
      resourcePath - the path to the resource within the class's resources
      destinationPath - the filesystem path where the resource should be deployed
      Returns:
      true if the resource was successfully deployed, false otherwise