feat: Implement localisation support for Options and Choices, include type conversion safeguard for Locale usage.

Author: FayeDel

interactions/client.py

@@ -599,9 +599,9 @@ async def message_command(ctx):
         :param default_permission?: The default permission of accessibility for the application command. Defaults to ``True``.
         :type default_permission: Optional[bool]
         :param name_localizations?: The dictionary of localization for the ``name`` field. This enforces the same restrictions as the ``name`` field.
-        :param name_localizations: Optional[Dict[str, str]]
+        :param name_localizations: Optional[Dict[Union[str, Locale], str]]
         :param description_localizations?: The dictionary of localization for the ``description`` field. This enforces the same restrictions as the ``description`` field.
-        :param description_localizations: Optional[Dict[str, str]]
+        :param description_localizations: Optional[Dict[Union[str, Locale], str]]
         :return: A callable response.
         :rtype: Callable[..., Any]
         """
@@ -645,7 +645,7 @@ def message_command(
         name: str,
         scope: Optional[Union[int, Guild, List[int], List[Guild]]] = MISSING,
         default_permission: Optional[bool] = MISSING,
-        name_localizations: Optional[Dict[Union[str, Locale], Any]] = MISSING,  # This is theory.
+        name_localizations: Optional[Dict[Union[str, Locale], Any]] = MISSING,
     ) -> Callable[..., Any]:
         """
         A decorator for registering a message context menu to the Discord API,
@@ -669,6 +669,8 @@ async def context_menu_name(ctx):
         :type scope: Optional[Union[int, Guild, List[int], List[Guild]]]
         :param default_permission?: The default permission of accessibility for the application command. Defaults to ``True``.
         :type default_permission: Optional[bool]
+        :param name_localizations?: The dictionary of localization for the ``name`` field. This enforces the same restrictions as the ``name`` field.
+        :param name_localizations: Optional[Dict[Union[str, Locale], str]]
         :return: A callable response.
         :rtype: Callable[..., Any]
         """
@@ -703,7 +705,7 @@ def user_command(
         name: str,
         scope: Optional[Union[int, Guild, List[int], List[Guild]]] = MISSING,
         default_permission: Optional[bool] = MISSING,
-        name_localizations: Optional[Dict[Union[str, Locale], Any]] = MISSING,  # This is theory.
+        name_localizations: Optional[Dict[Union[str, Locale], Any]] = MISSING,
     ) -> Callable[..., Any]:
         """
         A decorator for registering a user context menu to the Discord API,
@@ -727,6 +729,8 @@ async def context_menu_name(ctx):
         :type scope: Optional[Union[int, Guild, List[int], List[Guild]]]
         :param default_permission?: The default permission of accessibility for the application command. Defaults to ``True``.
         :type default_permission: Optional[bool]
+        :param name_localizations?: The dictionary of localization for the ``name`` field. This enforces the same restrictions as the ``name`` field.
+        :param name_localizations: Optional[Dict[Union[str, Locale], str]]
         :return: A callable response.
         :rtype: Callable[..., Any]
         """

interactions/models/command.py

@@ -2,7 +2,7 @@
 
 from ..api.models.channel import ChannelType
 from ..api.models.misc import DictSerializerMixin, Snowflake
-from ..enums import ApplicationCommandType, OptionType, PermissionType
+from ..enums import ApplicationCommandType, Locale, OptionType, PermissionType
 
 
 class Choice(DictSerializerMixin):
@@ -21,15 +21,29 @@ class Choice(DictSerializerMixin):
 
     :ivar str name: The name of the choice.
     :ivar Union[str, int, float] value: The returned value of the choice.
+    :ivar Optional[Dict[Union[str, Locale], str]] name_localizations?: The dictionary of localization for the ``name`` field. This enforces the same restrictions as the ``name`` field.
     """
 
-    __slots__ = ("_json", "name", "value")
+    __slots__ = ("_json", "name", "value", "name_localizations")
     _json: dict
     name: str
     value: Union[str, int, float]
+    name_localizations: Optional[Dict[Union[str, Locale], str]]
 
     def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)
+        if self._json.get("name_localizations"):
+            if any(
+                type(x) != str for x in self._json.get("name_localizations")
+            ):  # check if Locale object is used to create localisation at any certain point.
+                self._json["name_localizations"] = {
+                    k.value if isinstance(k, Locale) else k: v
+                    for k, v in self._json["name_localizations"].items()
+                }
+            self.name_localizations = {
+                k if isinstance(k, Locale) else Locale(k): v
+                for k, v in self._json["name_localizations"].items()
+            }
 
 
 class Option(DictSerializerMixin):
