Локализация в Битрикс: Правильная работа с языковыми файлами (GetMessage и Loc::getMessage)

Жестко «зашивать» текстовые строки (заголовки, названия кнопок, сообщения) прямо в код — плохая практика. Это затрудняет перевод сайта на другие языки и усложняет поддержку. В Битрикс для этого существует механизм локализации, основанный на языковых файлах.

Зачем нужны языковые файлы?

1. Многоязычность: Легко перевести компонент или модуль, просто создав новую папку с переводами (en, de и т.д.).
2. Чистый код: Логика отделена от текста.
3. Удобство: Весь текст собран в одном месте, его легко найти и отредактировать.

Структура и подключение

Языковые файлы всегда лежат в папке lang. Для каждого языка создается своя подпапка (ru, en). Структура папок с языковыми файлами должна повторять структуру папок с PHP-файлами, к которым они относятся.

• Для файла /local/components/my/comp/component.php
• Языковой файл будет: /local/components/my/comp/lang/ru/component.php

Содержимое языкового файла — это простой PHP-массив $MESS.

// /.../lang/ru/component.php
<?
$MESS['MY_COMP_TITLE'] = 'Заголовок компонента';
$MESS['MY_COMP_BUTTON_SEND'] = 'Отправить';

1. Классический подход: GetMessage()

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

Синтаксис: GetMessage(«КОД_СООБЩЕНИЯ»)

Пример в шаблоне компонента:

// template.php
?>
<h3><?= GetMessage('MY_COMP_TITLE') ?></h3>
<button><?= GetMessage('MY_COMP_BUTTON_SEND') ?></button>

Подстановка значений:
GetMessage поддерживает замену плейсхолдеров.

// lang/ru/template.php
$MESS['GREETING_MESSAGE'] = 'Здравствуйте, #USER_NAME#!';

// template.php
echo GetMessage('GREETING_MESSAGE', ['#USER_NAME#' => $arResult['USER']['NAME']]);

2. Современный D7-подход: Loc::getMessage()

В ядре D7 для локализации предназначен класс \Bitrix\Main\Localization\Loc. Он предлагает более удобный и производительный механизм «ленивой» загрузки.

Подготовка:

use Bitrix\Main\Localization\Loc;

// Сообщаем системе, для какого файла нам нужны языковые сообщения
// Сама загрузка произойдет только при первом вызове getMessage
Loc::loadMessages(__FILE__);

Строка Loc::loadMessages(__FILE__); — обязательна. Она указывает, для текущего файла нужно будет найти и подключить соответствующий lang-файл.

Синтаксис: Loc::getMessage(«КОД_СООБЩЕНИЯ», $replace, $language)

Пример в component.php

use Bitrix\Main\Localization\Loc;
Loc::loadMessages(__FILE__);

if (empty($arParams['NAME'])) {
    $arResult['ERRORS'][] = Loc::getMessage('ERROR_NAME_EMPTY');
}

Подстановка значений в D7:
Массив для замены передается вторым аргументом.

// lang/ru/template.php
$MESS['GREETING_MESSAGE_D7'] = 'Добро пожаловать, #USER_NAME#.';

// template.php
use Bitrix\Main\Localization\Loc;
Loc::loadMessages(__FILE__);

echo Loc::getMessage('GREETING_MESSAGE_D7', ['#USER_NAME#' => 'Гость']);

GetMessage vs. Loc::getMessage

Вывод:
Всегда выносите текстовые строки в языковые файлы. Это признак качественного кода. Используйте современный Loc::getMessage в логике ваших компонентов и модулей для повышения производительности и чистоты кода, а привычный GetMessage можно оставить для использования в template.php, где его использование максимально просто.

GetMessage, Loc::getMessage, языковые файлы Битрикс, локализация, lang.php, многоязычность, D7.