pycord-localizer

A pycord extension for internationalization and localization.

Installation

# linux / macOS
pip3 install pycord-localizer

# windows
pip install pycord-localizer

Quick Start

1. Create a Locales Folder

Instead of one file per language, organize translations by feature/domain. Each file holds every locale it needs, keyed by category first (strings, commands, context_menus) and locale second:

locales/
    info.json
    music.json
    roles.json

locales/info.json

{
    "strings": {
        "zh-TW": {
            "Hello, world!": "你好，世界！"
        },
        "zh-CN": {
            "Hello, world!": "你好，世界！"
        }
    },
    "commands": {
        "greet": {
            "zh-TW": {
                "name": "問候",
                "description": "向使用者問候",
                "options": {
                    "user": {
                        "name": "使用者",
                        "description": "選擇要問候的使用者"
                    }
                }
            }
        }
    },
    "context_menus": {
        "user_info": {
            "zh-TW": {
                "name": "使用者資訊"
            }
        }
    }
}

Files are merged together, so multiple files may contribute strings, commands, or context menus for the same locale.

2. Setup in Your Bot

from discord import Bot, Option
from pycord_localizer import I18n, t

# Create bot and load every file under locales/
bot = Bot()
i18n = I18n(bot, locales_dir="locales")

# Define commands
@i18n.localize
@bot.slash_command()
async def greet(ctx, user: Option(discord.Member, "Select a user")):
    await ctx.respond(t("Hello, {0}!", user.mention))

bot.run("YOUR_TOKEN")

Alternative: One File per Locale

The original per-locale file format is still supported, either loaded manually or merged in alongside locales_dir:

import json
from pycord_localizer import I18n

with open("zh-TW.json", encoding="utf-8") as f:
    zh_tw = json.load(f)

i18n = I18n(bot, zh_TW=zh_tw)

// zh-TW.json
{
    "strings": {
        "Hello, world!": "你好，世界！"
    },
    "commands": {
        "greet": {
            "name": "問候",
            "description": "向使用者問候"
        }
    }
}

Documentation

Supported Locales

"id", "da", "de", "en-GB", "en-US", "es-ES", "es-419", "fr", "hr", "it", 
"lt", "hu", "nl", "no", "pl", "pt-BR", "ro", "fi", "sv-SE", "vi", "tr", 
"cs", "el", "bg", "ru", "uk", "hi", "th", "zh-CN", "ja", "zh-TW", "ko"

Localization Structure

Locales folder format (category first, locale second — for locales_dir):

{
    "strings": {
        "locale_code": {
            "key": "translated text",
            "format {0}": "格式化 {0}"
        }
    },
    "commands": {
        "command_name": {
            "locale_code": {
                "name": "localized_name",
                "description": "localized_description",
                "options": {
                    "option_name": {
                        "name": "localized_option",
                        "description": "localized_description",
                        "choices": {
                            "choice_value": "localized_choice_name"
                        }
                    }
                }
            }
        }
    },
    "context_menus": {
        "context_menu_name": {
            "locale_code": {
                "name": "localized_menu_name"
            }
        }
    }
}

Single-locale file format (for files loaded manually and passed as **translations):

{
    "strings": {
        "key": "translated text",
        "format {0}": "格式化 {0}"
    },
    "commands": {
        "command_name": {
            "name": "localized_name",
            "description": "localized_description",
            "options": {
                "option_name": {
                    "name": "localized_option",
                    "description": "localized_description",
                    "choices": {
                        "choice_value": "localized_choice_name"
                    }
                }
            }
        }
    },
    "context_menus": {
        "context_menu_name": {
            "name": "localized_menu_name"
        }
    }
}

Examples

Slash Command with Choices

from discord import Option, OptionChoice

@i18n.localize
@bot.slash_command()
async def language(
    ctx,
    lang: Option(
        str,
        "Choose your preferred language",
        choices=[
            OptionChoice(name="English", value="en-US"),
            OptionChoice(name="Traditional Chinese", value="zh-TW"),
            OptionChoice(name="Japanese", value="ja"),
            OptionChoice(name="German", value="de"),
        ]
    )
):
    await ctx.respond(f"Language set to: {lang}")

Localization file:

{
    "commands": {
        "language": {
            "name": "語言",
            "description": "選擇你的偏好語言",
            "options": {
                "lang": {
                    "name": "語言",
                    "description": "選擇你偏好的語言",
                    "choices": {
                        "en-US": "英文",
                        "zh-TW": "繁體中文",
                        "ja": "日文",
                        "de": "德文"
                    }
                }
            }
        }
    }
}

Context Menu Commands

# User command (right-click on user)
@i18n.localize
@bot.user_command(name="user_info")
async def user_info(ctx, member):
    await ctx.respond(_("User: {0}", member.name))

# Message command (right-click on message)
@i18n.localize
@bot.message_command(name="get_id")
async def get_id(ctx, message):
    await ctx.respond(_("Message ID: {0}", message.id))

Batch Localization

Instead of decorating each command, you can localize all at once:

# Define all commands first
@bot.slash_command()
async def hello(ctx):
    await ctx.respond(_("Hello!"))

@bot.user_command(name="user_info")
async def user_info(ctx, member):
    await ctx.respond(f"User: {member.name}")

# Then localize all commands
i18n.localize_commands()

String Formatting

# Simple formatting
await ctx.respond(_("Hello, {0}!", user.name))

# Multiple arguments
await ctx.respond(_("User {0} has {1} points", name, points))

User vs Server Locale

# Default: Use server locale
i18n = I18n(bot, zh_TW=zh_tw)

# Use user's preferred locale
i18n = I18n(bot, consider_user_locale=True, zh_TW=zh_tw)