Design a multilingual Telegram bot: language selection, fallback, and interface copy

A multilingual bot needs more than an English /help translation. Does a user's manual language choice survive the next message? Can one English-speaking member change a whole group's interface? What appears when an error message has no translation? These policies determine whether the experience is predictable.

This guide covers localization of fixed interface copy, not translation of group conversations or a requirement to call a language model at runtime. For menu scopes, see the command-menu guide.

Separate three language signals

The client language is an initial hint. A deliberate user choice is a preference. The language of an incoming sentence is a property of its content. Do not collapse these into one “automatic language” field.

grammY's i18n documentation describes locale negotiation using a stored choice, client language_code, and a default. It also notes that client language may be unavailable. The design pattern is useful without installing that plugin.

Define an explicit private-chat priority:

1. A saved user choice that the bot supports.
2. The client language mapped to a supported locale.
3. A fixed default.

If the interface supports only Chinese and English, taking the first two letters is not enough to establish a complete language policy. Decide how zh, zh-CN, and zh-TW map to available copy. Missing and unknown values should fall back with a discoverable language selector.

An English sentence should not silently overwrite a previously selected Chinese interface. Translating user content is a separate feature with its own scope and costs.

Group messages need their own language policy

Private replies usually follow the user's preference. Shared announcements, public lists, and group administration may need a group-selected language or a consistent bilingual format.

This is an optional policy, not a Telegram requirement. The important decision is ownership: changing a member's personal setting must not silently change the group setting, and changing interface copy must not rewrite stored business content.

Remembering a preference requires persistent storage actually supported by the environment. Temporarily changing one reply and retaining the choice across later updates are separate acceptance criteria.

Translate complete messages, not word fragments

Concatenating a phrase, number, and noun may work in one language and fail in another. Project Fluent's Selectors guide demonstrates full-message variants selected by numbers or strings, with a required default branch.

Fluent itself is not mandatory. Specify the outcome: English uses appropriate singular and plural forms for one versus zero or multiple tasks; Chinese has its own complete sentence. Treat task names, names, and notes as values, not interface translation keys.

Define date, time-zone, and number presentation as well. A language switch must not change an event's actual start time or reinterpret an already saved date. Both languages should display the same time meaning and identify the business time zone.

Missing copy needs a fallback, not an internal key

Prepare localized start, help, empty-list, unauthorized, invalid-input, success, cancellation, and temporary-failure messages. A feature with translated success copy but untranslated failure paths is not complete.

Separate two fallback cases: an unsupported locale selects the default interface; a missing message in the selected locale uses the default version for that message and records the missing key. Logging the key and version is enough; user content is unnecessary.

Button labels are not stable business identifiers. “完成” and “Done” should invoke the same action. A language change must not redefine existing buttons. Whether old messages are edited is another policy to specify separately.

A requirement example

Build a personal-list bot in Chinese and English. In private chats, select the language from a saved user choice, a supported client language, then English. /language changes and saves the preference and immediately confirms in the new language. The choice survives reopening the chat. Switching changes only interface copy, not task contents, IDs, or dates. Administrators configure group-announcement language; members' personal choices do not affect it. Provide complete start, help, success, empty, unauthorized, error, and cancellation messages. Missing keys fall back to English and log the key name. Use stable button action identifiers, correct English singular/plural task counts, and the same clearly labeled business time zone.

Acceptance checks

• Two users choose different languages and cannot overwrite each other's preference.
• Missing or unsupported client language produces the default interface.
• Changing client language after a manual selection follows the documented policy.
• Immediate confirmation, the next update, and reopening all use the expected language.
• Test English counts of zero, one, and two, then the same data in Chinese.
• Omit one error translation deliberately; no internal key or blank reply appears.
• Check group announcements, old buttons, dates, and original user content for unwanted changes.

BotFatherV2 creates and modifies Telegram Serverless bots through AI conversations. Put the language policy, complete copy, and tests in the requirements, but its fixed SDK does not imply support for arbitrary i18n plugins, npm modules, or Node/Bun APIs. Its first release does not add paid-AI runtime capabilities. Localizing fixed copy does not need to become runtime AI translation.

BotFatherV2 is independent of Telegram's official BotFather. Product boundaries were checked October 14, 2026.

Sources

• grammY, Internationalization (i18n), first-party English framework documentation; no explicit publication date shown; accessed October 14, 2026, with the official Chinese version cross-checked.
• Project Fluent, Selectors, first-party English language guide; no publication date shown; accessed October 14, 2026.