feat(api): allow Translators to create their own Components

Allows Translators to bypass the loading and parsing of MessageFormat
in favor of providing their own rendered Components. Use cases may
include using MiniMessage in i18n files (in favor of §) or even raw
JSON strings/objects.

api/src/main/java/net/kyori/adventure/text/renderer/TranslatableComponentRenderer.java

@@ -73,6 +73,13 @@ public abstract class TranslatableComponentRenderer<C> extends AbstractComponent
       protected @Nullable MessageFormat translate(final @NotNull String key, final @NotNull Locale context) {
         return source.translate(key, context);
       }
+
+      @Override
+      protected @NotNull Component renderTranslatable(final @NotNull TranslatableComponent component, final @NotNull Locale context) {
+        final @Nullable Component translated = source.translate(component, context);
+        if (translated != null) return translated;
+        return super.renderTranslatable(component, context);
+      }
     };
   }
 

api/src/main/java/net/kyori/adventure/translation/GlobalTranslatorImpl.java

@@ -30,6 +30,8 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Stream;
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.TranslatableComponent;
 import net.kyori.adventure.text.renderer.TranslatableComponentRenderer;
 import net.kyori.examination.ExaminableProperty;
 import org.jetbrains.annotations.NotNull;
@@ -80,6 +82,17 @@ public boolean removeSource(final @NotNull Translator source) {
     return null;
   }
 
+  @Override
+  public @Nullable Component translate(final @NotNull TranslatableComponent component, final @NotNull Locale locale) {
+    requireNonNull(component, "component");
+    requireNonNull(locale, "locale");
+    for (final Translator source : this.sources) {
+      final Component translation = source.translate(component, locale);
+      if (translation != null) return translation;
+    }
+    return null;
+  }
+
   @Override
   public @NotNull Stream<? extends ExaminableProperty> examinableProperties() {
     return Stream.of(ExaminableProperty.of("sources", this.sources));

api/src/main/java/net/kyori/adventure/translation/Translator.java

@@ -27,11 +27,13 @@
 import java.util.Locale;
 import java.util.ResourceBundle;
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.TranslatableComponent;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * A message format translator.
+ * A message translator.
  *
  * <p>To see how to create a {@link Translator} with a {@link ResourceBundle}
  * see {@link TranslationRegistry#registerAll(Locale, ResourceBundle, boolean)}</p>
@@ -82,4 +84,16 @@ public interface Translator {
    * @since 4.0.0
    */
   @Nullable MessageFormat translate(final @NotNull String key, final @NotNull Locale locale);
+
+  /**
+   * Gets a translated component from a translatable component and locale.
+   *
+   * @param locale a locale
+   * @param component a translatable component
+   * @return a translated component or {@code null} to use {@link #translate(String, Locale)} instead (if available)
+   * @since 4.13.0
+   */
+  default @Nullable Component translate(final @NotNull TranslatableComponent component, final @NotNull Locale locale) {
+    return null;
+  }
 }

api/src/test/java/net/kyori/adventure/translation/GlobalTranslatorTest.java

@@ -27,11 +27,14 @@
 import java.util.Locale;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.TranslatableComponent;
 import net.kyori.adventure.text.format.NamedTextColor;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -45,16 +48,17 @@ void removeDummySourceBeforeEachTest() {
     GlobalTranslator.translator().removeSource(DummyTranslator.INSTANCE);
   }
 
-  @Test
-  void testRender() {
+  @ParameterizedTest
+  @ValueSource(strings = {"testDummy", "otherDummy"})
+  void testRender(final @NotNull String key) {
     GlobalTranslator.translator().addSource(DummyTranslator.INSTANCE);
     assertEquals(
       Component.text()
         .append(Component.text("Hello "))
         .append(Component.text("kashike", NamedTextColor.DARK_PURPLE))
         .append(Component.text("!"))
         .build(),
-      GlobalTranslator.render(Component.translatable("testDummy", Component.text("kashike", NamedTextColor.DARK_PURPLE)), Locale.US)
+      GlobalTranslator.render(Component.translatable(key, Component.text("kashike", NamedTextColor.DARK_PURPLE)), Locale.US)
     );
     assertEquals(
       Component.entityNBT()
@@ -67,7 +71,7 @@ void testRender() {
             .append(Component.text("!"))
         )
         .build(),
-      GlobalTranslator.render(Component.entityNBT("ignored", "@p").separator(Component.translatable("testDummy", Component.text("you"))), Locale.US)
+      GlobalTranslator.render(Component.entityNBT("ignored", "@p").separator(Component.translatable(key, Component.text("you"))), Locale.US)
     );
   }
 
@@ -89,6 +93,14 @@ void testTranslate() {
     assertNull(GlobalTranslator.translator().translate("testDummy", Locale.US));
     GlobalTranslator.translator().addSource(DummyTranslator.INSTANCE);
     assertEquals(new MessageFormat("Hello {0}!"), GlobalTranslator.translator().translate("testDummy", Locale.US));
+    assertEquals(
+      Component.text()
+        .append(Component.text("Hello "))
+        .append(Component.text("{0}"))
+        .append(Component.text("!"))
+        .build(),
+      GlobalTranslator.translator().translate(Component.translatable("otherDummy"), Locale.US)
+    );
   }
 
   static class DummyTranslator implements Translator {
@@ -105,5 +117,16 @@ static class DummyTranslator implements Translator {
         ? new MessageFormat("Hello {0}!")
         : null;
     }
+
+    @Override
+    public @Nullable Component translate(final @NotNull TranslatableComponent component, final @NotNull Locale locale) {
+      return (component.key().equals("otherDummy") && locale.equals(Locale.US))
+        ? Component.text()
+          .append(Component.text("Hello "))
+          .append(component.args().isEmpty() ? Component.text("{0}") : component.args().get(0))
+          .append(Component.text("!"))
+          .build()
+        : null;
+    }
   }
 }