| Name | discord-ext-i17n JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | |
| Summary | A Pycord extension to support automatic text translations in 107 languages. |
| upload_time | 2024-02-03 23:34:55 |
| maintainer | |
| docs_url | None |
| author | Timo |
| requires_python | >=3.7 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# A [PyCord](https://github.com/Pycord-Development/pycord) extension for internationalization
<a href="https://github.com/Pycord-Development/pycord"><img src="https://img.shields.io/badge/Pycord-%3E=2.0.0b5-orange?style=for-the-badge&logo=python&logoColor=white"></a>
<a href="https://pypi.org/project/discord-ext-i17n"><img src="https://img.shields.io/pypi/v/discord-ext-i17n?style=for-the-badge&logo=pypi&logoColor=white&color=green"></a>
> [!NOTE]
> `Agent` class has been renamed as `AutoI17nAgent` but the old name is still supported
## Key Features
- Automatic text translations for messages, embeds [etc..](#fields-covered-by-automatic-translation)
- Zero code change necessary
- Fully customizable
- Forward Compatible
The extension is able to automatically translate all
specified objects [here](#fields-covered-by-automatic-translation) into any registered language
depending on the preferences of the destination channel or guild.
For instance, if a channel has the preference for Spanish, any messages, embeds etc.. that are being sent to the channel will be automatically translated into Spanish before it is sent.
> [!TIP]
> Translations will carry over markdown!
>
> ```
> I've set the language to `English` ๐ด๓ ง๓ ข๓ ฅ๓ ฎ๓ ง๓ ฟ!
> + He establecido el idioma en `Spanish` ๐ช๐ธ!
> + แแซแแฌแแฌแ
แแฌแธแแญแฏแแฌแธแแแบ `แแผแแบแแฌ (แแแฌ)` ๐ฒ๐ฒ!
> ```
_GoogleTranslated string in different languages with formatting maintained_
Check out the [FAQ](#faq), [Examples](#Examples) and [other feathers](#features-extended) for more information.
This extension is relatively new so please report any bugs at [issues](https://github.com/timoo4devv/discord-ext-i17n/issues)!
## Fields Covered by Automatic Translation
- `Messages`
- `Interaction Messages`
- `Embeds`
- `Buttons`
- `Selects`
- `Modals` (beta)
- `Webhooks` (beta)
## Installing
This is an extension for `PyCord`. It is recommended that there exists an installation of `py-cord>=2.0.0b5`.
To install this extension, run the following command:
```
# Linux/macOS
python3 -m pip install -U discord-ext-i17n
# Windows
py -3 -m pip install -U discord-ext-i17n
```
## Quick Example
**Required Steps**:
- Define a language getter function decorated with the `Detector.lang_getter` decorator
(this getter is called with an ID of _guilds / channels_ to see if it has a
language preference)
- Instantiate a `discord.ext.i17n.AutoI17nAgent` class to configure and inject code
- Create a command for users to set preferences
```py
from typing import Optional
from discord import Intents, Bot, ApplicationContext
from discord.ext.i17n import AutoI17nAgent, Language, Detector
intents = Intents.default()
# not necessary for the extension, enabled for msg commands
intents.messages = True
intents.message_content = True
bot = Bot(
command_prefix="!",
intents=intents,
)
bot.preferences = {}
bot.agent = AutoI17nAgent(
translate_all=True
) # This must be instantiated at least and only once
@Detector.lang_getter
async def get_lang(id) -> Optional[Language]:
"""
This decorated function will be called internally to get Language
preferences.
"""
return bot.preferences.get(id, None)
@bot.slash_command(name="lang")
async def set_lang(ctx: ApplicationContext, lang_code: str):
"""
Set the language for the bot in the current channel.
"""
lang = Language.from_code(lang_code)
if lang is None:
return await ctx.respond("Bad language code!")
elif lang is Language.English:
if ctx.channel.id in bot.preferences:
bot.preferences.pop(ctx.channel.id)
else:
bot.preferences[ctx.channel.id] = lang
await ctx.respond(f"I've set the language to `{lang.name.title()}` {lang.emoji}!")
@bot.command(name="hi")
async def greet(ctx):
# This will be translated before sent if necessary
await ctx.reply("Hey!!")
bot.run("TOKEN")
```
## Examples
1. [Get Started](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/get_started.py) - A minimal example on how to get started with the extension.
2. [Cog Example](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/cog_example.py) - Get started but inside a cog.
3. [Customized](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/customized.py) - An example on how to customize/make your own translator and override the default one.
4. [Settings](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py) - An example on how to enable/disable the extension from translating certain fields
5. [Optimized](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/optimized.py) - An example on how to ignore translation on parts of a string that is prone to change
6. [All Objects](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/all_objects.py) - A summary example of every object that is affected by translation + all features discussed prior
## Features Extended
### Tokenization
Tokenization breaks down a string in any order or magnitude of markdown decorations to the extent accepted by discord, into separate tokens to ready for batch translation. Once translated, the new phrases are reassembeled into correct positions and thus maintaining decorative characters fairly accurately.
### Constants
This library implements constants for:
1. Language `Names` *to* `Code` *to* `Emoji` enum
Examples:
```py
>>> Language.English.code
... en
>>> Language.English.emoji
... ๐ด๓ ง๓ ข๓ ฅ๓ ฎ๓ ง๓ ฟ
>>> Language.name
... english
```
To access enum elements for a specific language through it's corresponding code or name:
```py
>>> Language.from_code("en")
... Language.English
>>> Language.from_name("english")
... Language.English
```
2. Codeblock identifiers
`CODEBLOCK_LANGS` is an exhaustive set of string identifiers that are considered valid code block languages in the tokenizer.
## FAQ
1. [How do we tell the extension to translate x?](#how-do-we-tell-the-extension-to-translate-x)
2. [How does the extension work?](#how-does-the-extension-work)
3. [What does it use to translate the string?](#what-does-it-use-to-translate-the-string)
4. [When are strings not translated?](#when-are-strings-not-translated)
5. [How do I avoid translation on specific function calls?](#how-do-i-avoid-translation-on-specific-function-calls)
### How do we tell the extension to translate x?
By default, the extension will translate all messages and ignore others. If you want
to translate other objects such as buttons, embeds and so on, you will have
to explicitly specify them as a parameter when instantiating the `AutoI17nAgent` class or modify the
`translate_x` flag from the class. See detailed example [here](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py)
Apart from that, you can call the usual methods like `Messegable.send`,
`ApplicationContext.respond` with your texts and the translation will be
handled in the backend. Absolutely
no code change is necessary when calling these high-level methods.
### How does the extension work?
When you call high-level methods e.g. `Messegable.send`
the extension intercepts the text and the destination it's being sent to. It resolves
whether if this text requires translation by calling the language getter with the
ID of its destination. If it has one, it will append
the language code into an appropriate field and this appendage is later extracted
before text gets sent to the discord API where tokenization, translation, caching
and other book-keeping occurs if necessary.
### What does it use to translate the string?
By default, the extension translates your strings using the [Google Translator](https://pypi.org/project/googletrans/)
library. You can override this with your own translator like in the example
[here](https://github.com/Ricktimoo4devvaym/discord-ext-i17n/blob/master/examples/customized.py).
### When are strings not translated?
Strings are not translated in cases where either if the text are already
detected to be in the language
that it should be translated into, or the destination no preference.
### How do I avoid translation on specific function calls?
You can switch the flags to process specific call translations with some
code changes. One example is the command `selective` [here](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py).
---
#### TODO / KNOWN ISSUES
[-] Defer interaction responses only if translation doesn't exist in cache
[-] Resolve the issue with not being able to translate in time for `Modals` and they can't be deferred....
[-] Support translation in Webhooks
[-] More tests
Raw data
{
"_id": null,
"home_page": "",
"name": "discord-ext-i17n",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Timo",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/22/ea/a6186b6d6192fb0d2aa31050a5148ba893a70b6ba4d405207d502bcf6b0d/discord-ext-i17n-0.1.0.tar.gz",
"platform": null,
"description": "# A [PyCord](https://github.com/Pycord-Development/pycord) extension for internationalization\r\n\r\n<a href=\"https://github.com/Pycord-Development/pycord\"><img src=\"https://img.shields.io/badge/Pycord-%3E=2.0.0b5-orange?style=for-the-badge&logo=python&logoColor=white\"></a>\r\n<a href=\"https://pypi.org/project/discord-ext-i17n\"><img src=\"https://img.shields.io/pypi/v/discord-ext-i17n?style=for-the-badge&logo=pypi&logoColor=white&color=green\"></a>\r\n\r\n> [!NOTE]\r\n> `Agent` class has been renamed as `AutoI17nAgent` but the old name is still supported\r\n\r\n## Key Features\r\n\r\n- Automatic text translations for messages, embeds [etc..](#fields-covered-by-automatic-translation)\r\n- Zero code change necessary\r\n- Fully customizable\r\n- Forward Compatible\r\n\r\nThe extension is able to automatically translate all\r\nspecified objects [here](#fields-covered-by-automatic-translation) into any registered language\r\ndepending on the preferences of the destination channel or guild.\r\nFor instance, if a channel has the preference for Spanish, any messages, embeds etc.. that are being sent to the channel will be automatically translated into Spanish before it is sent.\r\n\r\n> [!TIP]\r\n> Translations will carry over markdown!\r\n> \r\n> ```\r\n> I've set the language to `English` \ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f!\r\n> + He establecido el idioma en `Spanish` \ud83c\uddea\ud83c\uddf8!\r\n> + \u1004\u102b\u1018\u102c\u101e\u102c\u1005\u1000\u102c\u1038\u1000\u102d\u102f\u1011\u102c\u1038\u1010\u101a\u103a `\u1019\u103c\u1014\u103a\u1019\u102c (\u1017\u1019\u102c)` \ud83c\uddf2\ud83c\uddf2!\r\n> ```\r\n\r\n\r\n_GoogleTranslated string in different languages with formatting maintained_\r\n\r\nCheck out the [FAQ](#faq), [Examples](#Examples) and [other feathers](#features-extended) for more information.\r\nThis extension is relatively new so please report any bugs at [issues](https://github.com/timoo4devv/discord-ext-i17n/issues)!\r\n\r\n## Fields Covered by Automatic Translation\r\n\r\n- `Messages`\r\n- `Interaction Messages`\r\n- `Embeds`\r\n- `Buttons`\r\n- `Selects`\r\n- `Modals` (beta)\r\n- `Webhooks` (beta)\r\n\r\n## Installing\r\n\r\nThis is an extension for `PyCord`. It is recommended that there exists an installation of `py-cord>=2.0.0b5`.\r\n\r\nTo install this extension, run the following command:\r\n\r\n```\r\n# Linux/macOS\r\npython3 -m pip install -U discord-ext-i17n\r\n\r\n# Windows\r\npy -3 -m pip install -U discord-ext-i17n\r\n```\r\n\r\n## Quick Example\r\n\r\n**Required Steps**:\r\n\r\n- Define a language getter function decorated with the `Detector.lang_getter` decorator\r\n (this getter is called with an ID of _guilds / channels_ to see if it has a\r\n language preference)\r\n- Instantiate a `discord.ext.i17n.AutoI17nAgent` class to configure and inject code\r\n- Create a command for users to set preferences\r\n\r\n```py\r\nfrom typing import Optional\r\nfrom discord import Intents, Bot, ApplicationContext\r\nfrom discord.ext.i17n import AutoI17nAgent, Language, Detector\r\n\r\nintents = Intents.default()\r\n# not necessary for the extension, enabled for msg commands\r\nintents.messages = True\r\nintents.message_content = True\r\n\r\nbot = Bot(\r\n command_prefix=\"!\",\r\n intents=intents,\r\n)\r\nbot.preferences = {}\r\nbot.agent = AutoI17nAgent(\r\n translate_all=True\r\n) # This must be instantiated at least and only once\r\n\r\n\r\n@Detector.lang_getter\r\nasync def get_lang(id) -> Optional[Language]:\r\n \"\"\"\r\n This decorated function will be called internally to get Language\r\n preferences.\r\n \"\"\"\r\n return bot.preferences.get(id, None)\r\n\r\n\r\n@bot.slash_command(name=\"lang\")\r\nasync def set_lang(ctx: ApplicationContext, lang_code: str):\r\n \"\"\"\r\n Set the language for the bot in the current channel.\r\n \"\"\"\r\n lang = Language.from_code(lang_code)\r\n if lang is None:\r\n return await ctx.respond(\"Bad language code!\")\r\n elif lang is Language.English:\r\n if ctx.channel.id in bot.preferences:\r\n bot.preferences.pop(ctx.channel.id)\r\n else:\r\n bot.preferences[ctx.channel.id] = lang\r\n\r\n await ctx.respond(f\"I've set the language to `{lang.name.title()}` {lang.emoji}!\")\r\n\r\n\r\n@bot.command(name=\"hi\")\r\nasync def greet(ctx):\r\n # This will be translated before sent if necessary\r\n await ctx.reply(\"Hey!!\")\r\n\r\n\r\nbot.run(\"TOKEN\")\r\n```\r\n\r\n## Examples\r\n\r\n1. [Get Started](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/get_started.py) - A minimal example on how to get started with the extension.\r\n2. [Cog Example](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/cog_example.py) - Get started but inside a cog.\r\n3. [Customized](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/customized.py) - An example on how to customize/make your own translator and override the default one.\r\n4. [Settings](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py) - An example on how to enable/disable the extension from translating certain fields\r\n5. [Optimized](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/optimized.py) - An example on how to ignore translation on parts of a string that is prone to change\r\n6. [All Objects](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/all_objects.py) - A summary example of every object that is affected by translation + all features discussed prior\r\n\r\n## Features Extended\r\n### Tokenization\r\n\r\nTokenization breaks down a string in any order or magnitude of markdown decorations to the extent accepted by discord, into separate tokens to ready for batch translation. Once translated, the new phrases are reassembeled into correct positions and thus maintaining decorative characters fairly accurately.\r\n\r\n### Constants\r\nThis library implements constants for:\r\n1. Language `Names` *to* `Code` *to* `Emoji` enum\r\n\r\nExamples:\r\n```py\r\n>>> Language.English.code\r\n... en\r\n>>> Language.English.emoji\r\n... \ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f\r\n>>> Language.name\r\n... english\r\n```\r\nTo access enum elements for a specific language through it's corresponding code or name:\r\n```py\r\n>>> Language.from_code(\"en\")\r\n... Language.English\r\n>>> Language.from_name(\"english\")\r\n... Language.English\r\n```\r\n\r\n2. Codeblock identifiers\r\n\r\n`CODEBLOCK_LANGS` is an exhaustive set of string identifiers that are considered valid code block languages in the tokenizer.\r\n\r\n## FAQ\r\n1. [How do we tell the extension to translate x?](#how-do-we-tell-the-extension-to-translate-x)\r\n2. [How does the extension work?](#how-does-the-extension-work)\r\n3. [What does it use to translate the string?](#what-does-it-use-to-translate-the-string)\r\n4. [When are strings not translated?](#when-are-strings-not-translated)\r\n5. [How do I avoid translation on specific function calls?](#how-do-i-avoid-translation-on-specific-function-calls)\r\n\r\n### How do we tell the extension to translate x?\r\n\r\nBy default, the extension will translate all messages and ignore others. If you want\r\nto translate other objects such as buttons, embeds and so on, you will have\r\nto explicitly specify them as a parameter when instantiating the `AutoI17nAgent` class or modify the\r\n`translate_x` flag from the class. See detailed example [here](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py)\r\n\r\nApart from that, you can call the usual methods like `Messegable.send`,\r\n`ApplicationContext.respond` with your texts and the translation will be\r\nhandled in the backend. Absolutely\r\nno code change is necessary when calling these high-level methods.\r\n\r\n### How does the extension work?\r\n\r\nWhen you call high-level methods e.g. `Messegable.send`\r\nthe extension intercepts the text and the destination it's being sent to. It resolves\r\nwhether if this text requires translation by calling the language getter with the\r\nID of its destination. If it has one, it will append\r\nthe language code into an appropriate field and this appendage is later extracted\r\nbefore text gets sent to the discord API where tokenization, translation, caching\r\nand other book-keeping occurs if necessary.\r\n\r\n### What does it use to translate the string?\r\n\r\nBy default, the extension translates your strings using the [Google Translator](https://pypi.org/project/googletrans/)\r\nlibrary. You can override this with your own translator like in the example\r\n[here](https://github.com/Ricktimoo4devvaym/discord-ext-i17n/blob/master/examples/customized.py).\r\n\r\n### When are strings not translated?\r\n\r\nStrings are not translated in cases where either if the text are already\r\ndetected to be in the language\r\nthat it should be translated into, or the destination no preference.\r\n\r\n### How do I avoid translation on specific function calls?\r\n\r\nYou can switch the flags to process specific call translations with some\r\ncode changes. One example is the command `selective` [here](https://github.com/timoo4devv/discord-ext-i17n/blob/master/examples/settings.py).\r\n\r\n---\r\n\r\n#### TODO / KNOWN ISSUES\r\n\r\n[-] Defer interaction responses only if translation doesn't exist in cache\r\n\r\n[-] Resolve the issue with not being able to translate in time for `Modals` and they can't be deferred....\r\n\r\n[-] Support translation in Webhooks\r\n\r\n[-] More tests\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A Pycord extension to support automatic text translations in 107 languages.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/timoo4devv/discord-ext-i17n/issues",
"Homepage": "https://github.com/timoo4devv/discord-ext-i17n"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c7cea9d0e1921bc0499a5dac4680d72c0d782ebff60272cca9be10aa4bd4524b",
"md5": "ad8df140da7e3cea6e58d3a00321f6fb",
"sha256": "313f30d5475e0df30d192a1ab5e1bc2488271d27cb342b7d3aa67bbfdfba3dc4"
},
"downloads": -1,
"filename": "discord_ext_i17n-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad8df140da7e3cea6e58d3a00321f6fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22807,
"upload_time": "2024-02-03T23:34:53",
"upload_time_iso_8601": "2024-02-03T23:34:53.796710Z",
"url": "https://files.pythonhosted.org/packages/c7/ce/a9d0e1921bc0499a5dac4680d72c0d782ebff60272cca9be10aa4bd4524b/discord_ext_i17n-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22eaa6186b6d6192fb0d2aa31050a5148ba893a70b6ba4d405207d502bcf6b0d",
"md5": "2cb4c290f8d906e88f158d6243a75e2a",
"sha256": "ce0382433676fab94a1a557ebe86af24f5a08d2afdcd1b65bd9da193492d0853"
},
"downloads": -1,
"filename": "discord-ext-i17n-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2cb4c290f8d906e88f158d6243a75e2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23552,
"upload_time": "2024-02-03T23:34:55",
"upload_time_iso_8601": "2024-02-03T23:34:55.441480Z",
"url": "https://files.pythonhosted.org/packages/22/ea/a6186b6d6192fb0d2aa31050a5148ba893a70b6ba4d405207d502bcf6b0d/discord-ext-i17n-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 23:34:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "timoo4devv",
"github_project": "discord-ext-i17n",
"github_not_found": true,
"lcname": "discord-ext-i17n"
}
