feat: better formatters

README.md

@@ -9,7 +9,8 @@ import org.densy.polyglot.api.util.LanguageStrategy;
 import org.densy.polyglot.common.language.SimpleLanguage;
 import org.densy.polyglot.core.context.BaseTranslationContext;
 import org.densy.polyglot.core.language.SimpleLanguageStandard;
-import org.densy.polyglot.core.parameter.KeyedTrParameters;
+import org.densy.polyglot.core.parameter.KeyedTranslationParameters;
+import org.densy.polyglot.core.parameter.TrParameters;
 import org.densy.polyglot.core.provider.YamlFileProvider;
 
 import java.io.File;
@@ -46,7 +47,7 @@ translation.addTranslation(SimpleLanguage.ENG, "local.translation", "Local messa
 
 // Translating the messages
 String local = translation.translate(SimpleLanguage.RUS, "local.translation", 1);
-String global = translation.translate(SimpleLanguage.RUS, "global.translation", new KeyedTrParameters().put("local", "Parameter"));
+String global = translation.translate(SimpleLanguage.RUS, "global.translation", TrParameters.keyed().put("local", "Parameter"));
 
 System.out.println("Translated local message: " + local);
 System.out.println("Translated global message: " + global);
@@ -68,7 +69,7 @@ Adding a library api:
 <dependency>
     <groupId>org.densy.polyglot</groupId>
     <artifactId>api</artifactId>
-    <version>1.0.5-SNAPSHOT</version>
+    <vearsion>1.0.5-SNAPSHOT</vearsion>
 </dependency>
 ```
 

api/src/main/java/org/densy/polyglot/api/Translation.java

@@ -1,32 +1,83 @@
 package org.densy.polyglot.api;
 
+import org.densy.polyglot.api.formatter.TranslationFormatterAware;
 import org.densy.polyglot.api.language.Language;
-import org.densy.polyglot.api.parameter.TrParameters;
-import org.densy.polyglot.api.parameter.formatter.TrParameterFormatter;
+import org.densy.polyglot.api.parameter.TranslationParameters;
 import org.densy.polyglot.api.util.FallbackStrategy;
 import org.densy.polyglot.api.util.LanguageStrategy;
 
 import java.util.Set;
 
-public interface Translation {
+/**
+ * Translation interface. Provides methods for translating keys into localized strings
+ * with support for parameters, formatters, and fallback strategies.
+ */
+public interface Translation extends TranslationFormatterAware, TranslationsAware {
 
+    /**
+     * Translates a key into the target language.
+     *
+     * @param language the target language
+     * @param key      the translation key
+     * @return translated string, or the key itself if translation not found
+     */
     String translate(Language language, String key);
 
-    String translate(Language language, String key, TrParameters parameters);
+    /**
+     * Translates a key into the target language with parameters.
+     *
+     * @param language   the target language
+     * @param key        the translation key
+     * @param parameters the translation parameters
+     * @return translated and formatted string
+     */
+    String translate(Language language, String key, TranslationParameters parameters);
 
+    /**
+     * Translates a key into the target language with array parameters.
+     * Parameters are accessible as {0}, {1}, {2}, etc.
+     *
+     * @param language   the target language
+     * @param key        the translation key
+     * @param parameters the array parameters
+     * @return translated and formatted string
+     */
     String translate(Language language, String key, Object... parameters);
 
+    /**
+     * Gets the default language for this translation.
+     *
+     * @return default language
+     */
     Language getDefaultLanguage();
 
+    /**
+     * Sets the default language for this translation.
+     *
+     * @param language the language to set as default
+     */
     void setDefaultLanguage(Language language);
 
+    /**
+     * Sets the language strategy that determines which language to use
+     * when the requested language is not available.
+     *
+     * @param languageStrategy the language strategy
+     */
     void setLanguageStrategy(LanguageStrategy languageStrategy);
 
+    /**
+     * Sets the fallback strategy that determines what to return
+     * when a translation key is not found.
+     *
+     * @param fallbackStrategy the fallback strategy
+     */
     void setFallbackStrategy(FallbackStrategy fallbackStrategy);
 
-    void addTranslation(Language language, String key, String value);
-
-    <T extends TrParameters> void setParameterFormatter(Class<T> parameterType, TrParameterFormatter formatter);
-
+    /**
+     * Gets all languages that have at least one translation in this instance.
+     *
+     * @return set of available languages
+     */
     Set<Language> getAvailableLanguages();
-}
+}

api/src/main/java/org/densy/polyglot/api/TranslationsAware.java

@@ -0,0 +1,45 @@
+package org.densy.polyglot.api;
+
+import org.densy.polyglot.api.language.Language;
+import org.jetbrains.annotations.UnmodifiableView;
+
+import java.util.Map;
+
+/**
+ * Interface for managing translation storage.
+ */
+public interface TranslationsAware {
+
+    /**
+     * Gets all translations organized by language and key.
+     *
+     * @return unmodifiable map of translations (Language -> Key -> Translation)
+     */
+    @UnmodifiableView
+    Map<Language, Map<String, String>> getTranslations();
+
+    /**
+     * Adds a single translation for a specific language and key.
+     *
+     * @param language the target language
+     * @param key the translation key
+     * @param value the translation value
+     */
+    void addTranslation(Language language, String key, String value);
+
+    /**
+     * Adds multiple translations for a specific language.
+     *
+     * @param language the target language
+     * @param translations map of translation keys to values
+     */
+    void addTranslations(Language language, Map<String, String> translations);
+
+    /**
+     * Removes a translation for a specific language and key.
+     *
+     * @param language the target language
+     * @param key the translation key to remove
+     */
+    void removeTranslation(Language language, String key);
+}

api/src/main/java/org/densy/polyglot/api/context/TranslationContext.java

@@ -45,7 +45,7 @@ public interface TranslationContext {
     /**
      * Adds global parameter available to all translations.
      *
-     * @param key the parameter key
+     * @param key   the parameter key
      * @param value the parameter value to add
      */
     void addGlobalParameter(String key, Object value);
@@ -67,16 +67,16 @@ public interface TranslationContext {
     /**
      * Adds global translations for a language.
      *
-     * @param language the target language
+     * @param language     the target language
      * @param translations the translations to add
      */
     void addGlobalTranslations(Language language, Map<String, String> translations);
 
     /**
      * Adds global translation for a language.
      *
-     * @param language the target language
-     * @param key the message key
+     * @param language    the target language
+     * @param key         the message key
      * @param translation the translation
      */
     void addGlobalTranslation(Language language, String key, String translation);

api/src/main/java/org/densy/polyglot/api/formatter/TranslationFormatter.java

@@ -0,0 +1,18 @@
+package org.densy.polyglot.api.formatter;
+
+import org.densy.polyglot.api.formatter.context.TranslationFormatContext;
+
+/**
+ * Translation post formatter interface.
+ */
+public interface TranslationFormatter {
+
+    /**
+     * Formats translation text and by applies parameters if it needs.
+     *
+     * @param text    the text to format
+     * @param context the translation format context
+     * @return formatted text
+     */
+    String format(String text, TranslationFormatContext context);
+}

api/src/main/java/org/densy/polyglot/api/formatter/TranslationFormatterAware.java

@@ -0,0 +1,34 @@
+package org.densy.polyglot.api.formatter;
+
+import org.jetbrains.annotations.UnmodifiableView;
+
+import java.util.List;
+
+/**
+ * Interface for managing translation formatters.
+ */
+public interface TranslationFormatterAware {
+
+    /**
+     * Gets the list of registered formatters.
+     * Formatters are applied in the order they appear in this list.
+     *
+     * @return unmodifiable list of formatters
+     */
+    @UnmodifiableView
+    List<TranslationFormatter> getFormatters();
+
+    /**
+     * Adds a formatter to the end of the formatter chain.
+     *
+     * @param formatter the formatter to add
+     */
+    void addFormatter(TranslationFormatter formatter);
+
+    /**
+     * Removes a formatter from the formatter chain.
+     *
+     * @param formatter the formatter to remove
+     */
+    void removeFormatter(TranslationFormatter formatter);
+}

api/src/main/java/org/densy/polyglot/api/formatter/context/TranslationFormatContext.java

@@ -0,0 +1,39 @@
+package org.densy.polyglot.api.formatter.context;
+
+import org.densy.polyglot.api.Translation;
+import org.densy.polyglot.api.language.Language;
+import org.densy.polyglot.api.parameter.TranslationParameters;
+
+/**
+ * Translation formatting context.
+ */
+public interface TranslationFormatContext {
+
+    /**
+     * Translation key.
+     *
+     * @return the translation key
+     */
+    String getKey();
+
+    /**
+     * Translation language.
+     *
+     * @return the Language object
+     */
+    Language getLanguage();
+
+    /**
+     * Translation itself.
+     *
+     * @return the Translation object
+     */
+    Translation getTranslation();
+
+    /**
+     * Translation parameters.
+     *
+     * @return the TranslationParameters object
+     */
+    TranslationParameters getParameters();
+}

api/src/main/java/org/densy/polyglot/api/parameter/TranslationParameters.java

@@ -0,0 +1,8 @@
+package org.densy.polyglot.api.parameter;
+
+/**
+ * Base interface for translation parameters.
+ */
+public interface TranslationParameters {
+
+}

build.gradle.kts

@@ -12,7 +12,7 @@ java {
 
 allprojects {
     group = "org.densy.polyglot"
-    version = "1.0.5-SNAPSHOT"
+    version = "1.1.0-SNAPSHOT"
 }
 
 subprojects {
@@ -26,6 +26,7 @@ subprojects {
     }
 
     dependencies {
+        compileOnlyApi("org.jetbrains:annotations:24.1.0")
         compileOnlyApi("org.projectlombok:lombok:1.18.38")
         annotationProcessor("org.projectlombok:lombok:1.18.38")
     }