Add translator docs

EvieePy · EvieePy · commit a6ccf411e09c · 2025-08-05T15:08:02.000+10:00
diff --git a/twitchio/ext/commands/context.py b/twitchio/ext/commands/context.py
@@ -545,6 +545,53 @@ async def send(self, content: str, *, me: bool = False) -> SentMessage:
         return await self.channel.send_message(sender=self.bot.bot_id, message=new)
 
     async def send_translated(self, content: str, *, me: bool = False, langcode: str | None = None) -> SentMessage:
+        """|coro|
+
+        Send a translated chat message to the channel associated with this context.
+
+        You must have added a :class:`.commands.Translator` to your :class:`.commands.Command` in order to effectively use
+        this method. If no :class:`.commands.Translator` is found, this method acts identical to :meth:`.send`.
+
+        If this method can not find a valid language code, E.g. both :meth:`.commands.Translator.get_langcode` and the parameter
+        ``langcode`` return ``None``, this method acts identical to :meth:`.send`.
+
+        See the following documentation for more details on translators:
+
+        - :class:`.commands.Translator`
+        - :class:`.commands.translator`
+
+        .. important::
+
+            You must have the ``user:write:chat`` scope. If an app access token is used,
+            then additionally requires the ``user:bot`` scope on the bot,
+            and either ``channel:bot`` scope from the broadcaster or moderator status.
+
+        Parameters
+        ----------
+        content: str
+            The content of the message you would like to translate and then send.
+            This **and** the translated version of this content cannot exceed ``500`` characters.
+            Additionally the content parameter will be stripped of all leading and trailing whitespace.
+        me: bool
+            An optional bool indicating whether you would like to send this message with the ``/me`` chat command.
+        langcode: str | None
+            An optional ``langcode`` to override the ``langcode`` returned from :meth:`.commands.Translator.get_langcode`.
+            This should only be provided if you do custom language code lookups outside of your
+            :class:`.commands.Translator`. Defaults to ``None``.
+
+
+        Returns
+        -------
+        SentMessage
+            The payload received by Twitch after sending this message.
+
+        Raises
+        ------
+        HTTPException
+            Twitch failed to process the message, could be ``400``, ``401``, ``403``, ``422`` or any ``5xx`` status code.
+        MessageRejectedError
+            Twitch rejected the message from various checks.
+        """
         translator: Translator | None = getattr(self.command, "translator", None)
         new = (f"/me {content}" if me else content).strip()
 
diff --git a/twitchio/ext/commands/core.py b/twitchio/ext/commands/core.py
@@ -272,6 +272,9 @@ def _get_signature(self) -> None:
 
     @property
     def translator(self) -> Translator | None:
+        """Property returning the :class:`.commands.Translator` associated with this command or ``None`` if one was not
+        used.
+        """
         return self._translator
 
     @property
