Rapptz
3 years ago
16 changed files with 663 additions and 91 deletions
@ -0,0 +1,195 @@ |
|||
""" |
|||
The MIT License (MIT) |
|||
|
|||
Copyright (c) 2015-present Rapptz |
|||
|
|||
Permission is hereby granted, free of charge, to any person obtaining a |
|||
copy of this software and associated documentation files (the "Software"), |
|||
to deal in the Software without restriction, including without limitation |
|||
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
|||
and/or sell copies of the Software, and to permit persons to whom the |
|||
Software is furnished to do so, subject to the following conditions: |
|||
|
|||
The above copyright notice and this permission notice shall be included in |
|||
all copies or substantial portions of the Software. |
|||
|
|||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
|||
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
|||
DEALINGS IN THE SOFTWARE. |
|||
""" |
|||
|
|||
from __future__ import annotations |
|||
from typing import Any, Optional |
|||
from .errors import TranslationError |
|||
from ..enums import Enum, Locale |
|||
|
|||
|
|||
__all__ = ( |
|||
'TranslationContext', |
|||
'Translator', |
|||
'locale_str', |
|||
) |
|||
|
|||
|
|||
class TranslationContext(Enum): |
|||
command_name = 0 |
|||
command_description = 1 |
|||
parameter_name = 2 |
|||
parameter_description = 3 |
|||
choice_name = 4 |
|||
|
|||
|
|||
class Translator: |
|||
"""A class that handles translations for commands, parameters, and choices. |
|||
|
|||
Translations are done lazily in order to allow for async enabled translations as well |
|||
as supporting a wide array of translation systems such as :mod:`gettext` and |
|||
`Project Fluent <https://projectfluent.org>`_. |
|||
|
|||
In order for a translator to be used, it must be set using the :meth:`CommandTree.set_translator` |
|||
method. The translation flow for a string is as follows: |
|||
|
|||
1. Use :class:`locale_str` instead of :class:`str` in areas of a command you want to be translated. |
|||
- Currently, these are command names, command descriptions, parameter names, parameter descriptions, and choice names. |
|||
- This can also be used inside the :func:`~discord.app_commands.describe` decorator. |
|||
2. Call :meth:`CommandTree.set_translator` to the translator instance that will handle the translations. |
|||
3. Call :meth:`CommandTree.sync` |
|||
4. The library will call :meth:`Translator.translate` on all the relevant strings being translated. |
|||
|
|||
.. versionadded:: 2.0 |
|||
""" |
|||
|
|||
async def load(self) -> None: |
|||
"""|coro| |
|||
|
|||
An asynchronous setup function for loading the translation system. |
|||
|
|||
The default implementation does nothing. |
|||
|
|||
This is invoked when :meth:`CommandTree.set_translator` is called. |
|||
""" |
|||
pass |
|||
|
|||
async def unload(self) -> None: |
|||
"""|coro| |
|||
|
|||
An asynchronous teardown function for unloading the translation system. |
|||
|
|||
The default implementation does nothing. |
|||
|
|||
This is invoked when :meth:`CommandTree.set_translator` is called |
|||
if a tree already has a translator or when :meth:`discord.Client.close` is called. |
|||
""" |
|||
pass |
|||
|
|||
async def _checked_translate(self, string: locale_str, locale: Locale, context: TranslationContext) -> Optional[str]: |
|||
try: |
|||
return await self.translate(string, locale, context) |
|||
except TranslationError: |
|||
raise |
|||
except Exception as e: |
|||
raise TranslationError(string=string, locale=locale, context=context) from e |
|||
|
|||
async def translate(self, string: locale_str, locale: Locale, context: TranslationContext) -> Optional[str]: |
|||
"""|coro| |
|||
|
|||
Translates the given string to the specified locale. |
|||
|
|||
If the string cannot be translated, ``None`` should be returned. |
|||
|
|||
The default implementation returns ``None``. |
|||
|
|||
If an exception is raised in this method, it should inherit from :exc:`TranslationError`. |
|||
If it doesn't, then when this is called the exception will be chained with it instead. |
|||
|
|||
Parameters |
|||
------------ |
|||
string: :class:`locale_str` |
|||
The string being translated. |
|||
locale: :class:`~discord.Locale` |
|||
The locale being requested for translation. |
|||
context: :class:`TranslationContext` |
|||
The translation context where the string originated from. |
|||
""" |
|||
|
|||
return None |
|||
|
|||
|
|||
class locale_str: |
|||
"""Marks a string as ready for translation. |
|||
|
|||
This is done lazily and is not actually translated until :meth:`CommandTree.sync` is called. |
|||
|
|||
The sync method then ultimately defers the responsibility of translating to the :class:`Translator` |
|||
instance used by the :class:`CommandTree`. For more information on the translation flow, see the |
|||
:class:`Translator` documentation. |
|||
|
|||
.. container:: operations |
|||
|
|||
.. describe:: str(x) |
|||
|
|||
Returns the message passed to the string. |
|||
|
|||
.. describe:: x == y |
|||
|
|||
Checks if the string is equal to another string. |
|||
|
|||
.. describe:: x != y |
|||
|
|||
Checks if the string is not equal to another string. |
|||
|
|||
.. describe:: hash(x) |
|||
|
|||
Returns the hash of the string. |
|||
|
|||
.. versionadded:: 2.0 |
|||
|
|||
Attributes |
|||
------------ |
|||
message: :class:`str` |
|||
The message being translated. Once set, this cannot be changed. |
|||
|
|||
.. warning:: |
|||
|
|||
This must be the default "message" that you send to Discord. |
|||
Discord sends this message back to the library and the library |
|||
uses it to access the data in order to dispatch commands. |
|||
|
|||
For example, in a command name context, if the command |
|||
name is ``foo`` then the message *must* also be ``foo``. |
|||
For other translation systems that require a message ID such |
|||
as Fluent, consider using a keyword argument to pass it in. |
|||
extras: :class:`dict` |
|||
A dict of user provided extras to attach to the translated string. |
|||
This can be used to add more context, information, or any metadata necessary |
|||
to aid in actually translating the string. |
|||
|
|||
Since these are passed via keyword arguments, the keys are strings. |
|||
""" |
|||
|
|||
def __init__(self, message: str, /, **kwargs: Any) -> None: |
|||
self.__message: str = message |
|||
self.extras: dict[str, Any] = kwargs |
|||
|
|||
@property |
|||
def message(self) -> str: |
|||
return self.__message |
|||
|
|||
def __str__(self) -> str: |
|||
return self.__message |
|||
|
|||
def __repr__(self) -> str: |
|||
kwargs = ', '.join(f'{k}={v!r}' for k, v in self.extras.items()) |
|||
if kwargs: |
|||
return f'{self.__class__.__name__}({self.__message!r}, {kwargs})' |
|||
return f'{self.__class__.__name__}({self.__message!r})' |
|||
|
|||
def __eq__(self, obj: object) -> bool: |
|||
return isinstance(obj, locale_str) and self.message == obj.message |
|||
|
|||
def __hash__(self) -> int: |
|||
return hash(self.__message) |
|||
Loading…
Reference in new issue