Add methods to get translation keys

Co-authored-by: MeFisto94 <MeFisto94@users.noreply.github.com>

paper-api/src/main/java/org/bukkit/Difficulty.java

@@ -7,7 +7,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents the various difficulty levels that are available.
  */
-public enum Difficulty {
+public enum Difficulty implements net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
     /**
      * Players regain health over time, hostile mobs don't spawn, the hunger
      * bar does not deplete.
@@ -51,6 +51,12 @@ public enum Difficulty {
         return value;
     }
 
+    // Paper start
+    @Override
+    public @org.jetbrains.annotations.NotNull String translationKey() {
+        return "options.difficulty." + this.name().toLowerCase(java.util.Locale.ENGLISH);
+    }
+    // Paper end
     /**
      * Gets the Difficulty represented by the specified value
      *

paper-api/src/main/java/org/bukkit/FireworkEffect.java

@@ -18,28 +18,44 @@ public final class FireworkEffect implements ConfigurationSerializable {
     /**
      * The type or shape of the effect.
      */
-    public enum Type {
+    public enum Type implements net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
         /**
          * A small ball effect.
          */
-        BALL,
+        BALL("small_ball"), // Paper - add name
         /**
          * A large ball effect.
          */
-        BALL_LARGE,
+        BALL_LARGE("large_ball"), // Paper - add name
         /**
          * A star-shaped effect.
          */
-        STAR,
+        STAR("star"), // Paper - add name
         /**
          * A burst effect.
          */
-        BURST,
+        BURST("burst"), // Paper - add name
         /**
          * A creeper-face effect.
          */
-        CREEPER,
+        CREEPER("creeper"), // Paper - add name
         ;
+        // Paper start
+        /**
+         * The name map.
+         */
+        public static final net.kyori.adventure.util.Index<String, org.bukkit.FireworkEffect.Type> NAMES = net.kyori.adventure.util.Index.create(Type.class, type -> type.name);
+        private final String name;
+
+        Type(final String name) {
+            this.name = name;
+        }
+
+        @Override
+        public @NotNull String translationKey() {
+            return "item.minecraft.firework_star.shape." + this.name;
+        }
+        // Paper end
     }
 
     /**

paper-api/src/main/java/org/bukkit/GameMode.java

@@ -9,7 +9,7 @@ import org.jetbrains.annotations.Nullable;
  * Represents the various type of game modes that {@link HumanEntity}s may
  * have
  */
-public enum GameMode {
+public enum GameMode implements net.kyori.adventure.translation.Translatable { // Paper - implement Translatable
     /**
      * Creative mode may fly, build instantly, become invulnerable and create
      * free items.
@@ -35,9 +35,18 @@ public enum GameMode {
 
     private final int value;
     private static final Map<Integer, GameMode> BY_ID = Maps.newHashMap();
+    // Paper start - translation keys
+    private final String translationKey;
+
+    @Override
+    public @org.jetbrains.annotations.NotNull String translationKey() {
+        return this.translationKey;
+    }
+    // Paper end
 
     private GameMode(final int value) {
         this.value = value;
+        this.translationKey = "gameMode." +  this.name().toLowerCase(java.util.Locale.ENGLISH); // Paper
     }
 
     /**

paper-api/src/main/java/org/bukkit/GameRule.java

@@ -15,7 +15,7 @@ import org.jetbrains.annotations.Nullable;
  *
  * @param <T> type of rule (Boolean or Integer)
  */
-public final class GameRule<T> {
+public final class GameRule<T> implements net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
 
     private static Map<String, GameRule<?>> gameRules = new HashMap<>();
     // Boolean rules
@@ -366,4 +366,11 @@ public final class GameRule<T> {
     public static GameRule<?>[] values() {
         return gameRules.values().toArray(new GameRule<?>[gameRules.size()]);
     }
+
+    // Paper start
+    @Override
+    public @NotNull String translationKey() {
+        return "gamerule." + this.name;
+    }
+    // Paper end
 }

paper-api/src/main/java/org/bukkit/Material.java

@@ -136,7 +136,7 @@ import org.jetbrains.annotations.Nullable;
  * An enum of all material IDs accepted by the official server and client
  */
 @SuppressWarnings({"DeprecatedIsStillUsed", "deprecation"}) // Paper
-public enum Material implements Keyed, Translatable {
+public enum Material implements Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper
     //<editor-fold desc="Materials" defaultstate="collapsed">
     AIR(9648, 0),
     STONE(22948),
@@ -4834,6 +4834,17 @@ public enum Material implements Keyed, Translatable {
     }
     // Paper end
 
+    // Paper start - add Translatable
+    @Override
+    public @NotNull String translationKey() {
+        if (this.isItem()) {
+            return java.util.Objects.requireNonNull(this.asItemType()).translationKey();
+        } else {
+            return java.util.Objects.requireNonNull(this.asBlockType()).translationKey();
+        }
+    }
+    // Paper end - add Translatable
+
     /**
      * Do not use for any reason.
      *
@@ -5583,9 +5594,11 @@ public enum Material implements Keyed, Translatable {
      * material
      * @see #getBlockTranslationKey()
      * @see #getItemTranslationKey()
+     * @deprecated use {@link #translationKey()}
      */
     @Override
     @NotNull
+    @Deprecated(forRemoval = true) // Paper
     public String getTranslationKey() {
         if (this.isItem()) {
             return asItemType().getTranslationKey();

paper-api/src/main/java/org/bukkit/MusicInstrument.java

@@ -6,7 +6,7 @@ import java.util.Collections;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public abstract class MusicInstrument implements Keyed {
+public abstract class MusicInstrument implements Keyed, net.kyori.adventure.translation.Translatable { // Paper - translation keys
 
     public static final MusicInstrument PONDER_GOAT_HORN = getInstrument("ponder_goat_horn");
     public static final MusicInstrument SING_GOAT_HORN = getInstrument("sing_goat_horn");
@@ -46,4 +46,14 @@ public abstract class MusicInstrument implements Keyed {
     private static MusicInstrument getInstrument(@NotNull String key) {
         return Registry.INSTRUMENT.getOrThrow(NamespacedKey.minecraft(key));
     }
+
+    // Paper start - mark translation key as deprecated
+    /**
+     * @deprecated this method assumes that the instrument description
+     * always be a translatable component which is not guaranteed.
+     */
+    @Override
+    @Deprecated(forRemoval = true)
+    public abstract @NotNull String translationKey();
+    // Paper end - mark translation key as deprecated
 }

paper-api/src/main/java/org/bukkit/Translatable.java

@@ -5,14 +5,18 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Represents an object with a text representation that can be translated by the
  * Minecraft client.
+ * @deprecated use {@link net.kyori.adventure.translation.Translatable}
  */
+@Deprecated(forRemoval = true) // Paper
 public interface Translatable {
 
     /**
      * Get the translation key, suitable for use in a translation component.
      *
      * @return the translation key
+     * @deprecated look for a {@code translationKey()} method instead
      */
     @NotNull
+    @Deprecated(forRemoval = true) // Paper
     String getTranslationKey();
 }

paper-api/src/main/java/org/bukkit/attribute/Attribute.java

@@ -14,7 +14,7 @@ import org.jetbrains.annotations.NotNull;
 /**
  * Types of attributes which may be present on an {@link Attributable}.
  */
-public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable {
+public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
 
     /**
      * Maximum health of an Entity.

paper-api/src/main/java/org/bukkit/block/Biome.java

@@ -20,7 +20,7 @@ import org.jetbrains.annotations.NotNull;
  * There may be additional biomes present in the server, for example from a {@link DataPack}
  * which can be accessed via {@link Registry#BIOME}.
  */
-public interface Biome extends OldEnum<Biome>, Keyed {
+public interface Biome extends OldEnum<Biome>, Keyed, net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
 
     Biome OCEAN = getBiome("ocean");
     Biome PLAINS = getBiome("plains");
@@ -127,4 +127,11 @@ public interface Biome extends OldEnum<Biome>, Keyed {
     static Biome[] values() {
         return Lists.newArrayList(Registry.BIOME).toArray(new Biome[0]);
     }
+
+    // Paper start
+    @Override
+    default @NotNull String translationKey() {
+        return "biome.minecraft." + this.getKey().getKey();
+    }
+    // Paper end
 }

paper-api/src/main/java/org/bukkit/block/Block.java

@@ -32,7 +32,7 @@ import org.jetbrains.annotations.Nullable;
  * (i.e. lighting and power) may not be able to be safely accessed during world
  * generation when used in cases like BlockPhysicsEvent!!!!
  */
-public interface Block extends Metadatable, Translatable {
+public interface Block extends Metadatable, Translatable, net.kyori.adventure.translation.Translatable { // Paper - translatable
 
     /**
      * Gets the metadata for this block
@@ -682,5 +682,12 @@ public interface Block extends Metadatable, Translatable {
      * @return the sound group for this block
      */
     @NotNull org.bukkit.SoundGroup getBlockSoundGroup();
+
+    /**
+     * @deprecated use {@link #translationKey()}
+     */
+    @NotNull
+    @Deprecated(forRemoval = true)
+    String getTranslationKey();
     // Paper end
 }

paper-api/src/main/java/org/bukkit/block/BlockType.java

@@ -129,7 +129,7 @@ import org.jetbrains.annotations.Nullable;
  * changes may occur. Do not use this API in plugins.
  */
 @ApiStatus.Internal
-public interface BlockType extends Keyed, Translatable {
+public interface BlockType extends Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - add translatable
 
     /**
      * Typed represents a subtype of {@link BlockType}s that have a known block
@@ -3616,4 +3616,13 @@ public interface BlockType extends Keyed, Translatable {
     @Nullable
     @Deprecated(since = "1.20.6")
     Material asMaterial();
+
+    // Paper start - add Translatable
+    /**
+     * @deprecated use {@link #translationKey()} and {@link net.kyori.adventure.text.Component#translatable(net.kyori.adventure.translation.Translatable)}
+     */
+    @Deprecated(forRemoval = true)
+    @Override
+    @NotNull String getTranslationKey();
+    // Paper end - add Translatable
 }

paper-api/src/main/java/org/bukkit/enchantments/Enchantment.java

@@ -14,7 +14,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * The various type of enchantments that may be added to armour or weapons
  */
-public abstract class Enchantment implements Keyed, Translatable {
+public abstract class Enchantment implements Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
     /**
      * Provides protection against environmental damage
      */
@@ -324,6 +324,16 @@ public abstract class Enchantment implements Keyed, Translatable {
     public abstract net.kyori.adventure.text.@NotNull Component displayName(int level);
     // Paper end
 
+    // Paper start - mark translation key as deprecated
+    /**
+     * @deprecated this method assumes that the enchantments description
+     * always be a translatable component which is not guaranteed.
+     */
+    @Override
+    @Deprecated(forRemoval = true)
+    public abstract @NotNull String translationKey();
+    // Paper end - mark translation key as deprecated
+
     /**
      * Gets the Enchantment at the specified key
      *

paper-api/src/main/java/org/bukkit/enchantments/EnchantmentWrapper.java

@@ -26,5 +26,10 @@ public abstract class EnchantmentWrapper extends Enchantment {
     public net.kyori.adventure.text.Component displayName(int level) {
         return getEnchantment().displayName(level);
     }
+
+    @Override
+    public @NotNull String translationKey() {
+        return getEnchantment().translationKey();
+    }
     // Paper end
 }

paper-api/src/main/java/org/bukkit/entity/EntityType.java

@@ -43,7 +43,7 @@ import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public enum EntityType implements Keyed, Translatable {
+public enum EntityType implements Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - translatable
 
     // These strings MUST match the strings in nms.EntityTypes and are case sensitive.
     /**
@@ -463,10 +463,22 @@ public enum EntityType implements Keyed, Translatable {
 
     @Override
     @NotNull
+    @Deprecated(forRemoval = true) // Paper
     public String getTranslationKey() {
         return Bukkit.getUnsafe().getTranslationKey(this);
     }
 
+    // Paper start
+    /**
+     * @throws IllegalArgumentException if the entity does not have a translation key (is probably a custom entity)
+     */
+    @Override
+    public @NotNull String translationKey() {
+        Preconditions.checkArgument(this != UNKNOWN, "UNKNOWN entities do not have translation keys");
+        return org.bukkit.Bukkit.getUnsafe().getTranslationKey(this);
+    }
+    // Paper end
+
     /**
      * Gets if this EntityType is enabled by feature in a world.
      *

paper-api/src/main/java/org/bukkit/entity/Villager.java

@@ -181,7 +181,7 @@ public interface Villager extends AbstractVillager {
      * Represents the various different Villager professions there may be.
      * Villagers have different trading options depending on their profession,
      */
-    interface Profession extends OldEnum<Profession>, Keyed {
+    interface Profession extends OldEnum<Profession>, Keyed, net.kyori.adventure.translation.Translatable {
 
         Profession NONE = getProfession("none");
         /**
@@ -282,6 +282,13 @@ public interface Villager extends AbstractVillager {
         static Profession[] values() {
             return Lists.newArrayList(Registry.VILLAGER_PROFESSION).toArray(new Profession[0]);
         }
+
+        // Paper start
+        @Override
+        default @NotNull String translationKey() {
+            return "entity.minecraft.villager." + this.getKey().getKey();
+        }
+        // Paper end
     }
 
     // Paper start - Add villager reputation API

paper-api/src/main/java/org/bukkit/inventory/CreativeCategory.java

@@ -3,51 +3,64 @@ package org.bukkit.inventory;
 /**
  * Represents a category in the creative inventory.
  */
-public enum CreativeCategory {
+public enum CreativeCategory implements net.kyori.adventure.translation.Translatable { // Paper
 
     /**
      * An assortment of building blocks including dirt, bricks, planks, ores
      * slabs, etc.
      */
-    BUILDING_BLOCKS,
+    BUILDING_BLOCKS("buildingBlocks"), // Paper
     /**
      * Blocks and items typically used for decorative purposes including
      * candles, saplings, flora, fauna, fences, walls, carpets, etc.
      */
-    DECORATIONS,
+    DECORATIONS("decorations"), // Paper
     /**
      * Blocks used and associated with redstone contraptions including buttons,
      * levers, pressure plates, redstone components, pistons, etc.
      */
-    REDSTONE,
+    REDSTONE("redstone"), // Paper
     /**
      * Items pertaining to transportation including minecarts, rails, boats,
      * elytra, etc.
      */
-    TRANSPORTATION,
+    TRANSPORTATION("transportation"), // Paper
     /**
      * Miscellaneous items and blocks that do not fit into other categories
      * including gems, dyes, spawn eggs, discs, banner patterns, etc.
      */
-    MISC,
+    MISC("misc"), // Paper
     /**
      * Food items consumable by the player including meats, berries, edible
      * drops from creatures, etc.
      */
-    FOOD,
+    FOOD("food"), // Paper
     /**
      * Equipment items meant for general utility including pickaxes, axes, hoes,
      * flint and steel, and useful enchantment books for said tools.
      */
-    TOOLS,
+    TOOLS("tools"), // Paper
     /**
      * Equipment items meant for combat including armor, swords, bows, tipped
      * arrows, and useful enchantment books for said equipment.
      */
-    COMBAT,
+    COMBAT("combat"), // Paper
     /**
      * All items related to brewing and potions including all types of potions,
      * their variants, and ingredients to brew them.
      */
-    BREWING;
+    BREWING("brewing"); // Paper
+    // Paper start
+    private final String translationKey;
+
+    CreativeCategory(String translationKey) {
+        this.translationKey = "itemGroup." + translationKey;
+    }
+
+    @Override
+    public @org.jetbrains.annotations.NotNull String translationKey() {
+        return this.translationKey;
+    }
+    // Paper end
+
 }

paper-api/src/main/java/org/bukkit/inventory/ItemStack.java

@@ -27,7 +27,7 @@ import org.jetbrains.annotations.Nullable;
  * use this class to encapsulate Materials for which {@link Material#isItem()}
  * returns false.</b>
  */
-public class ItemStack implements Cloneable, ConfigurationSerializable, Translatable, net.kyori.adventure.text.event.HoverEventSource<net.kyori.adventure.text.event.HoverEvent.ShowItem> { // Paper
+public class ItemStack implements Cloneable, ConfigurationSerializable, Translatable, net.kyori.adventure.text.event.HoverEventSource<net.kyori.adventure.text.event.HoverEvent.ShowItem>, net.kyori.adventure.translation.Translatable { // Paper
     private Material type = Material.AIR;
     private int amount = 0;
     private MaterialData data = null;
@@ -628,6 +628,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
 
     @Override
     @NotNull
+    @Deprecated(forRemoval = true) // Paper
     public String getTranslationKey() {
         return Bukkit.getUnsafe().getTranslationKey(this);
     }
@@ -982,5 +983,16 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
         ItemMeta itemMeta = getItemMeta();
         return itemMeta != null && itemMeta.hasItemFlag(flag);
     }
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * This is not the same as getting the translation key
+     * for the material of this itemstack.
+     */
+    @Override
+    public @NotNull String translationKey() {
+        return Bukkit.getUnsafe().getTranslationKey(this);
+    }
     // Paper end
 }

paper-api/src/main/java/org/bukkit/inventory/ItemType.java

@@ -47,7 +47,7 @@ import org.jetbrains.annotations.Nullable;
  * changes may occur. Do not use this API in plugins.
  */
 @ApiStatus.Internal
-public interface ItemType extends Keyed, Translatable {
+public interface ItemType extends Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - add Translatable
 
     /**
      * Typed represents a subtype of {@link ItemType}s that have a known item meta type
@@ -2409,4 +2409,13 @@ public interface ItemType extends Keyed, Translatable {
     @Nullable
     @Deprecated(since = "1.20.6")
     Material asMaterial();
+
+    // Paper start - add Translatable
+    /**
+     * @deprecated use {@link #translationKey()} and {@link net.kyori.adventure.text.Component#translatable(net.kyori.adventure.translation.Translatable)}
+     */
+    @Deprecated(forRemoval = true)
+    @Override
+    @NotNull String getTranslationKey();
+    // Paper end - add Translatable
 }