[Github](https://github.com/PearooXD/discord-localization) | [PyPI](https://pypi.org/project/discord-localization/)
--------
## Setting up
Start by downloading the package via pip.
```
python3 -m pip install discord-localization
```
After that, you can just import it into your file as a discord.py extension.
--------
## Examples
```py
from discord.ext import localization
import random
_ = localization.Localization("main.i18n.json", "en")
# the first option is the relative path to the localization
# file. the second is the fallback/default language that is
# used if the actual language is not found.
dice = random.randint(1, 6)
language = input("What's your native language? / Was ist Deine Muttersprache? (en/de) >>> ")
print(_("dice_result", language, dice=dice))
```
```json
{
"en": {
"dice_result": "Your dice rolled {dice}!"
},
"de": {
"dice_result": "Dein Würfel hat eine {dice} gewürfelt!"
}
}
```
-------
## Integrating it into your Discord bot
```py
import discord
from discord.ext import commands, localization
bot = commands.Bot(command_prefix="!", intents=discord.Intents.all())
# hey guys, breaking the 4th wall here. please stop using Intents.default()
# just to set the message_contentintent to True right after. Intents.all() does
# it for you.
_ = localization.Localization("main_localization.json", "en")
@bot.event
async def on_ready():
print("Bot is ready!")
@bot.command()
async def ping(ctx):
await ctx.reply(_("ping", ctx, latency=bot.latency * 1000))
```
```json
{
"en": {
"ping": "Pong! {latency}ms"
},
"en-US": {
"ping": "Pong! {latency}ms, but American! (because Discord makes a difference between en-US and en-UK locales - you can circumvent this by setting the default_locale)"
},
"en-UK": {
"ping": "Ping is {latency}ms, innit, bruv? (i'm sorry)"
},
"fr": {
"ping": "Bonjour! Ping is {latency}ms!"
}
}
```
Explanation:
- By setting the default locale to "en", we won't have any issues with unfinished localizations. This way, we are also not required to define localizations for both "en-US" and"en-UK" (since Discord's API differentiates them, however, usually, bots don't.)
- We are passing a `latency` argument to the localization function (which is also available with `Localization._`! But calling the object is fine too.), which will be later usedwhenever we use `{latency}` in a localization.
- We are defining an `en` locale in the JSON file, even though both Discord's API and discord.py doesn't have such a locale. This is to make it more obvious that everything inthat locale should be in English - you could also name it `default_locale`, you just have to make sure to edit it in the `Localization` object.
- We pass `ctx` to the localization function, which will automatically try getting `ctx.guild.preferred_locale`. This works with `Interaction` (by using `Interaction.guildpreferred_locale` internally), `Guild` (by using `guild.preferred_locale` internally), or just passing the `Locale` itself, for example, `discord.Locale.american_english` (whichwill convert to the `en-US` locale).
------
# Working with plurals
```py
from discord.ext.localization import Localization
import locale
_ = Localization("main_plurals.json") # this will look for main_plurals.json as the language JSON file
apples = int(input("How many apples do you have? >>> "))
language = locale.getlocale()[0][:2] # this will return the default OS language, such as en, hu, de, fr, es etc.
print(_.one("apples", apples, language, apples=apples))
```
```json
{
"en": {
"apples": ["You only have one apple! What a loser...", "You have {apples} apples!"]
},
"hu": {
"apples": ["{apples} almád van!"]
}
}
```
This example does a great job at presenting how the `.one()` function works. Here's the explanation for the code:
The code will look for the default OS language, and will tell you how many apples you have with plurals in mind. I always get angry when I see "you have 1 apples"-ish text on awebsite, and it's an easy fix, but for some reason, many developers don't pay attention to it.
Hungarian doesn't make a difference between plurals, so the list for "hu"/"apples" only has 1 item. This won't be a problem though - the library isn't hardcoded to only look forthe first and second elements in the returned list, it will look for the **first** and the **last**. Which means that if a list only has 1 item, it will only return that item.
-------
## Advanced usage with nested keys and nested objects
With v1.1.0, we now have the ability to do some **nesting** with the dictionaries.
For example, now that we've learned how to work with plurals, we can also work with nested keys. Here's an example of a nested JSON file:
```json
{
"en": {
"apples": {
"one": "You only have one apple! What a loser...",
"three": "You have three apples! That's a lot!",
"many": "You have {apples} apples!"
}
},
"hu": {
"apples": {
"one": "{apples} almád van!",
"three": "Három almád van! Ez nagyon sok!",
"many": "Van {apples} almád!"
}
}
}
```
We may now use the `localize()` method to get the nested keys, with the `text` argument being a "path" to our string, seperated by dots. Here's an example:
```py
from discord.ext.localization import Localization
_ = Localization("nested.json")
apples = int(input("How many apples do you have? >>> "))
locale = input("What's your locale? >>> ")
if apples == 1:
print(_.localize("apples.one", "one", apples=apples))
# you could use an f-string here, but I'm trying to keep it simple
elif apples == 3:
print(_.localize("apples.three", "three", apples=apples))
else:
print(_.localize("apples.many", "many", apples=apples))
```
Raw data
{
"_id": null,
"home_page": null,
"name": "discord-localization",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "discord.py, i18n, translation, localisation, localization",
"author": "Pearoo",
"author_email": "<contact@pearoo.dev>",
"download_url": "https://files.pythonhosted.org/packages/87/b7/ee6eb51fb7a7c914a30ad533ee8530d212d7954686148ff7861a6e3a5c9a/discord_localization-1.1.4.tar.gz",
"platform": null,
"description": "[Github](https://github.com/PearooXD/discord-localization) | [PyPI](https://pypi.org/project/discord-localization/)\n\n--------\n## Setting up\nStart by downloading the package via pip.\n```\npython3 -m pip install discord-localization\n```\nAfter that, you can just import it into your file as a discord.py extension.\n\n--------\n## Examples\n```py\nfrom discord.ext import localization\nimport random\n\n_ = localization.Localization(\"main.i18n.json\", \"en\")\n# the first option is the relative path to the localization\n# file. the second is the fallback/default language that is\n# used if the actual language is not found.\ndice = random.randint(1, 6)\nlanguage = input(\"What's your native language? / Was ist Deine Muttersprache? (en/de) >>> \")\n\nprint(_(\"dice_result\", language, dice=dice))\n```\n```json\n{\n \"en\": {\n \"dice_result\": \"Your dice rolled {dice}!\"\n },\n \"de\": {\n \"dice_result\": \"Dein W\u00fcrfel hat eine {dice} gew\u00fcrfelt!\"\n }\n}\n```\n\n-------\n## Integrating it into your Discord bot\n```py\nimport discord\nfrom discord.ext import commands, localization\nbot = commands.Bot(command_prefix=\"!\", intents=discord.Intents.all())\n# hey guys, breaking the 4th wall here. please stop using Intents.default()\n# just to set the message_contentintent to True right after. Intents.all() does\n# it for you.\n_ = localization.Localization(\"main_localization.json\", \"en\")\n\n@bot.event\nasync def on_ready():\n print(\"Bot is ready!\")\n\n@bot.command()\nasync def ping(ctx):\n await ctx.reply(_(\"ping\", ctx, latency=bot.latency * 1000))\n```\n```json\n{\n \"en\": {\n \"ping\": \"Pong! {latency}ms\"\n },\n \"en-US\": {\n \"ping\": \"Pong! {latency}ms, but American! (because Discord makes a difference between en-US and en-UK locales - you can circumvent this by setting the default_locale)\"\n },\n \"en-UK\": {\n \"ping\": \"Ping is {latency}ms, innit, bruv? (i'm sorry)\"\n },\n \"fr\": {\n \"ping\": \"Bonjour! Ping is {latency}ms!\"\n }\n}\n```\nExplanation:\n- By setting the default locale to \"en\", we won't have any issues with unfinished localizations. This way, we are also not required to define localizations for both \"en-US\" and\"en-UK\" (since Discord's API differentiates them, however, usually, bots don't.)\n- We are passing a `latency` argument to the localization function (which is also available with `Localization._`! But calling the object is fine too.), which will be later usedwhenever we use `{latency}` in a localization.\n- We are defining an `en` locale in the JSON file, even though both Discord's API and discord.py doesn't have such a locale. This is to make it more obvious that everything inthat locale should be in English - you could also name it `default_locale`, you just have to make sure to edit it in the `Localization` object.\n- We pass `ctx` to the localization function, which will automatically try getting `ctx.guild.preferred_locale`. This works with `Interaction` (by using `Interaction.guildpreferred_locale` internally), `Guild` (by using `guild.preferred_locale` internally), or just passing the `Locale` itself, for example, `discord.Locale.american_english` (whichwill convert to the `en-US` locale).\n------\n# Working with plurals\n```py\nfrom discord.ext.localization import Localization\nimport locale\n\n_ = Localization(\"main_plurals.json\") # this will look for main_plurals.json as the language JSON file\napples = int(input(\"How many apples do you have? >>> \"))\nlanguage = locale.getlocale()[0][:2] # this will return the default OS language, such as en, hu, de, fr, es etc.\n\nprint(_.one(\"apples\", apples, language, apples=apples))\n```\n```json\n{\n \"en\": {\n \"apples\": [\"You only have one apple! What a loser...\", \"You have {apples} apples!\"]\n },\n \"hu\": {\n \"apples\": [\"{apples} alm\u00e1d van!\"]\n }\n}\n```\nThis example does a great job at presenting how the `.one()` function works. Here's the explanation for the code:\nThe code will look for the default OS language, and will tell you how many apples you have with plurals in mind. I always get angry when I see \"you have 1 apples\"-ish text on awebsite, and it's an easy fix, but for some reason, many developers don't pay attention to it.\nHungarian doesn't make a difference between plurals, so the list for \"hu\"/\"apples\" only has 1 item. This won't be a problem though - the library isn't hardcoded to only look forthe first and second elements in the returned list, it will look for the **first** and the **last**. Which means that if a list only has 1 item, it will only return that item.\n\n-------\n## Advanced usage with nested keys and nested objects\nWith v1.1.0, we now have the ability to do some **nesting** with the dictionaries.\n\nFor example, now that we've learned how to work with plurals, we can also work with nested keys. Here's an example of a nested JSON file:\n```json\n{\n \"en\": {\n \"apples\": {\n \"one\": \"You only have one apple! What a loser...\",\n \"three\": \"You have three apples! That's a lot!\",\n \"many\": \"You have {apples} apples!\"\n }\n },\n \"hu\": {\n \"apples\": {\n \"one\": \"{apples} alm\u00e1d van!\",\n \"three\": \"H\u00e1rom alm\u00e1d van! Ez nagyon sok!\",\n \"many\": \"Van {apples} alm\u00e1d!\"\n }\n }\n}\n```\nWe may now use the `localize()` method to get the nested keys, with the `text` argument being a \"path\" to our string, seperated by dots. Here's an example:\n```py\nfrom discord.ext.localization import Localization\n\n_ = Localization(\"nested.json\")\napples = int(input(\"How many apples do you have? >>> \"))\nlocale = input(\"What's your locale? >>> \")\nif apples == 1:\n print(_.localize(\"apples.one\", \"one\", apples=apples))\n # you could use an f-string here, but I'm trying to keep it simple\nelif apples == 3:\n print(_.localize(\"apples.three\", \"three\", apples=apples))\nelse:\n print(_.localize(\"apples.many\", \"many\", apples=apples))\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A discord.py extension for command localization.",
"version": "1.1.4",
"project_urls": {
"Source": "https://github.com/rnxm/discord-localization"
},
"split_keywords": [
"discord.py",
" i18n",
" translation",
" localisation",
" localization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c02c0fbbc5a86c1922ce44388ef309c25540065e1f1a58021cf55592b34abaa1",
"md5": "3fbb3dc1374aa6ce0af7ff6b8a2a793b",
"sha256": "ed3c529235e545a84b0185b6259d6394e1c2e729b4c7c770018330fc9532c75a"
},
"downloads": -1,
"filename": "discord_localization-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3fbb3dc1374aa6ce0af7ff6b8a2a793b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8686,
"upload_time": "2024-12-30T18:15:21",
"upload_time_iso_8601": "2024-12-30T18:15:21.166858Z",
"url": "https://files.pythonhosted.org/packages/c0/2c/0fbbc5a86c1922ce44388ef309c25540065e1f1a58021cf55592b34abaa1/discord_localization-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87b7ee6eb51fb7a7c914a30ad533ee8530d212d7954686148ff7861a6e3a5c9a",
"md5": "8d68fc0728b12f0610edb0aab4c5d35b",
"sha256": "210e6665777585daed4af9b6f39c967f3f1b7a25bf40035e565b1c828943e3fe"
},
"downloads": -1,
"filename": "discord_localization-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "8d68fc0728b12f0610edb0aab4c5d35b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11141,
"upload_time": "2024-12-30T18:15:23",
"upload_time_iso_8601": "2024-12-30T18:15:23.633502Z",
"url": "https://files.pythonhosted.org/packages/87/b7/ee6eb51fb7a7c914a30ad533ee8530d212d7954686148ff7861a6e3a5c9a/discord_localization-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-30 18:15:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rnxm",
"github_project": "discord-localization",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "discord-localization"
}
JSON
