Skip to content

Commit

Permalink
Merge pull request #868 from NoahvdAa/feat/translatable-fallback
Browse files Browse the repository at this point in the history 
feat(api): add support for translatable component fallbacks (#863)
  • Loading branch information
@zml2008
zml2008 authored Mar 14, 2023
2 parents b815a02 + 1560d46 commit 7a66047
Show file tree
Hide file tree
Showing 11 changed files with 547 additions and 26 deletions.
254 changes: 250 additions & 4 deletions api/src/main/java/net/kyori/adventure/text/Component.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1278,6 +1278,34 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
return translatable(requireNonNull(translatable, "translatable").translationKey(), Style.empty());
}

/**
* Creates a translatable component with a translation key and an optional fallback string.
*
* @param key the translation key
* @param fallback the fallback string
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback) {
return translatable(key, fallback, Style.empty());
}

/**
* Creates a translatable component with a translation key and an optional fallback string.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, Style.empty());
}

/**
* Creates a translatable component with a translation key and styling.
*
Expand All @@ -1288,7 +1316,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
*/
@Contract(value = "_, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @NotNull Style style) {
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, Collections.emptyList());
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, null, Collections.emptyList());
}

/**
Expand All @@ -1304,6 +1332,224 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
return translatable(requireNonNull(translatable, "translatable").translationKey(), style);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param key the translation key
* @param fallback the fallback string
* @param style the style
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull Style style) {
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, fallback, Collections.emptyList());
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param style the style
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull Style style) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, style);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param key the translation key
* @param fallback the fallback string
* @param style the style
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull StyleBuilderApplicable... style) {
return translatable(requireNonNull(key, "key"), fallback, Style.style(style));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param style the style
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull Iterable<StyleBuilderApplicable> style) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, Style.style(style));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param key the translation key
* @param fallback the fallback string
* @param args the translation arguments
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull ComponentLike@NotNull... args) {
return translatable(key, fallback, Style.empty(), args);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param args the translation arguments
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull ComponentLike@NotNull... args) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, args);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param key the translation key
* @param fallback the fallback string
* @param style the style
* @param args the translation arguments
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull Style style, final @NotNull ComponentLike@NotNull... args) {
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, fallback, requireNonNull(args, "args"));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and styling.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param style the style
* @param args the translation arguments
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull Style style, final @NotNull ComponentLike@NotNull... args) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, style, args);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param key the translation key
* @param fallback the fallback string
* @param style the style
* @param args the translation arguments
* @return a translatable component
* @since 4.0.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull Style style, final @NotNull List<? extends ComponentLike> args) {
return TranslatableComponentImpl.create(Collections.emptyList(), style, key, fallback, requireNonNull(args, "args"));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param style the style
* @param args the translation arguments
* @return a translatable component
* @since 4.8.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull Style style, final @NotNull List<? extends ComponentLike> args) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, style, args);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param key the translation key
* @param fallback the fallback string
* @param args the translation arguments
* @param style the style
* @return a translatable component
* @since 4.0.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull List<? extends ComponentLike> args, final @NotNull Iterable<StyleBuilderApplicable> style) {
return TranslatableComponentImpl.create(Collections.emptyList(), Style.style(style), key, fallback, requireNonNull(args, "args"));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param args the translation arguments
* @param style the style
* @return a translatable component
* @since 4.8.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull List<? extends ComponentLike> args, final @NotNull Iterable<StyleBuilderApplicable> style) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, args, style);
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param key the translation key
* @param fallback the fallback string
* @param args the translation arguments
* @param style the style
* @return a translatable component
* @since 4.0.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @Nullable String fallback, final @NotNull List<? extends ComponentLike> args, final @NotNull StyleBuilderApplicable... style) {
return TranslatableComponentImpl.create(Collections.emptyList(), Style.style(style), key, fallback, requireNonNull(args, "args"));
}

/**
* Creates a translatable component with a translation key, optional fallback string, and arguments.
*
* @param translatable the translatable object to get the key from
* @param fallback the fallback string
* @param args the translation arguments
* @param style the style
* @return a translatable component
* @since 4.8.0
* @sinceMinecraft 1.19.4
*/
@Contract(value = "_, _, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull Translatable translatable, final @Nullable String fallback, final @NotNull List<? extends ComponentLike> args, final @NotNull StyleBuilderApplicable... style) {
return translatable(requireNonNull(translatable, "translatable").translationKey(), fallback, args, style);
}

/**
* Creates a translatable component with a translation key, and optional color.
*
Expand Down Expand Up @@ -1423,7 +1669,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @NotNull Style style, final @NotNull ComponentLike@NotNull... args) {
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, requireNonNull(args, "args"));
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, null, requireNonNull(args, "args"));
}

/**
Expand Down Expand Up @@ -1508,7 +1754,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
*/
@Contract(value = "_, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @NotNull List<? extends ComponentLike> args) {
return TranslatableComponentImpl.create(Collections.emptyList(), Style.empty(), key, requireNonNull(args, "args"));
return TranslatableComponentImpl.create(Collections.emptyList(), Style.empty(), key, null, requireNonNull(args, "args"));
}

/**
Expand All @@ -1535,7 +1781,7 @@ public interface Component extends ComponentBuilderApplicable, ComponentLike, Ex
*/
@Contract(value = "_, _, _ -> new", pure = true)
static @NotNull TranslatableComponent translatable(final @NotNull String key, final @NotNull Style style, final @NotNull List<? extends ComponentLike> args) {
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, requireNonNull(args, "args"));
return TranslatableComponentImpl.create(Collections.emptyList(), requireNonNull(style, "style"), key, null, requireNonNull(args, "args"));
}

/**
Expand Down
41 changes: 40 additions & 1 deletion api/src/main/java/net/kyori/adventure/text/TranslatableComponent.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
import net.kyori.examination.ExaminableProperty;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
* A component that can display translated text.
Expand Down Expand Up @@ -119,12 +120,37 @@ public interface TranslatableComponent extends BuildableComponent<TranslatableCo
@Contract(pure = true)
@NotNull TranslatableComponent args(final @NotNull List<? extends ComponentLike> args);

/**
* Gets the translation fallback text for this component.
* The fallback text will be shown when the client doesn't know the
* translation key used in the translatable component.
*
* @return the fallback string
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Nullable String fallback();

/**
* Sets the translation fallback text for this component.
* The fallback text will be shown when the client doesn't know the
* translation key used in the translatable component.
*
* @param fallback the fallback string
* @return a translatable component
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract(pure = true)
@NotNull TranslatableComponent fallback(final @Nullable String fallback);

@Override
default @NotNull Stream<? extends ExaminableProperty> examinableProperties() {
return Stream.concat(
Stream.of(
ExaminableProperty.of("key", this.key()),
ExaminableProperty.of("args", this.args())
ExaminableProperty.of("args", this.args()),
ExaminableProperty.of("fallback", this.fallback())
),
BuildableComponent.super.examinableProperties()
);
Expand Down Expand Up @@ -208,5 +234,18 @@ interface Builder extends ComponentBuilder<TranslatableComponent, Builder> {
*/
@Contract("_ -> this")
@NotNull Builder args(final @NotNull List<? extends ComponentLike> args);

/**
* Sets the translation fallback text.
* The fallback text will be shown when the client doesn't know the
* translation key used in the translatable component.
*
* @param fallback the fallback string
* @return this builder
* @since 4.13.0
* @sinceMinecraft 1.19.4
*/
@Contract("_ -> this")
@NotNull Builder fallback(final @Nullable String fallback);
}
}
Loading

0 comments on commit 7a66047

Please sign in to comment.