Localization

You can localize commands and strings with EzCord. More information can be found in the Localization Documentation. This is currently only available for Pycord.

Warning

The following cases can’t get the current locale automatically. You can use the locale parameter to pass an object to extract the locale automatically.

• followup.send - Use interaction.respond instead (or pass the interaction manually using the locale argument

• followup.edit_message - Pass the interaction manually using the locale argument

• DMs - Pass a localizable object manually using the locale argument

Localize Commands

You can localize commands by passing a dictionary of all commands and groups to localize_commands().

In this example, the commands are stored in commands.yaml. Create a key for every command and group that you want to localize. The key is the name of the command or group.

commands.yaml

en-US:
  greet:
    # The name can be omitted if it's the same as the default name
    description: Greet someone
    options:
      user:
        name: user  # The line can be omitted because "user" is the default name
        description: The user you want to greet.

  example_group:  # SlashCommandGroup
    group_greet:
      description: Greeting with a SlashCommandGroup

de:
  greet:
    name: begrüßung
    description: Begrüße einen User
    options:
      user:
        description: Der User, den du begrüßen möchtest.

  example_group:
    group_greet:
      name: gruppen_begrüßung
      description: Begrüßung mit einer SlashCommandGroup

  cogs:
    # Cogs names and descriptions can be localized as well
    # This is useful for the help command
    Miscellaneous:
      name: Sonstiges
      description: Sonstige Befehle

main.py

import yaml

import ezcord

with open("en.yaml", encoding="utf-8") as file:
    en = yaml.safe_load(file)

string_locals = {"en": en}
ezcord.i18n.I18N(string_locals)


with open("commands.yaml", encoding="utf-8") as file:
    cmd_locales = yaml.safe_load(file)


if __name__ == "__main__":
    bot = ezcord.Bot()
    bot.load_cogs()
    bot.localize_commands(cmd_locales)  # Must be called after all commands and cogs are loaded
    bot.run()

Localize Strings

Strings can be localized by calling I18N like in the example above. Create a language file (in this case en.yaml) and define all strings that you want to localize.

Variables can be defined with curly braces, as shown in the example below.

en.yaml

general:
  # Uppercase general values can be used anywhere in the language file with curly braces
  # and will be replaced when the language file is loaded.
  COOKIE: Cookie

example:
  command1:
    welcome:
      # Use lists to select a random message from the list.
      # The user variable can be set in the Discord bot code.
      - Hey {user}
      - Hi {user}

    welcome_cookie:
      one: This greeting comes with a {COOKIE}.
      many: These greetings come with many {COOKIE}s.  # Specify plural form

# You can also localize the embed for the Ezcord help command.
help:
  embed:
    title: Localized Help Command
    description: This is a localized help command

Usage Example

The language file keys can be used almost everywhere throughout the Discord bot. You can see some examples below.

example_cog.py

import discord
from discord.commands import slash_command

import ezcord


class ExampleCog(ezcord.Cog):
    def __init__(self, bot: ezcord.Bot):
        self.bot = bot

    @slash_command()
    async def example_cmd(self, ctx: ezcord.EzContext):
        # Keys from the language file will be auto-translated.
        await ctx.respond("example.command1.welcome", user=ctx.user.mention)

        # You can use multiple keys and other values in the same string.
        await ctx.respond("🍪 {example.command1.welcome}", user=ctx.user.mention)

        # Strings can also be loaded directly.
        text = ctx.t("example.command1.welcome", user=ctx.user.mention)
        await ctx.respond(text)

        # If ctx is not available, you can use other types to determine the language.
        text = ezcord.t(ctx.interaction, "example.command1.welcome", user=ctx.user.mention)
        await ctx.respond(text)

        # The count variable is used for pluralization.
        await ctx.respond("🍪 {example.command1.welcome_cookie}", count=1)

        # Keys can be used in other places as well.
        embed = discord.Embed(title="example.command1.welcome")
        view = discord.ui.View(discord.ui.Button(label="example.command1.welcome"))
        await ctx.respond(embed=embed, view=view)


def setup(bot: ezcord.Bot):
    bot.add_cog(ExampleCog(bot))