BabelBot DocsHow BabelBot translates Discord messages
Learn when BabelBot translates Discord messages automatically, when it skips, and how quotas and bridges behave.
This page explains how BabelBot behaves. Use it when a translation is missing, when output feels noisy, or when you want to know what counts toward your plan. For step-by-step fixes, see Troubleshooting. For plan numbers, see Billing and Limits.
End-to-end pipeline
When someone posts in an enabled guild text channel, BabelBot runs through roughly this sequence:
- Eligibility: Is the server on, the channel allowed, and the message worth translating?
- Content gathering: Plain message text plus any text inside rich embeds (titles, descriptions, fields, and footers) is collected together. This covers embeds posted by bots, such as a rules or announcement card, but not the automatic preview Discord adds under a plain link. Embed translation works on every plan and counts the same as a normal translation.
- Bridge routing: If the channel is part of a bridge, delivery may go to a paired channel instead of (or as well as) local target languages.
- Attachment policy: Supported PDFs, images, video attachments, and audio files follow different rules than plain text (paid media translation on Pro and above). If a message has several supported images, BabelBot translates each image in order. Unsupported file types are not sent through the media translator. If attached media cannot be translated but the message text can, BabelBot can still post the text translation with a short partial notice.
- Source language exclusions: Normal automatic messages can be skipped before quota when the detected source language is on Don't translate from.
- Quota: AI-backed work checks your plan’s AI translation allowance.
- Provider: Plain text uses AI (OpenRouter) when quota is available, or Custom BabelBot Translation Model on eligible tiers after AI quota is used (LibreTranslate-backed). Plain text bridge messages can also use the Custom BabelBot Translation Model if AI hits a technical error before returning a usable translation.
- Translation: One run per target language (or bridge destination language).
- Post-validation: Drop results that are empty or already in the target language.
- Delivery: Post as channel replies or inside a translation thread, depending on your delivery settings.
- Usage: Record quota only when a translation is actually posted.
Usage does not increase when BabelBot skips a message or drops output after translation.
Recent context for AI translation
Automatic AI translation can use up to five previous eligible human text messages from the same channel or thread to understand pronouns, slang, and ambiguous wording. BabelBot caps each message at 200 graphemes (visible characters) and keeps this context in Redis for up to 15 minutes. BabelBot does not fetch older Discord history.
Recent message context applies only to normal automatic AI translations. Bridge translations and the Custom BabelBot Translation Model do not use it. BabelBot asks the AI to translate only the current message. If the result appears to repeat recent context, BabelBot blocks that result and retries the current message once without recent context.
When messages are skipped
BabelBot does not call a translator when:
- The server master switch is off
- The channel is on the server’s disabled-channel list (see Dashboard Guide)
- The author is a bot, except native Discord followed-announcement crossposts (see below) or a bot you added to Translate other bots in the Dashboard Guide. BabelBot always ignores its own messages.
- The author is on the server’s ignored-users list
- The message is not in a guild channel (automatic flow is guild-only)
- Content is not translatable: whitespace-only, link-only without attachments, UUIDs/snowflakes, or similar non-linguistic tokens
- Attachments are present but media translation is off or the plan does not allow it (media-only messages on free tier)
- A normal automatic message is confidently detected as a language in Don't translate from
- AI quota is exhausted and no fallback applies (for example attachments that require AI)
BabelBot may run translation but not post a translation when:
- Detected source language already matches the target (this stays silent)
When BabelBot receives missing, empty, or duplicated output for target languages on a regular automatic message, it can add a Retry button. If some languages worked, the button appears on the Partial translation notice. If none worked, it appears on the Translation failed notice. Retry asks for the failed target languages, leaves source-language targets out, and stays available for about 1 minute. If BabelBot asks you to wait, wait for the cooldown and click Retry again. That wait does not use up the retry. If delivery fails after your click is accepted, BabelBot sends you a private note. Bridge translations keep their existing behavior and do not get a retry button.
When BabelBot started translating but could not produce usable output for any target, it posts a short failure notice instead of staying silent. Retryable failure notices can include Retry. Failure notices do not count toward usage.
“Missing” translations are often correct skips. Compare the message to the lists above before assuming a bug.
Reply mode and thread mode
| Scenario | Reply in channel | Reply in threads |
|---|---|---|
| One target language | One reply under the message | One thread with the translation |
| Multiple target languages | Multiple replies in the channel | One thread containing all translations |
| Forum or media channel posts | Replies inside the post | Replies inside the post |
If Discord rejects a reply because the original message was deleted or does not support replies, BabelBot posts the translation as a normal channel message instead. In thread mode, BabelBot also replies in the channel when Discord permissions prevent it from creating or posting in the translation thread.
Controlling noise
Multiple target languages in reply mode multiply visible bot messages. Long translations can also split into more than one reply so Discord accepts them. Thread mode groups translations so the main channel stays readable.
In thread mode you can configure thread retention (days until BabelBot deletes its translation threads). That control lives under Settings → Reply preference in the dashboard.
Discord forum and media posts are already threads. In those posts, BabelBot replies inside the existing post instead of creating another translation thread. This also applies to flag-reaction translations inside forum and media posts.
AI translation vs custom text translation
| Kind | Engine | Quota |
|---|---|---|
| AI translation | OpenRouter (default model configured for BabelBot) | Counts toward your plan’s AI translation allowance |
| Custom text translation | LibreTranslate-backed Custom BabelBot Translation Model | Unlimited on tiers that allow fallback after AI quota is used; also used for plain text bridge recovery when AI has a technical error |
On Free, Pro, and Ultra, when AI quota for the period is exhausted, plain text without attachments can still translate via Custom BabelBot Translation Model. Plain text bridge messages can also use that model when AI has a technical error before returning a usable translation. Flag reactions, context menus, custom words, and media translation still require AI.
Legacy Ultra and Founder Access tiers treat AI translations as unlimited.
Details and exact limits: Billing and Limits.
Custom words (AI translation only)
On Pro and above you can set custom words: pick a word and tell BabelBot how to translate it into one language or All Languages. Use them for server names, game vocabulary, brand and product names, community slang, or terms that should stay untranslated. Custom words only work with AI. When a message uses one of your custom words, BabelBot always translates it with AI and does not fall back to the Custom BabelBot Translation Model for that message. If your AI quota runs out, the normal quota behavior applies. Custom words work in automatic translation, bridges, flag reactions, the Translate Text context menu, and voice chat translation. Notes are just reminders for your team and the bot never follows them. See the Dashboard Guide to set them up.
Bridges
Bridges connect channels so messages in one language channel appear in another:
- Pair bridge: Two channels, two languages, traffic both ways
- Hub bridge: One hub channel plus multiple spoke channels (same bridge UI in the dashboard)
When a bridge matches, BabelBot infers source language from the channel where the message was sent and delivers translated (or link-only) content to the paired destination via webhooks. Quota and normal eligibility skips still apply.
Don't translate from does not apply to bridge routes. Bridges already define their source and target language behavior.
Followed announcements
Some servers Follow announcement channels from other guilds. Discord marks those crossposts in ways BabelBot recognizes.
When a message qualifies as a followed announcement, BabelBot may translate it even though the author is a bot or webhook. Detection is limited to native crosspost patterns so random bot traffic is not translated.
There is no separate dashboard toggle for this today; behavior follows Discord’s message flags. Output uses the same delivery mode as the rest of the server.
Flag reaction translations
When Allow flag reactions is on (Settings), reacting with a supported country-flag emoji translates that message to the associated language.
- Uses the AI provider only
- Counts toward AI quota
- Includes supported PDFs, images, video attachments, and audio files when media translation is available for the server
- Respects disabled channels and ignored users
- Can stay on in a channel rule even when automatic translation is off
- Supports PDF-only, image-only, video-only, audio-only, and media+caption posts when media translation is available for the server
- Honors reply vs thread preference
- Ignores Don't translate from because the reaction is an explicit translation request
Context menus and DMs
Translate Text and Detect Language (right-click a message) use AI. They work in guild channels and, with user install, in DMs and private channels. They do not replace server-wide automatic translation settings.
Voice chat translation
For live voice calls, BabelBot can join a voice channel, listen to speech, and post translated text in that channel's text chat. This is separate from audio attachments (voice notes and audio clips posted in text channels).
- One active voice translation per server
- Members start it with
/voice startafter an admin enables it on Ultra or Founder Access - Does not count toward your normal message translation quota
Full guide with admin and member steps: Voice chat translation.
Summary
- Skips are usually policy, not outages: bots, non-text content, disabled channels, and quota boundaries are the common causes.
- Thread mode and fewer target languages reduce noise.
- Bridges change where output appears, not whether eligibility rules exist.
- Only posted message translations consume AI quota (voice chat translation is separate).
- Voice chat translation is live call transcription + translation in voice channel text chat; voice notes and audio files are attachment-based in text channels.
Next: Dashboard Guide for how to change settings, or Troubleshooting if behavior still does not match this page.