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

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

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

Локализация определяет, как шаблон показывает название, описание и другие основные фразы на языке Битрикс24. Ее задают при регистрации шаблона через landing.demos.register.

Эта статья показывает, как устроены параметры lang и lang_original. Она также объясняет, как система выбирает перевод и как проверить сохраненную локализацию через landing.demos.getList.

Параметры с такими же именами есть у пользовательских блоков, но это отдельный механизм с другим набором переводимых полей. Он описан в статье Локализация блока.

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

  1. Подготовьте исходные фразы шаблона на одном языке
  2. Передайте код этого языка в lang_original
  3. Передайте переводы в lang
  4. После регистрации проверьте поле LANG методом landing.demos.getList

Какие параметры отвечают за локализацию

lang_original. Код исходного языка фраз в шаблоне. Параметр передают в landing.demos.register. Пример значения: ru.

lang. Объект переводов по кодам языков. Параметр передают в landing.demos.register. Внутри каждого языка ключом служит исходная фраза, а значением — перевод этой фразы.

После регистрации система сохраняет оба параметра в поле LANG.

Структура массива может выглядеть так:

  • lang_original — код исходного языка фраз
  • lang.en — переводы для английского языка
  • lang.de — переводы для немецкого языка, если шаблон используют на немецком языке

Например:

{
    "lang_original": "ru",
    "lang": {
        "en": {
            "Название шаблона": "Template title"
        },
        "de": {
            "Название шаблона": "Vorlagenname"
        }
    }
}

Что можно локализовать

В этом примере в массив локализации переданы название и описание:

{
    "lang_original": "ru",
    "lang": {
        "en": {
            "Название шаблона": "Template title",
            "Описание шаблона": "Template description"
        },
        "de": {
            "Название шаблона": "Vorlagenname",
            "Описание шаблона": "Vorlagenbeschreibung"
        }
    }
}

Состав ключей зависит от шаблона. В массив локализации обычно включают название, описание и строковые значения в ADDITIONAL_FIELDS или аналогичных полях шаблона.

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

При выводе шаблона через компонент landing.demo система сначала ищет переводы для языка Битрикс24.

Для языков ru, kz, by и uz используется ветка ru.

Если перевода для языка Битрикс24 нет и lang_original отличается от него, используется ветка en.

Если подходящего перевода нет, остаются исходные фразы шаблона.

Как проверить локализацию

После регистрации вызовите landing.demos.getList и запросите поле LANG. В ответе проверьте:

  • сохранился ли объект локализации
  • какие языки есть в lang
  • какой язык указан в lang_original

Пример ответа метода:

{
    "ID": "11",
    "XML_ID": "demo_localization_test",
    "TITLE": "Название шаблона",
    "DESCRIPTION": "Описание шаблона",
    "TYPE": "page",
    "TPL_TYPE": "S",
    "LANG": {
        "lang": {
            "en": {
                "Название шаблона": "Template title",
                "Описание шаблона": "Template description"
            },
            "de": {
                "Название шаблона": "Vorlagenname",
                "Описание шаблона": "Vorlagenbeschreibung"
            }
        },
        "lang_original": "ru"
    }
}

Поля TITLE и DESCRIPTION возвращаются в том виде, в котором были сохранены при регистрации. Переводы хранятся отдельно в LANG.

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

  • Значение lang_original должно совпадать с исходным языком фраз в шаблоне
  • Для каждого языка передавайте одинаковый набор ключей
  • Если шаблон отображается в Битрикс24 с разными языками, подготовьте массив локализации до регистрации
  • Метод landing.demos.getList помогает проверить, что локализация сохранилась в ожидаемой структуре

Локализация в landing.demos.* хранится отдельно от основных полей шаблона. Поэтому после регистрации стоит проверить не только TITLE и DESCRIPTION, но и содержимое поля LANG.

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

Предыдущая
Введение
Следующая
Зарегистрировать шаблон