Add ComponentBundle#components

Author: NonSwag

src/main/java/net/thenextlvl/i18n/ComponentBundle.java

@@ -303,6 +303,112 @@ public sealed interface ComponentBundle permits ComponentBundleImpl {
     @Contract(value = "_, _, _ -> new", pure = true)
     Component component(@NonNls String translationKey, Locale locale, TagResolver... resolvers);
 
+    /**
+     * Creates an array of {@link Component Components} based on the provided translation key and locale.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * Opposed to {@link #translate(String, Audience)},
+     * this method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the key used to retrieve the localized translation
+     * @param audience       the {@link Audience} to determine the locale used for the translation
+     * @return an array containing one localized {@link Component} per line
+     * @see #translate(String, Audience)
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Audience audience);
+
+    /**
+     * Translates a given translation key into an array of localized {@link Component Components} for the specified
+     * {@link Audience}, with optional arguments for formatting arguments within the translation.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * Opposed to {@link #translate(String, Audience, ComponentLike...)},
+     * this method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the translation key representing the entry to be localized
+     * @param audience       the {@link Audience} to determine the locale used for the translation
+     * @param arguments      optional {@link ComponentLike} arguments used to replace arguments within the translation
+     * @return an array containing one translated {@link Component} per line
+     * @see #translate(String, Audience, ComponentLike...)
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Audience audience, ComponentLike... arguments);
+
+    /**
+     * Translates a given translation key into an array of localized {@link Component Components} for the specified
+     * {@link Audience}, with optional tag resolvers for formatting arguments within the translation.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * This method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the translation key representing the entry to be localized
+     * @param audience       the {@link Audience} to determine the locale used for the translation
+     * @param resolvers      optional {@link TagResolver} arguments used for resolving tags within the translation
+     * @return an array containing one translated {@link Component} per line
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Audience audience, TagResolver... resolvers);
+
+    /**
+     * Creates an array of {@link Component Components} based on the provided translation key and locale.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * Opposed to {@link #translate(String, Locale)},
+     * this method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the key used to retrieve the localized translation
+     * @param locale         the locale that determines the language and formatting of the translation
+     * @return an array containing one localized {@link Component} per line
+     * @see #translate(String, Locale)
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Locale locale);
+
+    /**
+     * Translates a given translation key into an array of localized {@link Component Components},
+     * with optional arguments for formatting arguments within the translation.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * Opposed to {@link #translate(String, Locale, ComponentLike...)},
+     * this method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the translation key representing the entry to be localized
+     * @param locale         the locale that determines the language and formatting of the translation
+     * @param arguments      optional {@link ComponentLike} arguments used to replace arguments within the translation
+     * @return an array containing one translated {@link Component} per line
+     * @see #translate(String, Locale, ComponentLike...)
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Locale locale, ComponentLike... arguments);
+
+    /**
+     * Translates a given translation key into an array of localized {@link Component Components},
+     * with optional tag resolvers for formatting arguments within the translation.
+     * Each line separated by {@code <br>}, {@code <newline>}, or {@code \n} is returned as a separate component.
+     * <p>
+     * This method does not return null if the translation could not be resolved.
+     * Instead, it returns an array containing a red text component with the translation key.
+     *
+     * @param translationKey the translation key representing the entry to be localized
+     * @param locale         the locale that determines the language and formatting of the translation
+     * @param resolvers      optional {@link TagResolver} arguments used for resolving tags within the translation
+     * @return an array containing one translated {@link Component} per line
+     * @since 1.3.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Component[] components(@NonNls String translationKey, Locale locale, TagResolver... resolvers);
+
     /**
      * A builder interface for constructing a {@link ComponentBundle}.
      */

src/main/java/net/thenextlvl/i18n/ComponentBundleImpl.java

@@ -29,6 +29,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Locale;
@@ -38,11 +39,13 @@
 final class ComponentBundleImpl implements ComponentBundle {
     private static final Logger LOGGER = LoggerFactory.getLogger("i18n");
     private final Locale fallback;
+    private final MiniMessage miniMessage;
     private final Map<String, String> placeholders;
     private final MiniMessageTranslationStore translator;
 
-    private ComponentBundleImpl(Locale fallback, Map<String, String> placeholders, MiniMessageTranslationStore translator) {
+    private ComponentBundleImpl(final Locale fallback, final Map<String, String> placeholders, final MiniMessageTranslationStore translator, final MiniMessage miniMessage) {
         this.fallback = fallback;
+        this.miniMessage = miniMessage;
         this.placeholders = Map.copyOf(placeholders);
         this.translator = translator;
     }
@@ -177,6 +180,39 @@ public Component component(final String translationKey, final Locale locale, fin
         return component(translationKey, locale, Argument.tagResolver(resolvers));
     }
 
+    @Override
+    public Component[] components(final String translationKey, final Audience audience) {
+        return components(translationKey, audience, new Component[0]);
+    }
+
+    @Override
+    public Component[] components(final String translationKey, final Audience audience, final ComponentLike... arguments) {
+        return components(translationKey, audience.get(Identity.LOCALE).orElse(fallback), arguments);
+    }
+
+    @Override
+    public Component[] components(final String translationKey, final Audience audience, final TagResolver... resolvers) {
+        return components(translationKey, audience, Argument.tagResolver(resolvers));
+    }
+
+    @Override
+    public Component[] components(final String translationKey, final Locale locale) {
+        return components(translationKey, locale, new Component[0]);
+    }
+
+    @Override
+    public Component[] components(final String translationKey, final Locale locale, final ComponentLike... arguments) {
+        final var serialized = miniMessage.serialize(component(translationKey, locale, arguments));
+        return Arrays.stream(serialized.split("<br>|<newline>|\n", -1))
+                .map(miniMessage::deserialize)
+                .toArray(Component[]::new);
+    }
+
+    @Override
+    public Component[] components(final String translationKey, final Locale locale, final TagResolver... resolvers) {
+        return components(translationKey, locale, Argument.tagResolver(resolvers));
+    }
+
     public static final class Builder implements ComponentBundle.Builder {
         private final Map<String, Locale> files = new HashMap<>();
         private final Map<String, String> placeholders = new HashMap<>();

src/test/java/module-info.java

@@ -0,0 +1,31 @@
+package net.thenextlvl.i18n.test;
+
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.format.NamedTextColor;
+import net.kyori.adventure.text.format.TextDecoration;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+import java.util.Locale;
+
+class ComponentsTest extends BaseTest {
+    @Override
+    public Key key() {
+        return Key.key("test", "components");
+    }
+
+    @Test
+    void lineBreaksProduceSeparateComponents() {
+        final var lines = bundle.components("lines", Locale.US);
+
+        Assertions.assertArrayEquals(new Component[]{
+                Component.text("first").decorate(TextDecoration.ITALIC),
+                Component.text("second").decoration(TextDecoration.ITALIC, false),
+                Component.text("third").decoration(TextDecoration.ITALIC, false),
+                Component.text("fourth"),
+                Component.empty(),
+                Component.text("hello", NamedTextColor.RED)
+        }, lines);
+    }
+}

src/test/java/net/thenextlvl/i18n/test/ComponentsTest.java

@@ -0,0 +1,4 @@
+@NullMarked
+package net.thenextlvl.i18n.test;
+
+import org.jspecify.annotations.NullMarked;

src/test/java/net/thenextlvl/i18n/test/package-info.java

@@ -3,4 +3,5 @@ hello=Hey
 resolved=Hello <world>!
 prefix=PREFIX
 prefix_test=<prefix> TEST
-colored=<rainbow>So many colors</rainbow>
+colored=<rainbow>So many colors</rainbow>
+lines=<i>first<br><!i>second</!i><newline><!i>third</!i>\nfourth\n\n<red>hello