Как фраза попадает на страницу

Эта часть — для того, кто пишет шаблоны и компоненты.

Короткий ответ

Шаблон зовёт функцию с кодом фразы. Модуль смотрит в словарь, берёт значение на языке текущей страницы и возвращает его. Если значения на этом языке нет — отдаёт базовый язык. Если записи нет вовсе — создаёт её с текстом-заглушкой, который вы передали, и сразу же отдаёт.

<?= LANG_VAR('SUBMIT_BTN', 'Отправить') ?>

Второй аргумент — не «значение по умолчанию на случай сбоя», а первичный текст фразы. Он попадёт в словарь и станет тем, что контент-менеджер увидит и поправит.

Путь значения

1. По коду ищется запись в словаре.
2. Берётся поле текущего языка.
3. Пусто — берётся поле базового языка.
4. Записи нет — она заводится с переданной заглушкой и тут же перечитывается.
5. Подставляются переменные, если вы их передали.
6. В режиме правки результат оборачивается в разметку, чтобы по нему можно было кликнуть.

Последний пункт — причина большинства неожиданностей. Подробнее и что с этим делать — Lang::get и LANG_VAR.

Откуда берётся язык

Из языка текущей страницы Битрикса. Модуль не заводит своего понятия «текущий язык» и не читает его из адреса: он доверяет платформе.

Отсюда следствие: если на сайте языковые версии сделаны не языками Битрикса, а как-то иначе — папками, доменами без привязки языка, параметром в адресе, — модуль будет отдавать один и тот же язык везде. Это не поломка, а условие работы.

Два разных механизма

Фразы интерфейса и контент инфоблоков живут по-разному, и путь у них разный.

Фразы идут через словарь, как описано выше.

Контент инфоблоков подставляется при выборке: вы получаете элемент, а в его полях уже лежит перевод. Шаблон при этом обычно не меняется вовсе. См. Выборка с учётом языка.

Спутать их легко, и симптом одинаковый — «перевод не показывается». Первый вопрос при разборе: это фраза из словаря или поле элемента?

Что читать дальше