chore: license file

Author: sasuked

README.MD

@@ -0,0 +1,108 @@
+# Translatica
+
+**Translatica** is a lightweight Java library for managing messages and translations using `ResourceBundle`. It allows you to register and retrieve localized messages based on `Locale`, making internationalization of applications easier.
+
+## Installation
+
+### Maven
+Add the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>io.github.mtbarr</groupId>
+    <artifactId>translatica</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+### Gradle
+Add the following to your `build.gradle`:
+
+```groovy
+dependencies {
+    implementation 'io.github.mtbarr:translatica:1.0-SNAPSHOT'
+}
+```
+
+## Usage Example
+
+The main class of the project is `MessageRegistry`, which allows you to register and retrieve messages from properties files. Below are some examples of how to use the library.
+
+### Registering Messages
+
+```java
+import io.github.mtbarr.translatica.MessageRegistry;
+
+public class Main {
+    public static void main(String[] args) {
+        // Create a message registry using the default "messages.properties" file
+        MessageRegistry registry = new MessageRegistry();
+
+        // Alternatively, specify a custom properties file
+        MessageRegistry customRegistry = new MessageRegistry("customMessages");
+    }
+}
+```
+
+### Retrieving Messages
+
+```java
+import io.github.mtbarr.translatica.MessageRegistry;
+
+import java.util.Locale;
+
+public class Main {
+  public static void main(String[] args) {
+    // Create a registry
+    // Creating it with no arguments will use the default "messages.properties" file
+    MessageRegistry registry = new MessageRegistry();
+    //    MessageRegistry registry = new MessageRegistry("custom_messages");
+
+
+    // Retrieve a message with the default locale
+    String message = registry.get("welcome.message");
+
+    // Retrieve a message for a specific locale
+    String messageInFrench = registry.get(Locale.FRENCH, "welcome.message");
+
+    // Retrieve a message with replacements
+    String formattedMessage = registry.get("welcome.user", "John");
+
+    System.out.println(message);           // Output: Welcome!
+    System.out.println(messageInFrench);   // Output: Bienvenue!
+    System.out.println(formattedMessage);  // Output: Welcome, John!
+  }
+}
+```
+
+### Static Access
+
+You can also use the static methods for accessing messages without needing to instantiate `MessageRegistry`:
+
+```java
+import io.github.mtbarr.translatica.MessageRegistry;
+
+public class Main {
+    public static void main(String[] args) {
+        // Retrieve a message statically
+        String message = MessageRegistry.getMessage("welcome.message");
+
+        // Retrieve a formatted message statically
+        String formattedMessage = MessageRegistry.getFormattedMessage("welcome.user", "John");
+        
+        System.out.println(message);           // Output: Welcome!
+        System.out.println(formattedMessage);  // Output: Welcome, John!
+    }
+}
+```
+
+## Features
+
+- **Locale-based message retrieval**: Get translated messages based on the `Locale`.
+- **Message formatting**: Supports message formatting with dynamic replacements.
+- **Simple resource bundle registration**: Easily register message bundles from `.properties` files.
+- **Static methods**: Access messages without creating an instance of `MessageRegistry`.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

build.gradle

@@ -12,8 +12,17 @@ repositories {
 dependencies {
     testImplementation platform('org.junit:junit-bom:5.10.0')
     testImplementation 'org.junit.jupiter:junit-jupiter'
+
+    compileOnly 'org.jetbrains:annotations:20.1.0'
+    annotationProcessor 'org.jetbrains:annotations:20.1.0'
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(8)
+    }
 }
 
 test {
     useJUnitPlatform()
-}
+}

src/main/java/io/github/mtbarr/translatica/MessageRegistry.java

