Class LocaleManager

java.lang.Object
com.everdro1d.libs.locale.LocaleManager
public class LocaleManager extends Object
The LocaleManager class is responsible for managing application locales, primarily for Swing GUI applications. It provides functionality to load, save, and manipulate locale data, enabling dynamic text updates for UI components.

Key Features:

  • Manages locale files stored in JSON format.
  • Supports ISO 639-3 language codes for locale identification.
  • Allows dynamic reloading of locales and notifies listeners of locale changes.
  • Provides methods to add, remove, and retrieve locale-specific text for UI components.
  • Ensures locale data is saved on application shutdown if updated.

Usage Examples:

 // Initialize the LocaleManager
 LocaleManager localeManager = new LocaleManager(Main.class, "ImADeveloper");

 // Load a locale file
 localeManager.loadLocaleFromFile("locale_eng");

 // Retrieve text for a specific UI component
 String buttonText = localeManager.getVariableSpecificMap("MainWindow", "button1", "text");

 // Save updated locale data
 localeManager.saveLocaleToFile("locale_eng", localeManager.getLocaleMap(), true);

Note: This class is designed to work with applications that have text based UI components, GUI or CLI.

See Also:
  • LocaleMap

  • Constructor Details

    • LocaleManager

      public LocaleManager(Class<?> clazz, String developerName)
      Initializes the LocaleManager with the specified class and developer directory name. Sets up the locale directory path and initializes the valid locales map.
      Parameters:
      clazz - the class associated with the application
      developerName - the developer's name for directory organization

  • Method Details

    • loadLocaleFromFile

      public void loadLocaleFromFile(String localeFileName)
      Loads a locale from a file. Defaults to English if the file does not exist or is invalid. The file name should follow the format "locale_[id]" or "[id]" (e.g., "locale_eng" or "eng").
      Parameters:
      localeFileName - the name of the locale file (without the file extension)

    • saveLocaleToFile

      public void saveLocaleToFile(String localeFileName, Map<String, Map<String, Map<String,String>>> localeMap, boolean overwrite)
      Saves the provided locale map to a file. The file name should follow the format "locale_[id]" or "[id]".
      Parameters:
      localeFileName - the name of the locale file (without the file extension)
      localeMap - the locale map to save
      overwrite - whether to overwrite an existing file with the same name

    • isLocaleCodeValid

      public boolean isLocaleCodeValid(String locale)
      Validates whether the provided locale code exists in the valid locale map.
      Parameters:
      locale - the locale code to validate
      Returns:
      true if the locale code is valid, false otherwise

    • checkForLocaleFile

      public boolean checkForLocaleFile(String fileName)
      Checks if the specified locale file exists. Creates the "/locales/" directory in application config if it does not exist.
      Parameters:
      fileName - the name of the locale file (ex: locale_eng)
      Returns:
      true if the locale file exists, false otherwise

    • printValidLocales

      public void printValidLocales()
      Prints all valid locale codes and their corresponding language names to the console.

    • getISOCodes

      public String[] getISOCodes()
      Retrieves an array of ISO 639-3 codes for all available locales.
      Returns:
      an array of 3-letter ISO 639 codes

    • reloadLocaleInProgram

      public void reloadLocaleInProgram(String newLocale)
      Reloads the locale in the program by loading the specified locale file and notifying all active LocaleChangeListener.

      Example Usage:

       localeManager.reloadLocaleInProgram(prefs.get("currentLocale", "eng"));
      Parameters:
      newLocale - the new locale code to load

    • getValidLocaleMap

      public Map<String,String> getValidLocaleMap()
      Retrieves a map of all valid locales with their ISO 639 codes and language names.
      Returns:
      a map of valid locale ISO 639-3 codes and their respective language names.

    • getLocaleMap

      public Map<String, Map<String, Map<String,String>>> getLocaleMap()
      Retrieves the entire locale map, which contains UI component text mappings.

      Outermost key being the Class Name of the UI component, and the inner key being the name of the component, and the third key being the descriptive variable with the value being the text to display.

      Returns:
      the locale map

    • setLocaleMap

      public void setLocaleMap(Map<String, Map<String, Map<String,String>>> LocaleMap)
      Sets the locale map and marks it as updated.

      Outermost key being the Class Name of the UI component, and the inner key being the name of the component, and the third key being the descriptive variable with the value being the text to display.

      Parameters:
      LocaleMap - the new locale map to set

    • getClassesInLocaleMap

      public List<String> getClassesInLocaleMap()
      Retrieves a list of all class names in the locale map.
      Returns:
      a list of class names

    • getComponentsInClassMap

      public List<String> getComponentsInClassMap(String className)
      Retrieves a list of all component names for a specific class in the locale map.
      Parameters:
      className - the class name to search for
      Returns:
      a list of component names, or an empty list if the class is not found

    • getVariablesInComponentMap

      public List<String> getVariablesInComponentMap(String className, String componentName)
      Retrieves a list of all variable names for a specific component in the locale map.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      Returns:
      a list of variable names, or an empty list if the class or component is not found

    • getClassSpecificMap

      public Map<String, Map<String,String>> getClassSpecificMap(String className)
      Retrieves the locale map for a specific class.
      Parameters:
      className - the class name to retrieve
      Returns:
      the locale map for the specified class, or an empty map if the class is not found

    • getAllVariablesWithinClassSpecificMap

      public Map<String,String> getAllVariablesWithinClassSpecificMap(String className)
      Retrieves all variables within a specific class's locale map.
      Parameters:
      className - the class name to retrieve
      Returns:
      a map of all variables and their text values, or an empty map if the class is not found

    • addClassSpecificMap

      public void addClassSpecificMap(String className, Map<String, Map<String,String>> map)
      Adds a locale map for a specific class.
      Parameters:
      className - the class name to add
      map - the locale map to add

    • removeClassSpecificMap

      public void removeClassSpecificMap(String className)
      Removes the locale map for a specific class.
      Parameters:
      className - the class name to remove

    • getComponentSpecificMap

      public Map<String,String> getComponentSpecificMap(String className, String componentName)
      Retrieves the locale map for a specific component.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      Returns:
      the locale map for the specified component, or an empty map if not found

    • addComponentSpecificMap

      public void addComponentSpecificMap(String className, String componentName, Map<String,String> map)
      Adds a locale map for a specific component.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      map - the locale map to add

    • removeComponentSpecificMap

      public void removeComponentSpecificMap(String className, String componentName)
      Removes the locale map for a specific component.
      Parameters:
      className - the class name of the component
      componentName - the name of the component to remove

    • getVariableInComponent

      public String getVariableInComponent(String className, String componentName, String variableName)
      Retrieves the text for a specific variable in the locale map.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      variableName - the name of the variable
      Returns:
      the text for the specified variable, or null if not found

    • addVariableToComponent

      public void addVariableToComponent(String className, String componentName, String variableName, String text)
      Adds a text value for a specific variable in the locale map.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      variableName - the name of the variable
      text - the text value to add

    • removeVariableInComponent

      public void removeVariableInComponent(String className, String componentName, String variableName)
      Removes a text value for a specific variable in the locale map.
      Parameters:
      className - the class name of the component
      componentName - the name of the component
      variableName - the name of the variable to remove

    • getLocaleDirectoryPath

      public Path getLocaleDirectoryPath()
      Retrieves the path to the locale directory.
      Returns:
      the path to the locale directory

    • setLocaleDirectoryPath

      public void setLocaleDirectoryPath(Path localeDirPath)
      Sets the path to the locale directory.
      Parameters:
      localeDirPath - the new path to the locale directory

    • getCurrentLocale

      public String getCurrentLocale()
      Retrieves the current locale code.
      Returns:
      the current locale code

    • getCurrentLocaleName

      public String getCurrentLocaleName()
      Retrieves the name of the current locale.
      Returns:
      the name of the current locale

    • getAvailableLocales

      public Map<String,String> getAvailableLocales()
      Retrieves a map of available locales that have corresponding files in the locale directory.
      Returns:
      a map of available locale codes and their respective language names

    • addLocaleChangeListener

      public void addLocaleChangeListener(LocaleChangeListener listener)
      Adds a listener to be notified of locale changes.
      Parameters:
      listener - the listener to add

    • removeLocaleChangeListener

      public void removeLocaleChangeListener(LocaleChangeListener listener)
      Removes a listener from being notified of locale changes.
      Parameters:
      listener - the listener to remove

    • notifyLocaleChange

      public void notifyLocaleChange()
      Notifies all registered listeners of a locale change.