@@ -1480,6 +1483,19 @@ def wrapper(
 
 
 def translator(cls: Translator | type[Translator]) -> Any:
+    """|deco|
+
+    Decorator which adds a :class:`.commands.Translator` to a :class:`.commands.Command`.
+
+    You can provide the class or instance of your implemented :class:`.commands.Translator` to this decorator.
+
+    See the :class:`.commands.Translator` documentation for more information on translators.
+
+    .. note::
+
+        You can only have one :class:`.commands.Translator` per command.
+    """
+
     def wrapper(func: Any) -> Any:
         inst = cls() if inspect.isclass(cls) else cls
 
diff --git a/twitchio/ext/commands/translators.py b/twitchio/ext/commands/translators.py
@@ -36,8 +36,115 @@
 
 
 class Translator(abc.ABC):
+    """Abstract Base Class for command translators.
+
+    This class allows you to implement logic to translate messages sent via the :meth:`.commands.Context.send_translated`
+    method in commands or anywhere :class:`.commands.Context` is available.
+
+    You should pass your implemented class to the :meth:`.commands.translator` decorator on top of a :class:`~.commands.Command`.
+
+    .. important::
+
+        You must implement every method of this ABC.
+    """
+
     @abc.abstractmethod
-    def get_langcode(self, ctx: Context[Any], name: str) -> str | None: ...
+    def get_langcode(self, ctx: Context[Any], name: str) -> str | None:
+        """Method which is called when :meth:`.commands.Context.send_translated` is used on a :class:`.commands.Command`
+        which has an associated Translator, to determine the ``langcode`` which should be passed to :meth:`.translate` or ``None``
+        if the content should not be translated.
+
+        By default the ``name`` or ``alias`` used to invoke the command is passed alongside :class:`.commands.Context` to aid in
+        determining the ``langcode`` you should use.
+
+        You can use any system for the language codes, however they must be a :class:`str`. We also recommend using a
+        recognized system such as the ``ISO 639`` language code format.
+
+        Parameters
+        ----------
+        ctx: commands.Context
+            The context surrounding the command invocation.
+        name: str
+            The ``name`` or ``alias`` used to invoke the command. This does not include the prefix, however if you need to
+            retrieve the prefix see: :attr:`.commands.Context.prefix`.
+
+        Returns
+        -------
+        str
+            The language code as a :class:`str` to pass to :meth:`.translate`.
+
+        Example
+        -------
+
+        .. code:: python3
+            # For example purposes only the "get_langcode" method is shown in this example...
+            # The "translate" method must also be implemented...
+
+            class HelloTranslator(commands.Translator):
+                def __init__(self) -> None:
+                    self.code_mapping = {"hello": "en", "bonjour": "fr"}
+
+               def get_langcode(self, ctx: commands.Context, name: str) -> str | None:
+                   # Return a default of "en". Could also be ``None`` to prevent `translate` being called and to
+                   # send the default message...
+                   return self.code_mapping.get(name, "en")
+
+
+            @commands.command(name="hello", aliases=["bonjour"])
+            @commands.translator(HelloTranslator)
+            async def hello_command(ctx: commands.Context) -> None:
+                await ctx.send_translated("Hello!")
+        """
 
     @abc.abstractmethod
-    async def translate(self, ctx: Context[Any], text: str, langcode: str) -> str: ...
+    async def translate(self, ctx: Context[Any], text: str, langcode: str) -> str:
+        """|coro|
+
+        Method used to translate the content passed to :meth:`.commands.Context.send_translated` with the language code returned from
+        :meth:`.get_langcode`. If ``None`` is returned from :meth:`.get_langcode`, this method will not be called and the
+        default content provided to :meth:`~.commands.Context.send_translated` will be sent instead.
+
+        You could use this method to call a local or external translation API, retrieve translations from a database or local
+        mapping etc.
+
+        This method must return a :class:`str`.
+
+        Parameters
+        ----------
+        ctx: commands.Context
+            The context surrounding the command invocation.
+        text: str
+            The content passed to :meth:`~.commands.Context.send_translated` which should be translated.
+        langcode: str
+            The language code returned via :meth:`.get_langcode`, which can be used to determine the language the text should
+            be translated to.
+
+        Returns
+        -------
+        str
+            The translated text which should be sent. This should not exceed ``500`` characters.
+
+        Example
+        -------
+
+        .. code:: python3
+            # For example purposes only the "translate" method is shown in this example...
+            # The "get_langcode" method must also be implemented...
+
+            class HelloTranslator(commands.Translator):
+
+                async def translate(self, ctx: commands.Context, text: str, langcode: str) -> str:
+                    # Usually you would call an API, or retrieve from a database or dict or some other solution...
+                    # This is just for an example...
+
+                    if langcode == "en":
+                        return text
+
+                    elif langcode == "fr":
+                        return "Bonjour!"
+
+            @commands.command(name="hello", aliases=["bonjour"])
+            @commands.translator(HelloTranslator)
+            async def hello_command(ctx: commands.Context) -> None:
+                await ctx.send_translated("Hello!")
+        """