@@ -0,0 +1,227 @@
+package io.github.mtbarr.translatica;
+
+import org.jetbrains.annotations.NotNull;
+
+import java.nio.charset.StandardCharsets;
+import java.text.MessageFormat;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
+
+/**
+ * A registry of keyed messages with the source {@link Locale}.
+ *
+ * @author Matheus Barreto
+ */
+public final class MessageRegistry {
+
+
+  private static MessageRegistry instance;
+
+  private final Map<Locale, List<ResourceBundle>> bundles = new ConcurrentHashMap<>();
+
+  public MessageRegistry(@NotNull String propertiesFileName) {
+    this.registerMessages(PropertyResourceBundle.getBundle(propertiesFileName));
+  }
+
+  /**
+   * Default constructor using 'messages' file
+   */
+  public MessageRegistry() {
+    this("messages");
+  }
+
+
+  /**
+   * Register all messages present in the provided resource bundle.
+   *
+   * @param resourceBundle ResourceBundle containing all messages.
+   **/
+  public void registerMessages(@NotNull ResourceBundle resourceBundle) {
+    List<ResourceBundle> bundleList = bundles.computeIfAbsent(resourceBundle.getLocale(), key -> new CopyOnWriteArrayList<>());
+    bundleList.add(resourceBundle);
+  }
+
+  /**
+   * Register all messages from the provided ResourceBundle that are registered.
+   *
+   * @param resourceBundle provided resouce bundle.
+   */
+  public void unregisterMessages(@NotNull ResourceBundle resourceBundle) {
+    List<ResourceBundle> bundleList = bundles.get(resourceBundle.getLocale());
+    if (bundleList != null) {
+      bundleList.removeIf(bundle -> bundle.getLocale().equals(resourceBundle.getLocale()));
+    }
+  }
+
+  /**
+   * Gets a keyed message according to the provided Locale.
+   *
+   * @param locale message locale.
+   * @param key    message key.
+   * @return a translated message valued based on {@param locale} provided.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  public String get(Locale locale, String key) {
+    List<ResourceBundle> bundleList = bundles.get(locale);
+    if (bundleList == null) {
+      throw new IllegalArgumentException("Cannot found resource bundle for this locale.");
+    }
+
+    for (ResourceBundle bundle : bundleList) {
+      return this.findBundleMessage(key, bundle);
+    }
+
+    throw new NullPointerException("Cannot found message keyed with " + key + " key on locale " + locale.getDisplayName());
+  }
+
+
+  /**
+   * Gets a keyed message according to the default Locale.
+   *
+   * @param key message key.
+   * @return a translated message valued based on default locale.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public String get(String key) {
+    return get(Locale.getDefault(), key);
+  }
+
+  /**
+   * Equivalent to {@link MessageRegistry#get(Locale, String)}
+   * but with replacements being provided.
+   *
+   * @param locale       message locale
+   * @param key          message key
+   * @param replacements message replacements
+   * @return a final replaced version of initial keyed message.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public String get(Locale locale, String key, Object... replacements) {
+    return String.format(get(locale, key), replacements);
+  }
+
+
+  /**
+   * Equivalent to {@link MessageRegistry#get(String)}
+   * but with replacements being provided.
+   *
+   * @param key          message key
+   * @param replacements message replacements
+   * @return a final replaced version of initial keyed message.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public String get(String key, Object... replacements) {
+    return get(Locale.getDefault(), key, replacements);
+  }
+
+  /**
+   * Gets the main instance of the message registry.
+   */
+  public static MessageRegistry getInstance() {
+    if (instance == null) {
+      instance = new MessageRegistry();
+    }
+
+    return instance;
+  }
+
+  /**
+   * Gets a keyed message according to the provided Locale.
+   *
+   * @param locale message locale.
+   * @param key    message key.
+   * @return a translated message valued based on {@param locale} provided.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public static String getMessage(@NotNull Locale locale, @NotNull String key) {
+    return getInstance().get(locale, key);
+  }
+
+  /**
+   * Equivalent to {@link MessageRegistry#get(Locale, String)}
+   * but with replacements being provided.
+   *
+   * @param locale       message locale
+   * @param key          message key
+   * @param replacements message replacements
+   * @return a final replaced version of initial keyed message.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public static String getMessage(@NotNull Locale locale, @NotNull String key, @NotNull Object... replacements) {
+    return getInstance().get(locale, key, replacements);
+  }
+
+  /**
+   * Gets a keyed message according to the default Locale.
+   *
+   * @param key message key.
+   * @return a translated message valued based on default locale.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public static String getMessage(@NotNull String key) {
+    return getInstance().get(key);
+  }
+
+  /**
+   * Equivalent to {@link MessageRegistry#get(String)}
+   * but with replacements being provided.
+   *
+   * @param key          message key
+   * @param replacements message replacements
+   * @return a final replaced version of initial keyed message.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public static String getMessage(@NotNull String key, @NotNull Object... replacements) {
+    return getInstance().get(key, replacements);
+  }
+
+  /**
+   * Equivalent to {@link MessageRegistry#get(String, Object...)}
+   * but using {@link MessageFormat#format(String, Object...)}
+   *
+   * @param key          message key
+   * @param replacements message replacements
+   * @return a final replaced version of initial keyed message.
+   * @throws IllegalArgumentException if the message value is not found.
+   */
+  @NotNull
+  public static String getFormattedMessage(@NotNull String key, Object... replacements) {
+    return MessageFormat.format(getMessage(key), replacements);
+  }
+
+  /**
+   * Get a section of the message registry.
+   * <p>
+   * Example:
+   * foo.bar.baz
+   * <p></>
+   * Where foo is the section, bar is the subsection and baz is the key.
+   *
+   * @param sectionName the section name.
+   * @return a section of the message registry.
+   */
+  public static MessageSection getSection(String sectionName) {
+    return new MessageSection(sectionName);
+  }
+
+  private static String encodeToUtf8(String value) {
+    byte[] bytes = value.getBytes();
+    return new String(bytes, StandardCharsets.UTF_8);
+  }
+
+  private String findBundleMessage(String key, ResourceBundle bundle) {
+    try {
+      return bundle.getString(key);
+    } catch (Exception e) {
+      throw new NullPointerException("Cannot found message keyed with " + key + " key on bundle " + bundle.getBaseBundleName());
+    }
+  }
+}