Internationalization (i18n)
Relevant source files
The following files were used as context for generating this wiki page:
Internationalization (i18n) provides the framework for translating the bot's interface, command responses, and documentation into multiple languages. It allows the bot to adapt its output based on global settings, server-specific configurations, or user preferences.
The system utilizes standard gettext-based translation files and manages locale-aware contexts for both text and regional formatting (such as dates and numbers).
Core Architecture
The i18n system manages translations through a global state and contextual variables. It uses Python's contextvars to maintain thread-safe, asynchronous-friendly locale information.
Translation Management Flow
The bot loads translations from .mo files located within specific cog or core directories. The Translator class serves as the primary interface for developers to mark strings for translation.
The diagram shows the logic used to determine which locale to apply when a string is translated.
Sources: redbot/core/i18n.py:44-93, redbot/core/_i18n.py:16-52
Contextual Locales
Red supports different locales for different contexts. The system tracks two distinct types of internationalization settings:
- Locale: Controls the language used for text strings.
- Regional Format: Controls the formatting of dates, times, and numbers.
Sources: redbot/core/i18n.py:114-142, redbot/core/core_commands.py:1115-1150
Key Components
Translator Class
The Translator class is instantiated with a domain name and a file path. It acts as a callable that retrieves the translation for a given string based on the current context.
| Feature | Description |
|---|---|
| Domain | Typically the name of the cog or "Core". |
| Contextual lookup | Checks _current_locale context variable first. |
| Fallback | Defaults to the global locale set in the bot configuration. |
Sources: redbot/core/i18n.py:44-100
Internationalization Settings
The bot manages global and server-specific settings via the Core cog.
| Command Group | Scope | Description |
|---|---|---|
[p]set locale global | Global | Sets the default language for the entire bot instance. |
[p]set locale server | Guild | Overrides the bot's language for a specific server. |
[p]set regionalformat global | Global | Sets the default date/number formatting. |
[p]set regionalformat server | Guild | Overrides date/number formatting for a specific server. |
Sources: redbot/core/core_commands.py:1020-1175
Event Handling and Context Switching
The bot automatically updates the translation context based on incoming messages.
Message Processing
During the on_message event, the bot identifies the guild where the message originated and updates the contextvars for the translation task.
The sequence shows how the bot ensures the correct language is used before executing any command logic.
Sources: redbot/core/_events.py:476-480, redbot/core/i18n.py:145-165
Implementation for Cogs
Cogs utilize the @cog_i18n decorator to register their translator with the core system. This ensures that strings within the cog class are correctly processed.
Example Integration
from redbot.core.i18n import Translator, cog_i18n
_ = Translator("ExampleCog", __file__)
@cog_i18n(_)
class ExampleCog(commands.Cog):
async def some_command(self, ctx):
await ctx.send(_("This string is translatable."))
Sources: redbot/cogs/general/general.py:34-36, redbot/core/i18n.py:103-111
Translation Functions
The system provides several utility functions for managing locales programmatically:
| Function | Actor | Description |
|---|---|---|
set_contextual_locale(target_locale) | System | Updates the _current_locale context variable. |
get_locale() | Translator | Returns the current active locale (contextual or global). |
get_regional_format() | System | Returns the current active regional format code. |
reload_locales() | Core | Clears internal translation caches to force a reload from disk. |
Sources: redbot/core/i18n.py:114-142, redbot/core/_i18n.py:55-82
Summary
The i18n system in Red-DiscordBot enables seamless multi-language support by combining a robust gettext backend with an asynchronous context management layer. By separating text language from regional formatting, the bot provides a localized experience that respects server-specific requirements while maintaining a global fallback for consistency. Contributors can extend translations by providing localized .mo files, which the bot dynamically loads based on the active context.