Локализация

Локализация позволяет одному сценарию бота отвечать пользователям на разных языках. Вместо того чтобы создавать отдельный сценарий или дублировать тексты для каждого языка, вы один раз заводите переменные перевода и подставляете их в текстах, подписях и кнопках — а бот сам выводит подходящий перевод в зависимости от языка конкретного пользователя.

Для каких задач это нужно

• Международный бот — один сценарий обслуживает аудиторию из разных стран.
• Магазин или сервис с мультиязычными клиентами — карточки товаров, уведомления, кнопки на языке покупателя.
• Поддержка нескольких языков в рамках одной страны — например, русский и казахский, русский и украинский.
• Быстрый перевод существующего бота — не нужно пересобирать сценарий, достаточно завести переводы и заменить тексты на переменные.

Как это устроено

1. Вы создаёте словарь переводов на уровне бота — он общий для всех сценариев (flow) этого бота.
2. В словаре добавляете нужные языки и отмечаете один из них как язык по умолчанию.
3. Заводите переменные локализации — короткие имена (например name, btn_buy, welcome_text) — и указываете перевод для каждого языка.
4. В любом текстовом поле конструктора (текст сообщения, подпись к медиа, текст кнопки, URL и т.д.) вставляете переменную вида:

{{trans.name}}

5. Когда бот отправляет сообщение конкретному пользователю, он подставляет вместо {{trans.name}} перевод на языке этого пользователя.

Вкладка «Локализация»

Управление словарём переводов находится в едином окне настроек конструктора: откройте выпадающее меню «Ещё» в шапке конструктора и выберите «Локализация».

Языки

• Добавляйте языки кнопкой «+ Добавить язык» — список языков берётся из общего каталога, как и в настройках виджета.
• Звёздочка рядом с языком отмечает язык по умолчанию. Кликните по звёздочке у другого языка, чтобы сделать его языком по умолчанию.
• Удалить язык можно кнопкой рядом с его названием — при этом удаляются все переводы для этого языка (сами переменные остаются).

Переменные и переводы

Список переменных общий для всех языков — вы заводите переменную один раз, а переводы указываете отдельно на вкладке каждого языка:

• «+ Добавить перевод» — создаёт новую переменную. Укажите короткое имя (латиница, цифры, _ и -, регистр не важен — приводится к нижнему автоматически).
• Переключаясь между языковыми вкладками, заполняйте перевод для каждого языка. Поле перевода — многострочное, при наведении в углу появляется кнопка расширенного редактора (с предпросмотром форматирования, как в текстовых блоках).
• Значок корзины удаляет переменную для всех языков сразу.
• Значения переводов могут содержать обычные переменные и Markdown-разметку — они раскрываются как обычно.

Автоматический перевод через ИИ

Чтобы не переводить вручную каждую переменную:

• На вкладке языка по умолчанию — кнопка «Перевести для всех языков (N)», где N — количество пустых переводов среди остальных языков. По нажатию ИИ переводит все незаполненные значения для всех языков, ориентируясь на текст языка по умолчанию.
• На вкладке любого другого языка — кнопка «Перевести пустые» переводит недостающие значения только для этого языка.

Во время перевода кнопка показывает прогресс («Перевод: RU (1/3)…») и недоступна для повторного нажатия. Уже заполненные вручную переводы никогда не перезаписываются — переводятся только пустые поля.

Перевод выполняется тем же ИИ-ассистентом и с тем же дневным лимитом запросов, что и функция «Перевести сообщение» в разделе «Чаты». Если лимит закончился в процессе перевода нескольких языков — уже полученные переводы сохраняются, а появится уведомление о частичном завершении.

Импорт и экспорт

• «Экспорт» — сохраняет весь словарь переводов в файл.
• «Импорт» — загружает файл обратно: новые переменные добавляются, а значения для существующих переменных обновляются (без дублирования).

Удобно для переноса переводов между ботами или для передачи текстов профессиональному переводчику вне конструктора.

Вставка переменной перевода в текст

