Crear un bot de Discord#10¡Añade soporte multilingüe (i18n)! (ejemplo en Python)

¡Hola! Soy Mojangcam 😎

En el #9 conectamos la IA (API de Claude y ChatGPT) a nuestro bot y creamos un bot con el que puedes conversar, ¿verdad? En este episodio vamos a convertir nuestro bot en un bot global. ¡Se trata del soporte multilingüe (i18n)!

Si administras un servidor de juego con jugadores de otros países, un bot que solo responde en coreano se queda corto. Cada usuario de Discord tiene su propia configuración de idioma del cliente, y si la lees puedes crear un bot que responda automáticamente en coreano a los usuarios coreanos y en inglés a los extranjeros. ¡Incluso puedes mostrar el nombre y la descripción de los slash commands de forma distinta en cada idioma!

🧠 ¿Qué es i18n y por qué lo necesitas?

i18n es la abreviatura de internationalization (internacionalización). Se llama i18n porque entre la i y la n hay 18 letras 💡

En un bot de Discord, los momentos en los que necesitas i18n son más de los que crees.

• Un bot de avisos para un servidor de juego (Minecraft, ARK, etc.) con jugadores de otros países
• Un bot público que se instala en servidores de muchos países
• Cuando quieres mostrar la descripción de los comandos en el idioma del usuario para que le cueste menos empezar

discord.py ya trae esto integrado. ¡Solo necesitas conocer dos cosas: interaction.locale (el idioma del usuario) y Translator (el traductor de comandos)!

📌 Lo que necesitas