@@ -67,6 +81,8 @@ class Option(DictSerializerMixin):
     :ivar Optional[int] min_value?: The minimum value supported by the option.
     :ivar Optional[int] max_value?: The maximum value supported by the option.
     :ivar Optional[bool] autocomplete?: A status denoting whether this option is an autocomplete option.
+    :ivar Optional[Dict[Union[str, Locale], str]] name_localizations?: The dictionary of localization for the ``name`` field. This enforces the same restrictions as the ``name`` field.
+    :ivar Optional[Dict[Union[str, Locale], str]] description_localizations?: The dictionary of localization for the ``description`` field. This enforces the same restrictions as the ``description`` field.
     """
 
     __slots__ = (
@@ -99,9 +115,8 @@ class Option(DictSerializerMixin):
     min_value: Optional[int]
     max_value: Optional[int]
     autocomplete: Optional[bool]
-
-    name_localizations: Optional[Dict[str, str]]  # TODO: post-v4: document these when Discord does.
-    description_localizations: Optional[Dict[str, str]]
+    name_localizations: Optional[Dict[Union[str, Locale], str]]
+    description_localizations: Optional[Dict[Union[str, Locale], str]]
 
     def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)
@@ -126,6 +141,32 @@ def __init__(self, **kwargs) -> None:
             elif all(isinstance(choice, Choice) for choice in self.choices):
                 self._json["choices"] = [choice._json for choice in self.choices]
 
+        if self._json.get("name_localizations"):
+            if any(
+                type(x) != str for x in self._json.get("name_localizations")
+            ):  # check if Locale object is used to create localisation at any certain point.
+                self._json["name_localizations"] = {
+                    k.value if isinstance(k, Locale) else k: v
+                    for k, v in self._json["name_localizations"].items()
+                }
+            self.name_localizations = {
+                k if isinstance(k, Locale) else Locale(k): v
+                for k, v in self._json["name_localizations"].items()
+            }
+
+        if self._json.get("description_localizations"):
+            if any(
+                type(x) != str for x in self._json.get("name_localizations")
+            ):  # check if Locale object is used to create localisation at any certain point.
+                self._json["description_localizations"] = {
+                    k.value if isinstance(k, Locale) else k: v
+                    for k, v in self._json["description_localizations"].items()
+                }
+            self.description_localizations = {
+                k if isinstance(k, Locale) else Locale(k): v
+                for k, v in self._json["description_localizations"].items()
+            }
+
 
 class Permission(DictSerializerMixin):
     """
@@ -178,8 +219,8 @@ class ApplicationCommand(DictSerializerMixin):
     :ivar int version: The Application Command version autoincrement identifier.
     :ivar str default_member_permissions: The default member permission state of the application command.
     :ivar boolean dm_permission: The application permissions if executed in a Direct Message.
-    :ivar Optional[Dict[str, str]] name_localizations: The localisation dictionary for the application command name, if any.
-    :ivar Optional[Dict[str, str]] description_localizations: The localisation dictionary for the application command description, if any.
+    :ivar Optional[Dict[Union[str, Locale], str]] name_localizations: The localisation dictionary for the application command name, if any.
+    :ivar Optional[Dict[Union[str, Locale], str]] description_localizations: The localisation dictionary for the application command description, if any.
     """
 
     __slots__ = (
@@ -214,8 +255,8 @@ class ApplicationCommand(DictSerializerMixin):
     # TODO: post-v4: Investigate these once documented by Discord.
     default_member_permissions: str
     dm_permission: bool
-    name_localizations: Optional[Dict[str, str]]
-    description_localizations: Optional[Dict[str, str]]
+    name_localizations: Optional[Dict[Union[str, Locale], str]]
+    description_localizations: Optional[Dict[Union[str, Locale], str]]
 
     def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)
@@ -232,3 +273,29 @@ def __init__(self, **kwargs) -> None:
             if self._json.get("permissions")
             else None
         )
+
+        if self._json.get("name_localizations"):
+            if any(
+                type(x) != str for x in self._json.get("name_localizations")
+            ):  # check if Locale object is used to create localisation at any certain point.
+                self._json["name_localizations"] = {
+                    k.value if isinstance(k, Locale) else k: v
+                    for k, v in self._json["name_localizations"].items()
+                }
+            self.name_localizations = {
+                k if isinstance(k, Locale) else Locale(k): v
+                for k, v in self._json["name_localizations"].items()
+            }
+
+        if self._json.get("description_localizations"):
+            if any(
+                type(x) != str for x in self._json.get("description_localizations")
+            ):  # check if Locale object is used to create localisation at any certain point.
+                self._json["description_localizations"] = {
+                    k.value if isinstance(k, Locale) else k: v
+                    for k, v in self._json["description_localizations"].items()
+                }
+            self.description_localizations = {
+                k if isinstance(k, Locale) else Locale(k): v
+                for k, v in self._json["description_localizations"].items()
+            }