discord-localization 0.1.2__tar.gz

discord_localization-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pearoo
+
+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.

discord_localization-0.1.2/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.1
+Name: discord-localization
+Version: 0.1.2
+Summary: A discord.py extension for command localization.
+Author: Pearoo
+Author-email: <contact@pearoo.dev>
+Project-URL: Source, https://github.com/PearooXD/discord-localization
+Keywords: discord.py,i18n,translation,localisation,localization
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+[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_content intent 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 used whenever 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 in that 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.guild.preferred_locale` internally), `Guild` (by using `guild.preferred_locale` internally), or just passing the `Locale` itself, for example, `discord.Locale.american_english` (which will 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 a website, 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 for the 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.

discord_localization-0.1.2/README.md

@@ -0,0 +1,100 @@
+[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_content intent 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 used whenever 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 in that 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.guild.preferred_locale` internally), `Guild` (by using `guild.preferred_locale` internally), or just passing the `Locale` itself, for example, `discord.Locale.american_english` (which will 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 a website, 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 for the 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.

discord_localization-0.1.2/discord/ext/localization/__init__.py

@@ -0,0 +1,25 @@
+"""
+MIT License
+
+Copyright (c) 2024 Pearoo
+
+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 .localization import Localization as Localization

discord_localization-0.1.2/discord/ext/localization/localization.py

@@ -0,0 +1,137 @@
+import json
+import logging
+import os
+from typing import Any, List, Optional, Union
+from sys import argv
+from discord import Guild, Locale, Interaction
+from discord.ext.commands import Context
+
+class Localization:
+    """discord.py extension for command localization."""
+    
+    def __init__(self, relative_path: str, default_locale: Optional[str] = None, error: Optional[bool] = False) -> None:
+        """
+        Represents a localization object.
+        
+        -------
+        ### Parameters:
+            relative_path: :class:`str`
+                The name of the file to load the localizations from. This must be a JSON file.
+            default_locale: Optional[:class:`str`]
+                The default locale to use if the locale is not found in the localization.
+            error: Optional[:class:`bool`]
+                Whether to raise an error if the localization is not found. If set to `False`, it will return the key itself. Defaults to `False`.
+        """
+        script_path = os.path.abspath(argv[0])
+        script_dir = os.path.dirname(script_path)
+        
+        self.relative_path: str = os.path.join(script_dir, relative_path)
+        self.default_locale: str = default_locale
+        self.error: bool = error
+        
+        try:
+            with open(self.relative_path, "r", encoding="utf-8") as f:
+                self.file: dict = json.load(f)
+        except json.JSONDecodeError:
+            raise ValueError("invalid JSON format in translation file: {}".format(self.relative_path))
+
+    def localize(self, text: str, locale: Union[str, Locale, Guild, Interaction, Context], **kwargs: Any) -> Union[str, List[str]]:
+        """
+        Gets the localization of a string like it's done in i18n.
+        
+        -------
+        ### Parameters:
+            text: :class:`str`
+                The key to find in the localization file.
+            locale: Union[:class:`str` | :class:`discord.Locale` | :class:`discord.Guild` | :class:`discord.Interaction` | :class:`discord.commands.ext.Context`]
+                The locale to find the localization with, or an object that has an attribute that returns :class:`discord.Locale`.
+            **kwargs: :class:`Any`
+                The arguments to pass to the string formatter.
+        
+        -------
+        ### Returns:
+            :class:`str`
+                The localized string.
+            List[:class:`str`]
+                If the localization is a list, it returns the list of localized strings.
+        """
+        if isinstance(locale, Guild):
+            locale = str(locale.preferred_locale)
+        elif isinstance(locale, (Interaction, Context)):
+            locale = str(locale.guild.preferred_locale)
+        elif isinstance(locale, (Locale, str)):
+            locale = str(locale)
+        else:
+            raise TypeError("locale must be of type str, discord.Locale, discord.Guild, discord.Interaction, or discord.ext.commands.Context, received {}".format(type(locale)))
+        
+        localizations = self.file.get(locale) or self.file.get(self.default_locale)
+        if not localizations:
+            if self.error:
+                raise KeyError("no localizations for language {}".format(locale))
+            else:
+                logging.error("No localizations for language {}".format(locale))
+                return text
+        
+        localized_text = localizations.get(text)
+        if localized_text:
+            if isinstance(localized_text, list):
+                return [localized_item.format(**kwargs) for localized_item in localizations[text]]
+            return localized_text.format(**kwargs)
+        else:
+            if self.error:
+                raise KeyError("localization \"{}\" not found for language {}".format(text, locale))
+            else:
+                logging.error("Localization \"{}\" not found for language {}".format(text, locale))
+                return text
+    
+    _ = t = translate = localise = localize
+    
+    def one(self, text: str, number: Union[int, float], locale: str, **kwargs: Any) -> str:
+        """
+        Gets the singular and plural form of a string like it's done in i18n.
+        
+        For this, you need to have the key in the JSON be a list of two strings, the first being the singular form, the second being the plural form.
+        
+        -------
+        ### Parameters:
+            text: `str`
+                The key to find in the localization file.
+            locale: Union[:class:`str` | :class:`discord.Locale` | :class:`discord.Guild` | :class:`discord.Interaction` | :class:`discord.commands.ext.Context`]
+                The locale to find the localization with, or an object that has an attribute that returns :class:`discord.Locale`.
+            number: Union[`int`, `float`]
+                The number to determine whether to use the singular or plural form.
+            **kwargs: `Any`
+                The arguments to pass to the string formatter.
+                
+        -------
+        ### Returns:
+            `str` If `num` is 1, returns the first item of the list. Otherwise, it returns the last item of the list. If the list only has 1 item, it returns that item.
+        """
+        if isinstance(locale, Guild):
+            locale = str(locale.preferred_locale)
+        elif isinstance(locale, (Interaction, Context)):
+            locale = str(locale.guild.preferred_locale)
+        elif isinstance(locale, (Locale, str)):
+            locale = str(locale)
+        else:
+            raise TypeError("locale must be of type str, discord.Locale, discord.Guild, discord.Interaction, or discord.ext.commands.Context, received {}".format(type(locale)))
+        
+        localized_text = self.localize(text, locale, **kwargs)
+        if not isinstance(localized_text, list):
+            raise TypeError("translation for \"{}\" is not a list".format(text))
+        
+        if not localized_text:
+            if self.error:
+                raise KeyError("localization \"{}\" not found for language {}".format(text, locale))
+            else:
+                logging.error("Localization \"{}\" not found for language {}".format(text, locale))
+                return text
+        
+        if number == 1:
+            return localized_text[0]
+        else:
+            return localized_text[-1]
+        
+    _o = o = one
+    
+    __call__ = localize

discord_localization-0.1.2/discord_localization.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.1
+Name: discord-localization
+Version: 0.1.2
+Summary: A discord.py extension for command localization.
+Author: Pearoo
+Author-email: <contact@pearoo.dev>
+Project-URL: Source, https://github.com/PearooXD/discord-localization
+Keywords: discord.py,i18n,translation,localisation,localization
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+[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_content intent 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 used whenever 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 in that 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.guild.preferred_locale` internally), `Guild` (by using `guild.preferred_locale` internally), or just passing the `Locale` itself, for example, `discord.Locale.american_english` (which will 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 a website, 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 for the 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.

discord_localization-0.1.2/discord_localization.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+discord/ext/localization/__init__.py
+discord/ext/localization/localization.py
+discord_localization.egg-info/PKG-INFO
+discord_localization.egg-info/SOURCES.txt
+discord_localization.egg-info/dependency_links.txt
+discord_localization.egg-info/top_level.txt
+tests/test.py

discord_localization-0.1.2/discord_localization.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

discord_localization-0.1.2/discord_localization.egg-info/top_level.txt

@@ -0,0 +1 @@
+discord

discord_localization-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

discord_localization-0.1.2/setup.py

@@ -0,0 +1,29 @@
+from setuptools import setup
+from pathlib import Path
+import os
+
+VERSION = '0.1.2'
+DESCRIPTION = 'A discord.py extension for command localization.'
+
+# Setting up
+setup(
+    name="discord-localization",
+    version=VERSION,
+    author="Pearoo",
+    author_email="<contact@pearoo.dev>",
+    description=DESCRIPTION,
+    long_description_content_type="text/markdown",
+    long_description=Path("README.md").read_text(),
+    packages=["discord.ext.localization"],
+    install_requires=[],
+    keywords=['discord.py', 'i18n', 'translation', 'localisation', 'localization'],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent"
+    ],
+    project_urls={
+        "Source": "https://github.com/PearooXD/discord-localization"
+    }
+)
+# command: python setup.py sdist bdist_wheel

discord_localization-0.1.2/tests/test.py

@@ -0,0 +1,5 @@
+from discord.ext import localization
+import logging
+
+_ = localization.Localization("test_lang.json")._
+print(_("hello", "hu"))