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.

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

• Other strings can be localized with the I18N class

Warning

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

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

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

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

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("commands.yaml", encoding="utf-8") as file:
    localizations = yaml.safe_load(file)

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

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

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

Localize Strings

Create a language file (in this case en.yaml) with the following structure:

• Create a key for every file name

• Inside the file name keys, you can create a key for every method name where you need to localize strings. You can use the class name as well, that’s useful for Views or Modals.

• Now you can create a key-value pair for every string that you want to localize.

Variables can be defined in the language file with curly braces.

Note

The following variable types are available. You can find examples for all types below.

• General: Can be used anywhere in the language file and in the code

• General, but inside a file name key: Can be used within this file name key by placing a dot before the variable

• Method specific: These variables are specified in the code and will be replaced with the given value

If general values are used within the language file, they are replaced with their value when the language file is loaded.

en.yaml

general:
  # General values can be accessed from anywhere
  accept: Accept
  decline: Decline
  cookie:
    one: Cookie
    many: Cookies  # Specify the plural form

example_cog:
  general:
    example: example

  command1:
    welcome:
      # Use lists to select a random message from the list
      - Hey {user}
      - Hi {user}

    embed1:
      # Use general variables (global or from the current cog)
      # In comparison to dynamic variables like {user},
      #   general variables are inserted when the language file is loaded
      title: "{accept} the cookie?"
      description: This is an {.example} text!

# 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 in multiple ways.

• You can use the t() function to get a localized string

• You can use the TEmbed class if you want to define the embed in the language file

• You can simply use the language file keys as message content

• You can even use language file keys directly in embeds, views and modals. Just make sure that the key is in the language file matches the current method or class name.

Variables can be passed directly to all send/edit methods like ctx.respond like in the example below. You can also pass variables to t() or TEmbed.

example_cog.py

import discord
from discord.commands import slash_command

import ezcord


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

    @slash_command()
    async def command1(self, ctx: ezcord.EzContext):
        embed = ezcord.TEmbed("embed1", color=discord.Color.blurple())
        await ctx.respond("welcome", embed=embed, user=ctx.user.mention)


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