Локализация блока

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Локализация блока задает переводы подписей интерфейса, которые пользователь видит в редакторе сайта: название блока, названия нод, карточек, полей атрибутов и пунктов меню. Переводы описывают в файле манифеста через ключи lang_original и lang.

Локализация нужна пользовательским блокам, которые приложение добавляет в репозиторий методом landing.repo.register. Типовой сценарий — приложение Маркетплейса со своими блоками, которое устанавливают в Битрикс24 с разными языками интерфейса. Системные блоки Битрикс24 переводятся языковыми файлами продукта и ключи lang_original и lang не используют.

Границы темы:

  • локализация не переводит контент блока. Текст, ссылки и изображения, которые пользователь ввел в блоке на странице, хранятся в контенте и остаются на исходном языке
  • ключи lang_original и lang с теми же именами есть у пользовательских шаблонов сайтов, но это отдельный механизм с другим набором переводимых полей. Он описан в статье Локализация шаблона

Как добавить локализацию

  1. Соберите манифест блока на одном языке.
  2. Передайте код этого языка в lang_original.
  3. Соберите массив lang: для каждого языка перечислите исходные фразы манифеста и их переводы.
  4. Зарегистрируйте блок методом landing.repo.register, передав lang_original и lang в параметре manifest.
  5. Добавьте блок на страницу и вызовите landing.block.getmanifest. В ответе значения name должны прийти на языке Битрикс24, ключ lang — отсутствовать, а lang_original — сохраниться в исходном виде.

Ключи локализации в манифесте

  • lang_original — код исходного языка фраз в манифесте, например ru
  • lang — набор переводов по кодам языков

Код языка совпадает с кодом языка Битрикс24. Текущий язык возвращает метод app.info в поле LANGUAGE_ID.

В массиве lang ключами выступают исходные фразы из манифеста, а значениями — переводы этих фраз.

Пример:

'lang_original' => 'ru',
'lang' => [
    'en' => [
        'Заголовок с разделителем на светлом фоне' => 'Title with a separator on a light background',
        'Кнопка' => 'Button',
    ],
    'de' => [
        'Заголовок с разделителем на светлом фоне' => 'Titel mit Trennlinie auf hellem Hintergrund',
        'Кнопка' => 'Schaltfläche',
    ],
],

Какие подписи участвуют в переводе

Система обходит манифест целиком и подменяет значения только у ключей name на любом уровне вложенности. Другие ключи не переводятся, даже если в lang есть подходящая фраза.

Ключи name, которые встречаются в манифесте:

Ключ манифеста

Что это за подпись

block.name

Название блока в каталоге блоков и в списке репозитория

nodes.<селектор>.name

Название ноды в форме редактирования блока

cards.<селектор>.name

Название группы карточек

cards.<селектор>.presets.<код>.name

Название пресета карточки в списке

style.nodes.<селектор>.name

Подпись элемента в панели стилей, если она задана ключом name

attrs.<селектор>[].name

Название поля атрибута в редакторе. У элемента-группы — название самой группы

attrs.<селектор>[].attrs[].name

Название поля внутри группы атрибутов

attrs.<селектор>[].items[].name

Подпись варианта в списочных типах атрибутов: dropdown, checkbox, radio, multiselect

style.nodes.<селектор>.additional.attrs[].name

Название поля атрибута, выведенного в форму дизайна

cards.<селектор>.additional.attrs[].name

Название поля атрибута, заданного отдельно для карточки

menu.<селектор>.name

Название меню в интерфейсе

menu.<селектор>.nodes.<селектор>.name

Название ноды внутри пункта меню

Таблица перечисляет места, где ключ name встречается в типовом манифесте. Правило шире таблицы: переводится любой ключ name на любом уровне вложенности, поэтому проверяйте свой манифест целиком.

Не переводятся:

  • block.description — описание блока
  • style.nodes.<селектор>.title — подпись элемента в панели стилей, заданная ключом title
  • служебные поля атрибутов: placeholder, title, stubText
  • значения value в списках items
  • селекторы, коды разделов, типы нод и типы стилей

В примере манифеста подписи в style.nodes заданы то ключом name, то ключом title. Если такую подпись нужно переводить, укажите ее ключом name.

Пример манифеста с подписями, которые попадут в перевод:

$manifest = [
    'block' => [
        'name' => 'Заголовок с разделителем',
        'section' => ['text'],
    ],
    'nodes' => [
        '.landing-block-node-title' => [
            'name' => 'Заголовок',
            'type' => 'text',
        ],
    ],
    'lang_original' => 'ru',
    'lang' => [
        'en' => [
            'Заголовок с разделителем' => 'Title with a separator',
            'Заголовок' => 'Title',
        ],
    ],
];

Как система выбирает перевод

Система выбирает одну ветку языка из массива lang и применяет ее ко всему манифесту:

  1. Определяет язык Битрикс24. Для языков ru, kz, by и uz используется ветка ru.
  2. Если ветка с этим кодом есть в lang, берет переводы из нее.
  3. Если ветки нет, а lang_original отличается от языка Битрикс24, берет переводы из ветки en.
  4. Если подходящей ветки нет, оставляет исходные фразы манифеста.

Внутри выбранной ветки перевод подставляется только для тех фраз, которые есть в ней как ключи. Фразы без перевода остаются на языке lang_original.

Какие методы возвращают переведенный манифест

Метод

Что возвращает

landing.block.getmanifest

Манифест блока, размещенного на странице, с уже подставленными переводами. Ключ lang из ответа удаляется, lang_original остается

landing.block.getmanifestfile

Исходный манифест блока без подстановки переводов, вместе с ключами lang_original и lang

landing.block.getrepository

Список блоков репозитория, где переводится только название блока. Остальные подписи в этот ответ не входят

Чтобы увидеть переводы, вызывайте landing.block.getmanifest для блока, уже добавленного на страницу. Язык подстановки задает язык Битрикс24, а не параметр метода.

В ответе этого метода проверьте:

  • значения name в block, nodes, cards, attrs и menu — они должны быть на языке Битрикс24
  • ключ lang — его в ответе нет, система удаляет его после подстановки переводов
  • ключ lang_original — он остается в том виде, в котором был передан при регистрации

Если значения name пришли на исходном языке, сверьте фразы-ключи в lang со строками манифеста и проверьте, есть ли в lang ветка для языка Битрикс24 или ветка en.

Права и ограничения

Scope: landing

Кто может выполнять метод: в зависимости от метода

Ограничения локализации:

  • переводится только значение ключа name
  • ключом перевода служит точная строка из манифеста, включая регистр, пробелы и знаки препинания
  • одна фраза переводится одинаково во всех местах манифеста, отдельный перевод для конкретного селектора задать нельзя
  • коды веток в lang ограничены кодами языков, доступных в Битрикс24. Ветка с кодом, которого нет среди языков интерфейса, не будет выбрана

Что учитывать

  • Указывайте в lang_original тот язык, на котором фразы записаны в манифесте. Если значение не совпадает с фактическим языком, запасная ветка en не сработает.
  • Задавайте одинаковый набор ключей во всех языковых ветках, чтобы интерфейс не смешивал языки.
  • Различайте подписи с разным смыслом уже на исходном языке. Например, вместо двух подписей «Название» используйте «Название блока» и «Название кнопки».
  • Заводите отдельную ветку en, даже если основной язык блока другой. Она используется как запасной вариант для языков без своего перевода.

Продолжите изучение

Предыдущая
Расширенное описание карточек
Следующая
Обзор блоков