• Python 3.8 o superior
• discord.py 2.x (este artículo usa la última versión, la 2.7.1)
• El token del bot + un servidor de pruebas al que hayas invitado al bot (consulta el #1)

pip install -U discord.py

📌 Paso 1 - Averigua el idioma del usuario (interaction.locale)

Cuando se ejecuta un slash command, Discord envía también la información de idioma de ese usuario. Primero veamos qué valor llega.

@bot.tree.command(name="lang", description="Ver mi configuración de idioma")
async def lang(interaction: discord.Interaction):
    await interaction.response.send_message(
        f"Idioma del cliente: {interaction.locale}"
    )

Vamos a verlo parte por parte 💡

• interaction.locale : es la configuración de idioma de la app de Discord del usuario que ejecutó el comando. Un cliente en coreano envía ko, uno en inglés (EE. UU.) envía en-US y uno en japonés envía ja.
• interaction.guild_locale : este no es el idioma del usuario, sino el idioma predeterminado del servidor (guild). Viene bien para mensajes a nivel de servidor, como los anuncios.
• El tipo que devuelve es un enum llamado discord.Locale, y si lo envuelves con str() se convierte en una cadena como 'ko'.

📌 Paso 2 - Cambia los mensajes de respuesta con un diccionario de traducciones

Ahora vamos a crear un diccionario de traducciones (dict) con la respuesta para cada idioma, y a elegir y enviar el mensaje que corresponda a interaction.locale.

RESPONSES = {
    "ko": "안녕하세요, {user}님! 만나서 반가워요 🙌",
    "ja": "こんにちは、{user}さん！",
    "en-US": "Hello, {user}! Nice to meet you 🙌",
}
DEFAULT_LOCALE = "en-US"

@bot.tree.command(name="hello", description="Send a friendly greeting")
async def hello(interaction: discord.Interaction):
    lang = str(interaction.locale)
    template = RESPONSES.get(lang, RESPONSES[DEFAULT_LOCALE])
    await interaction.response.send_message(
        template.format(user=interaction.user.display_name)
    )

Vamos a verlo parte por parte 💡

• RESPONSES : un diccionario de traducciones que usa los códigos de idioma como claves. Si quieres añadir un idioma, basta con agregar una línea aquí.
• RESPONSES.get(lang, predeterminado) : si llega un idioma que no está en el diccionario (por ejemplo, el francés fr), el bot responde en el idioma predeterminado (inglés). ¡Es la red de seguridad clave del manejo multilingüe!
• {user} + format() : un marcador de posición para insertar variables como el apodo dentro del mensaje.

📌 Paso 3 - Traduce también el nombre y la descripción de los comandos (Translator)

Cambiar solo las respuestas es quedarse a medias. ¿No sería mejor que los usuarios coreanos vieran el propio comando como /인사? Para eso sirve app_commands.Translator.

from discord import app_commands
from discord.app_commands import locale_str as _T

COMMAND_I18N = {
    "ko": {
        "hello": "인사",
        "Send a friendly greeting": "봇이 반갑게 인사를 건네요",
    },
    "ja": {
        "hello": "あいさつ",
        "Send a friendly greeting": "ボットがあいさつします",
    },
}

class MyTranslator(app_commands.Translator):
    async def translate(self, string, locale, context):
        # Si hay traducción, devuelve el texto traducido; si no, None (se mantiene el original)
        return COMMAND_I18N.get(str(locale), {}).get(string.message)

Vamos a verlo parte por parte 💡

• locale_str (_T) : un marcador que indica "esta cadena se debe traducir". Al crear un comando, la envuelves así: name=_T("hello").
• Translator : cuando registras (sync) los comandos en el servidor, se llama a translate() para todos los idiomas que admite Discord. Si no hay traducción, devuelve None y se usa el texto original tal cual.
• string.message : es la cadena original que envolviste con _T(). La usas como clave para buscar en el diccionario de traducciones.
• ⚠️ Las reglas de los nombres de comandos también se aplican a las traducciones. ¡Nada de espacios, y las letras en inglés solo en minúscula! (el coreano y el japonés están bien tal cual)

Por último, registra el traductor antes de sync cuando arranque el bot.

@bot.event
async def on_ready():
    await bot.tree.set_translator(MyTranslator())  # ¡Siempre antes de sync!
    await bot.tree.sync()
    print(f"¡{bot.user} ha iniciado sesión!")

📌 Código completo (puedes copiar y pegar)

# discord.py 2.7.x / Python 3.8+
from typing import Optional

import discord
from discord import app_commands
from discord.app_commands import locale_str as _T
from discord.ext import commands

intents = discord.Intents.default()
bot = commands.Bot(command_prefix="!", intents=intents)

# Traducciones de nombres y descripciones de comandos (las usa Translator)
COMMAND_I18N = {
    "ko": {
        "hello": "인사",
        "Send a friendly greeting": "봇이 반갑게 인사를 건네요",
    },
    "ja": {
        "hello": "あいさつ",
        "Send a friendly greeting": "ボットがあいさつします",
    },
}

# Traducciones de los mensajes de respuesta (se eligen con interaction.locale)
RESPONSES = {
    "ko": "안녕하세요, {user}님! 만나서 반가워요 🙌",
    "ja": "こんにちは、{user}さん！",
    "en-US": "Hello, {user}! Nice to meet you 🙌",
}
DEFAULT_LOCALE = "en-US"

class MyTranslator(app_commands.Translator):
    async def translate(
        self,
        string: app_commands.locale_str,
        locale: discord.Locale,
        context: app_commands.TranslationContext,
    ) -> Optional[str]:
        return COMMAND_I18N.get(str(locale), {}).get(string.message)

@bot.tree.command(name=_T("hello"), description=_T("Send a friendly greeting"))
async def hello(interaction: discord.Interaction):
    lang = str(interaction.locale)  # p. ej.: 'ko', 'ja', 'en-US'
    template = RESPONSES.get(lang, RESPONSES[DEFAULT_LOCALE])
    await interaction.response.send_message(
        template.format(user=interaction.user.display_name)
    )

@bot.event
async def on_ready():
    await bot.tree.set_translator(MyTranslator())  # ¡Siempre antes de sync!
    await bot.tree.sync()
    print(f"¡{bot.user} ha iniciado sesión!")

bot.run("Pon aquí el token de tu bot")

📌 Resultado

Ejecuta el bot y prueba a escribir el comando...

• Cliente en coreano: en la lista de comandos aparece como /인사 - 봇이 반갑게 인사를 건네요 ("/saludo - El bot te saluda con alegría"), y al ejecutarlo responde "안녕하세요, ○○님! 만나서 반가워요 🙌" ("¡Hola, ○○! Encantado de conocerte 🙌")
• Cliente en inglés: aparece como /hello - Send a friendly greeting y responde "Hello, ○○! Nice to meet you 🙌"
• Cliente en japonés: ¡aparece como /あいさつ! Es el mismo comando, pero se ve completamente distinto en cada idioma.

¡Prueba también a ejecutarlo en un idioma que no esté en el diccionario de traducciones (francés, etc.) y comprueba que responde en inglés, el idioma predeterminado!

📌 Errores frecuentes

1. El nombre del comando no se traduce y solo aparece en inglés Causa: llamaste a set_translator() después de sync(), o no volviste a sincronizar después de registrar el traductor. Las traducciones se aplican en el momento del sync. Solución: respeta el orden await bot.tree.set_translator(...) → await bot.tree.sync() y recarga el cliente de Discord con Ctrl+R. Puede tardar unos minutos en reflejarse.
2. Sale el error 400 Bad Request (CommandSyncFailure) durante el sync Causa: el nombre de comando traducido no cumple las reglas de Discord. Los nombres de comandos no pueden llevar espacios, y tampoco se permiten mayúsculas en inglés. Solución: revisa la parte de los nombres de comandos en el diccionario de traducciones. "인사 하기" (con espacio ❌) → "인사하기" (⭕), "Hello" (mayúscula ❌) → "hello" (⭕)
3. interaction.locale siempre sale como en-US Causa: locale no se basa en el idioma del servidor, sino en la configuración de idioma de la app de Discord de cada usuario. Si tu app está en inglés, que salga en-US es lo normal. Solución: ve a Ajustes de Discord → Idioma, cámbialo a coreano y vuelve a probar. Si necesitas el idioma del servidor, usa interaction.guild_locale.

📌 Para terminar

Hoy creamos un bot multilingüe en 3 pasos: leer el idioma del usuario con interaction.locale, cambiar las respuestas con un diccionario de traducciones y traducir el nombre y la descripción de los comandos con Translator. Con solo añadir una línea por idioma al diccionario puedes admitir cualquier idioma, ¡así que amplíalo según lo que necesite tu servidor!

En el próximo episodio veremos cooldowns y gestión de permisos para evitar que se abuse de los comandos. ¡No te lo pierdas! 🙌

📚 Serie Crear un bot de Discord

1. Crear un bot de Discord - ¡Domina por completo los Slash Commands!
2. Crear un bot de Discord #2 - ¡Añade opciones (argumentos) a tus Slash Commands!
3. Crear un bot de Discord #3 - ¡Añade subcomandos (Subcommand) a tus Slash Commands!
4. Crear un bot de Discord #4 - ¡Envía embeds con Slash Commands!
5. Crear un bot de Discord #5 - Implementa interacciones con botones (Button)
6. Crear un bot de Discord #6 - Implementa menús desplegables (Select Menu)
7. Crear un bot de Discord #7 - Pide texto al usuario con un modal (Modal)
8. Crear un bot de Discord #8 - Decora embeds (Embed) con imágenes y campos
9. Crear un bot de Discord #9 - Integra la IA (API de Claude y ChatGPT)
10. Crear un bot de Discord #10 - Añade soporte multilingüe (i18n) ← ¡estás leyendo este!