Prefer using Locale instead of DiscordLocale, and deprecate such usages (#260)

Author: freya022

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/LocalizableAction.kt

@@ -1,6 +1,5 @@
 package io.github.freya022.botcommands.api.localization
 
-import io.github.freya022.botcommands.api.core.config.BLocalizationConfig
 import io.github.freya022.botcommands.api.core.messages.BotCommandsMessages
 import io.github.freya022.botcommands.api.core.messages.BotCommandsMessagesFactory
 import io.github.freya022.botcommands.api.localization.context.LocalizationContext
@@ -102,12 +101,15 @@ interface LocalizableAction {
      * - No [registered bundle][BLocalizationConfig.responseBundles] containing the path could be found
      * - If the template requires an argument that was not passed to [entries]
      */
+    @Deprecated("Pass a Locale instead")
     fun getLocalizedMessage(locale: DiscordLocale, localizationPath: String, vararg entries: Localization.Entry): String =
         getLocalizedMessage(locale.toLocale(), localizationPath, *entries)
 }
 
 fun LocalizableAction.getLocalizedMessage(locale: Locale, localizationPath: String, vararg entries: PairEntry): String =
     getLocalizedMessage(locale, localizationPath, *entries.mapToEntries())
 
+@Suppress("DEPRECATION")
+@Deprecated("Pass a Locale instead")
 fun LocalizableAction.getLocalizedMessage(locale: DiscordLocale, localizationPath: String, vararg entries: PairEntry): String =
-    getLocalizedMessage(locale, localizationPath, *entries.mapToEntries())
+    getLocalizedMessage(locale, localizationPath, *entries.mapToEntries())

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/context/AppLocalizationContext.kt

@@ -1,3 +1,5 @@
+@file:Suppress("DEPRECATION")
+
 package io.github.freya022.botcommands.api.localization.context
 
 import io.github.freya022.botcommands.api.localization.Localization
@@ -6,6 +8,7 @@ import io.github.freya022.botcommands.api.localization.interaction.GuildLocalePr
 import io.github.freya022.botcommands.api.localization.interaction.UserLocaleProvider
 import net.dv8tion.jda.api.interactions.DiscordLocale
 import net.dv8tion.jda.api.interactions.Interaction
+import java.util.*
 import javax.annotation.CheckReturnValue
 
 /**
@@ -40,11 +43,15 @@ interface AppLocalizationContext : TextLocalizationContext {
      * @see withUserLocale
      */
     //User locale is always provided in interactions
-    val userLocale: DiscordLocale
+    val userLocale: Locale
 
+    @Deprecated("Use the Locale overload")
     @CheckReturnValue
     override fun withGuildLocale(guildLocale: DiscordLocale?): AppLocalizationContext
 
+    @CheckReturnValue
+    override fun withGuildLocale(guildLocale: Locale?): AppLocalizationContext
+
     @CheckReturnValue
     override fun withBundle(localizationBundle: String): AppLocalizationContext
 

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/context/LocalizationContext.kt

@@ -1,3 +1,5 @@
+@file:Suppress("DEPRECATION")
+
 package io.github.freya022.botcommands.api.localization.context
 
 import io.github.freya022.botcommands.api.commands.text.BaseCommandEvent
@@ -26,6 +28,7 @@ import net.dv8tion.jda.api.requests.restaction.WebhookMessageCreateAction
 import net.dv8tion.jda.api.requests.restaction.WebhookMessageEditAction
 import net.dv8tion.jda.api.requests.restaction.interactions.MessageEditCallbackAction
 import net.dv8tion.jda.api.requests.restaction.interactions.ReplyCallbackAction
+import java.util.*
 import javax.annotation.CheckReturnValue
 
 typealias PairEntry = Pair<String, Any>
@@ -45,9 +48,9 @@ interface LocalizationContext {
      * The locale used when no locale is specified, the best locale is picked in this order:
      * - The [user locale][Interaction.getUserLocale]
      * - The [guild locale][Guild.getLocale]
-     * - The default locale ([DiscordLocale.ENGLISH_US])
+     * - The default locale ([Locale.US])
      */
-    val effectiveLocale: DiscordLocale
+    val effectiveLocale: Locale
 
     /**
      * Returns the localization bundle of the current context.
@@ -74,17 +77,35 @@ interface LocalizationContext {
      *
      * @param guildLocale The guild locale to use, or `null` to remove it
      */
+    @Deprecated("Use the Locale overload")
     @CheckReturnValue
     fun withGuildLocale(guildLocale: DiscordLocale?): TextLocalizationContext
 
+    /**
+     * Returns a new [TextLocalizationContext] with the specified guild locale.
+     *
+     * @param guildLocale The guild locale to use, or `null` to remove it
+     */
+    @CheckReturnValue
+    fun withGuildLocale(guildLocale: Locale?): TextLocalizationContext
+
     /**
      * Returns a new [AppLocalizationContext] with the specified user locale.
      *
      * @param userLocale The user locale to use, or `null` to remove it
      */
+    @Deprecated("Use the Locale overload")
     @CheckReturnValue
     fun withUserLocale(userLocale: DiscordLocale?): AppLocalizationContext
 
+    /**
+     * Returns a new [AppLocalizationContext] with the specified user locale.
+     *
+     * @param userLocale The user locale to use, or `null` to remove it
+     */
+    @CheckReturnValue
+    fun withUserLocale(userLocale: Locale?): AppLocalizationContext
+
     /**
      * Returns a new localization context with the specified localization bundle.
      *
@@ -118,7 +139,19 @@ interface LocalizationContext {
      * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
      * @param entries          The entries to fill the template with
      */
+    @Deprecated("Use the Locale overload")
     fun localize(locale: DiscordLocale, localizationPath: String, vararg entries: Localization.Entry): String
+        = localize(locale.toLocale(), localizationPath, *entries)
+
+    /**
+     * Localizes the provided path, with the provided locale.
+     *
+     * @param locale           The [Locale] to use when fetching the localization bundle
+     * @param localizationPath The path of the localization template,
+     * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
+     * @param entries          The entries to fill the template with
+     */
+    fun localize(locale: Locale, localizationPath: String, vararg entries: Localization.Entry): String
 
     /**
      * Localizes the provided path, with the provided locale, or returns `null` if the path does not exist.
@@ -128,7 +161,19 @@ interface LocalizationContext {
      * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
      * @param entries          The entries to fill the template with
      */
+    @Deprecated("Use the Locale overload")
     fun localizeOrNull(locale: DiscordLocale, localizationPath: String, vararg entries: Localization.Entry): String?
+        = localizeOrNull(locale.toLocale(), localizationPath, *entries)
+
+    /**
+     * Localizes the provided path, with the provided locale, or returns `null` if the path does not exist.
+     *
+     * @param locale           The [Locale] to use when fetching the localization bundle
+     * @param localizationPath The path of the localization template,
+     * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
+     * @param entries          The entries to fill the template with
+     */
+    fun localizeOrNull(locale: Locale, localizationPath: String, vararg entries: Localization.Entry): String?
 
     /**
      * Localizes the provided path, with the [best locale][effectiveLocale] available.
@@ -153,8 +198,8 @@ interface LocalizationContext {
 
     class Builder internal constructor(private val localizationService: LocalizationService, private val bundleName: String) {
         private var prefix: String? = null
-        private var guildLocaleProvider: Lazy<DiscordLocale>? = null
-        private var userLocaleProvider: Lazy<DiscordLocale>? = null
+        private var guildLocaleProvider: Lazy<Locale>? = null
+        private var userLocaleProvider: Lazy<Locale>? = null
 
         /**
          * Sets the prefix of the context.
@@ -170,24 +215,24 @@ interface LocalizationContext {
          * Sets the guild locale to be provided by the passed [GuildLocaleProvider].
          */
         fun setGuildLocaleProvider(provider: GuildLocaleProvider, interaction: Interaction): Builder {
-            return setGuildLocaleProvider(lazy { provider.getDiscordLocale(interaction) })
+            return setGuildLocaleProvider(lazy { provider.getLocale(interaction) })
         }
 
         /**
          * Sets the guild locale to be provided by the passed [TextCommandLocaleProvider].
          */
         fun setGuildLocaleProvider(provider: TextCommandLocaleProvider, event: MessageReceivedEvent): Builder {
-            return setGuildLocaleProvider(lazy { provider.getDiscordLocale(event) })
+            return setGuildLocaleProvider(lazy { provider.getLocale(event) })
         }
 
         /**
          * Sets the guild locale to the provided one.
          */
-        fun setGuildLocale(locale: DiscordLocale): Builder {
+        fun setGuildLocale(locale: Locale): Builder {
             return setGuildLocaleProvider(lazyOf(locale))
         }
 
-        private fun setGuildLocaleProvider(provider: Lazy<DiscordLocale>): Builder {
+        private fun setGuildLocaleProvider(provider: Lazy<Locale>): Builder {
             this.guildLocaleProvider = provider
             return this
         }
@@ -196,17 +241,17 @@ interface LocalizationContext {
          * Sets the user locale to be provided by the passed [UserLocaleProvider].
          */
         fun setUserLocaleProvider(provider: UserLocaleProvider, interaction: Interaction): Builder {
-            return setUserLocaleProvider(lazy { provider.getDiscordLocale(interaction) })
+            return setUserLocaleProvider(lazy { provider.getLocale(interaction) })
         }
 
         /**
          * Sets the user locale to the provided one.
          */
-        fun setUserLocale(locale: DiscordLocale): Builder {
+        fun setUserLocale(locale: Locale): Builder {
             return setUserLocaleProvider(lazyOf(locale))
         }
 
-        private fun setUserLocaleProvider(provider: Lazy<DiscordLocale>): Builder {
+        private fun setUserLocaleProvider(provider: Lazy<Locale>): Builder {
             this.userLocaleProvider = provider
             return this
         }
@@ -273,8 +318,8 @@ interface LocalizationContext {
                 context.getService<LocalizationService>(),
                 localizationBundle,
                 localizationPrefix,
-                lazy { context.getService<GuildLocaleProvider>().getDiscordLocale(event) },
-                lazy { context.getService<UserLocaleProvider>().getDiscordLocale(event) },
+                lazy { context.getService<GuildLocaleProvider>().getLocale(event) },
+                lazy { context.getService<UserLocaleProvider>().getLocale(event) },
             )
         }
 
@@ -292,7 +337,7 @@ interface LocalizationContext {
                 context.getService<LocalizationService>(),
                 localizationBundle,
                 localizationPrefix,
-                lazy { context.getService<TextCommandLocaleProvider>().getDiscordLocale(event) },
+                lazy { context.getService<TextCommandLocaleProvider>().getLocale(event) },
                 userLocale?.toProvider(),
             )
         }
@@ -315,7 +360,7 @@ interface LocalizationContext {
             return Builder(localizationService, localizationBundle)
         }
 
-        private fun DiscordLocale.toProvider(): Lazy<DiscordLocale> = lazyOf(this)
+        private fun DiscordLocale.toProvider(): Lazy<Locale> = lazyOf(this.toLocale())
     }
 }
 
@@ -331,9 +376,21 @@ internal fun Array<out PairEntry>.mapToEntries() = Array(this.size) {
  * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
  * @param entries          The entries to fill the template with
  */
+@Deprecated("Use the Locale overload")
 fun LocalizationContext.localize(locale: DiscordLocale, localizationPath: String, vararg entries: PairEntry): String =
     localize(locale, localizationPath, *entries.mapToEntries())
 
+/**
+ * Localizes the provided path, with the provided locale.
+ *
+ * @param locale           The [Locale] to use when fetching the localization bundle
+ * @param localizationPath The path of the localization template,
+ * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
+ * @param entries          The entries to fill the template with
+ */
+fun LocalizationContext.localize(locale: Locale, localizationPath: String, vararg entries: PairEntry): String =
+    localize(locale, localizationPath, *entries.mapToEntries())
+
 /**
  * Localizes the provided path, with the provided locale, or returns `null` if the path does not exist.
  *
@@ -342,9 +399,21 @@ fun LocalizationContext.localize(locale: DiscordLocale, localizationPath: String
  * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
  * @param entries          The entries to fill the template with
  */
+@Deprecated("Use the Locale overload")
 fun LocalizationContext.localizeOrNull(locale: DiscordLocale, localizationPath: String, vararg entries: PairEntry): String? =
     localizeOrNull(locale, localizationPath, *entries.mapToEntries())
 
+/**
+ * Localizes the provided path, with the provided locale, or returns `null` if the path does not exist.
+ *
+ * @param locale           The [Locale] to use when fetching the localization bundle
+ * @param localizationPath The path of the localization template,
+ * prefixed with [localizationPrefix][LocalizationContext.localizationPrefix] unless starting with `/`
+ * @param entries          The entries to fill the template with
+ */
+fun LocalizationContext.localizeOrNull(locale: Locale, localizationPath: String, vararg entries: PairEntry): String? =
+    localizeOrNull(locale, localizationPath, *entries.mapToEntries())
+
 /**
  * Localizes the provided path, with the [best locale][LocalizationContext.effectiveLocale] available.
  *

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/context/TextLocalizationContext.kt

@@ -5,8 +5,8 @@ import io.github.freya022.botcommands.api.localization.annotations.LocalizationB
 import io.github.freya022.botcommands.api.localization.interaction.GuildLocaleProvider
 import net.dv8tion.jda.api.entities.Guild
 import net.dv8tion.jda.api.events.message.MessageReceivedEvent
-import net.dv8tion.jda.api.interactions.DiscordLocale
 import net.dv8tion.jda.api.interactions.Interaction
+import java.util.*
 import javax.annotation.CheckReturnValue
 
 /**
@@ -43,18 +43,18 @@ interface TextLocalizationContext : LocalizationContext {
     fun hasGuildLocale(): Boolean
 
     /**
-     * Returns the [DiscordLocale] of the guild.
+     * Returns the [Locale] of the guild.
      *
      * The locale can either come from the [GuildLocaleProvider] or from a [withGuildLocale].
      *
-     * @return the [DiscordLocale] of the guild
+     * @return the [Locale] of the guild
      *
      * @throws IllegalStateException If the event did not happen in a Guild and the guild locale was not supplied
      *
      * @see hasGuildLocale
      * @see withGuildLocale
      */
-    val guildLocale: DiscordLocale
+    val guildLocale: Locale
 
     @CheckReturnValue
     override fun withBundle(localizationBundle: String): TextLocalizationContext

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/interaction/GuildLocaleProvider.kt

@@ -26,8 +26,10 @@ import java.util.*
  */
 @InterfacedService(acceptMultiple = false)
 interface GuildLocaleProvider {
+    @Deprecated("Use 'getLocale' instead, use 'DiscordLocale.from' / 'DiscordLocale#toLocale' if necessary")
     fun getDiscordLocale(interaction: Interaction): DiscordLocale
 
+    @Suppress("DEPRECATION")
     fun getLocale(interaction: Interaction): Locale =
         getDiscordLocale(interaction).toLocale()
-}
+}

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/interaction/LocalizableEditCallback.kt

@@ -1,6 +1,5 @@
 package io.github.freya022.botcommands.api.localization.interaction
 
-import io.github.freya022.botcommands.api.core.config.BLocalizationConfig
 import io.github.freya022.botcommands.api.localization.Localization
 import io.github.freya022.botcommands.api.localization.context.PairEntry
 import io.github.freya022.botcommands.api.localization.context.mapToEntries
@@ -95,6 +94,7 @@ interface LocalizableEditCallback {
      * - No [registered bundle][BLocalizationConfig.responseBundles] containing the path could be found
      * - If the template requires an argument that was not passed to [entries]
      */
+    @Deprecated("Pass a Locale instead")
     @CheckReturnValue
     fun editLocalized(locale: DiscordLocale, localizationPath: String, vararg entries: Localization.Entry): MessageEditCallbackAction =
         editLocalized(locale.toLocale(), localizationPath, *entries)
@@ -201,6 +201,8 @@ fun LocalizableEditCallback.editGuild(localizationPath: String, vararg entries:
  * - No [registered bundle][BLocalizationConfig.responseBundles] containing the path could be found
  * - If the template requires an argument that was not passed to [entries]
  */
+@Suppress("DEPRECATION")
+@Deprecated("Pass a Locale instead")
 fun LocalizableEditCallback.editLocalized(locale: DiscordLocale, localizationPath: String, vararg entries: PairEntry) =
     editLocalized(locale, localizationPath, *entries.mapToEntries())
 
@@ -226,4 +228,4 @@ fun LocalizableEditCallback.editLocalized(locale: DiscordLocale, localizationPat
  * - If the template requires an argument that was not passed to [entries]
  */
 fun LocalizableEditCallback.editLocalized(locale: Locale, localizationPath: String, vararg entries: PairEntry) =
-    editLocalized(locale, localizationPath, *entries.mapToEntries())
+    editLocalized(locale, localizationPath, *entries.mapToEntries())

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/localization/interaction/LocalizableInteraction.kt

@@ -1,6 +1,5 @@
 package io.github.freya022.botcommands.api.localization.interaction
 
-import io.github.freya022.botcommands.api.core.config.BLocalizationConfig
 import io.github.freya022.botcommands.api.localization.LocalizableAction
 import io.github.freya022.botcommands.api.localization.Localization
 import io.github.freya022.botcommands.api.localization.context.AppLocalizationContext
@@ -33,7 +32,7 @@ interface LocalizableInteraction : LocalizableAction {
 
     /**
      * Returns a localization context for the provided bundle name and path prefix,
-     * using the locales from [UserLocaleProvider.getDiscordLocale] and [GuildLocaleProvider.getDiscordLocale].
+     * using the locales from [UserLocaleProvider] and [GuildLocaleProvider].
      */
     override fun getLocalizationContext(bundleName: String, pathPrefix: String?): AppLocalizationContext
 
@@ -146,4 +145,4 @@ fun LocalizableInteraction.getUserMessage(localizationPath: String, vararg entri
  * - If the template requires an argument that was not passed to [entries]
  */
 fun LocalizableInteraction.getGuildMessage(localizationPath: String, vararg entries: PairEntry): String =
-    getGuildMessage(localizationPath, *entries.mapToEntries())
+    getGuildMessage(localizationPath, *entries.mapToEntries())