Есть два способа добавить {{trans.*}} в поле:

Через список переменных

В любом текстовом поле начните вводить {{ — появится список доступных переменных. Переменные локализации выделены в отдельную группу «Локализация» и показывают перевод на языке по умолчанию как подсказку.

Прямо из поля — кнопка «Локализация»

Рядом с текстовыми полями (там же, где кнопки вставки эмодзи и переменных) есть кнопка «Локализация». Она открывает мини-форму прямо под полем:

• Если языки ещё не добавлены — форма покажет ссылку «Добавить языки», которая откроет вкладку «Локализация».
• Если поле уже содержит {{trans.имя}} — форма автоматически подгрузит существующие переводы для редактирования.
• Укажите переменную и переводы для каждого языка, при необходимости нажмите «Перевести» (переводит с языка по умолчанию на остальные), затем «Сохранить» — переменная будет создана или обновлена, а макрос {{trans.имя}} вставится в поле.

Это позволяет создавать и редактировать переводы, не покидая настройки блока.

Как бот выбирает нужный перевод

Для каждой переменной {{trans.имя}} действует правило из трёх шагов:

1. Ищется перевод для языка текущего пользователя.
2. Если перевода для его языка нет или он не заполнен — используется перевод для языка по умолчанию.
3. Если пусто и там — переменная выводится как пустая строка.

Это значит, что бот никогда не «упадёт» из-за отсутствующего перевода — в худшем случае просто ничего не выведет вместо этого текста, поэтому язык по умолчанию стоит заполнять в первую очередь и полностью.

Как дать пользователю выбрать язык самому

Язык интерфейса Telegram-клиента пользователя не всегда совпадает с языком, на котором он хочет общаться с ботом. Чтобы пользователь мог выбрать язык сам:

1. Добавьте в сценарий (например, в приветственную команду) кнопки с названиями языков, например:
   • «🇷🇺 Русский»
   • «🇬🇧 English»
2. На каждую кнопку повесьте переход к отдельной команде, где стоит блок «База данных» → источник «Пользователь» → действие «Изменить язык» — укажите код языка (ru, en и т.д.), соответствующий нажатой кнопке. Подробнее о блоке — в разделе База данных.
3. После сохранения языка все переменные {{trans.*}} в сценарии автоматически начнут выводиться на выбранном пользователем языке — при следующем и всех последующих сообщениях, без каких-либо дополнительных действий.

Тот же принцип работает и для гостей веб-виджета — язык определяется независимо для каждого пользователя.

Где ещё учитывается язык пользователя

• На канвасе конструктора — тексты и подписи кнопок с {{trans.*}} показывают перевод на языке по умолчанию — это удобный предпросмотр, реальным пользователям выводится их собственный язык.
• В истории переписки (раздел «Чаты») — если пользователь нажал на кнопку с переменной перевода, в списке диалогов и в самой переписке отображается текст кнопки на языке этого пользователя, а не исходный макрос.

Пример

Заведена переменная greeting со значениями:

Текст сообщения в блоке:

{{trans.greeting}}

Пользователю с языком ru бот отправит «Добро пожаловать, Иван!», пользователю с языком en — «Welcome, Ivan!», а пользователю с любым другим языком (например, de) — перевод для языка по умолчанию, то есть тот же текст на русском.

Советы

• Называйте переменные по смыслу, а не по месту использования: btn_buy, welcome_text, order_confirmed — так проще ориентироваться в списке при росте словаря.
• Всегда полностью заполняйте язык по умолчанию — это подстраховка на случай отсутствия перевода для остальных языков.
• Переменные перевода можно использовать где угодно — в тексте сообщений, подписях к медиа, тексте и URL кнопок, тексте автосообщений.
• Внутри значения перевода можно свободно использовать другие переменные бота ({{user.first_name}}, {{balance}} и т.д.) — они подставятся как обычно.
• Проверяйте результат автоматического перевода — ИИ обычно справляется хорошо, но для важных текстов (названия, юридические формулировки) стоит перепроверить вручную.