Руководство по работе с локализацией в 1С-Битрикс с использованием пространства имён Localization и класса Loc

В 1С-Битрикс локализация (перевод интерфейса на разные языки) организована с помощью системы языковых файлов. Для удобного управления переводами используется пространство имён Bitrix\Main\Localization и, в частности, финальный класс Loc. Ниже рассмотрим основные принципы работы с классом Loc, подключение языковых файлов и передачу параметров для перевода.

$Руководство по локализации в 1С-Битрикс через Bitrix\Main\Localization\Loc$

1. Общие сведения о локализации в 1С-Битрикс

Языковые файлы: В 1С-Битрикс переводы хранятся в отдельных PHP-файлах, расположенных в папках вида /lang/ru/ (для русского языка), /lang/en/ (для английского) и т.д. Обычно такие файлы содержат массив с ключами и соответствующими переводами.
Пространство имён Localization: Начиная с определённой версии 1С-Битрикс (примерно с 15.0.0 – 16.0.0, в зависимости от редакции), локализационные функции получили собственное пространство имён \Bitrix\Main\Localization.
Класс Loc: Основной и финальный класс для работы с языковыми сообщениями, реализующий методы загрузки языковых файлов и получения переводов. По сути, он заменяет прежние глобальные функции типа GetMessage(), предлагая более гибкий и современный интерфейс.

2. Подготовка языковых файлов

Прежде чем использовать класс Loc, необходимо создать языковые файлы, в которых будут храниться ваши переводы. Рассмотрим пример. Допустим, у нас есть файл example.php в папке /local/php_interface/ (путь может быть любым, важно понимать логику):

Создаём папку для русского языка:
```
/local/php_interface/lang/ru/
```
В этой папке создаём файл с тем же именем, что и у основного файла, например example.php, и записываем в него переводы. Например:
```
<?php
$MESS["MY_GREETING"] = "Здравствуйте!";
$MESS["MY_FAREWELL"] = "До свидания!";
?>
```
Аналогично, для английской версии интерфейса создаём:
```
/local/php_interface/lang/en/
```
И там файл example.php:
```
<?php
$MESS["MY_GREETING"] = "Hello!";
$MESS["MY_FAREWELL"] = "Goodbye!";
?>
```

Обратите внимание, что структура папок должна повторять структуру размещения основного файла, чтобы 1С-Битрикс корректно определял, где искать переводы.

3. Подключение языковых файлов и использование класса Loc

3.1. Подключение

Для подключения языкового файла необходимо вызвать метод:

use Bitrix\Main\Localization\Loc;

// В начале php-файла:
Loc::loadMessages(__FILE__);

__FILE__ указывает, что нужно загрузить языковой файл с тем же путём и именем, что и у текущего.
Если вы хотите явно загрузить языковой файл из другого пути, укажите его вторым параметром. Пример:
```
Loc::loadMessages($_SERVER["DOCUMENT_ROOT"]."/local/php_interface/include/functions.php");
```

3.2. Получение переводов

После загрузки файлов мы можем обратиться к переводу ключа с помощью:

Loc::getMessage("MY_GREETING");

Если вы используете русский язык, вернётся "Здравствуйте!", а если в настройках сайта выбран английский язык — "Hello!".

Пример использования:

<?php
use Bitrix\Main\Localization\Loc;

// Подключаем языковой файл
Loc::loadMessages(__FILE__);

// Выведем на экран фразу приветствия
echo Loc::getMessage("MY_GREETING");
?>

3.3. Передача параметров в перевод

Часто требуется подставлять динамические значения внутрь текстовых сообщений. Класс Loc позволяет это делать с помощью второго параметра — массива замены:

Loc::getMessage("KEY_WITH_PLACEHOLDERS", [
    "#USER_NAME#" => $userName,
    "#DATE#"      => date("d.m.Y"),
]);

Тогда в языковом файле необходимо прописать сообщение с плейсхолдерами:

$MESS["KEY_WITH_PLACEHOLDERS"] = "Здравствуйте, #USER_NAME#! Сегодня #DATE#.";

После вызова Loc::getMessage плейсхолдеры заменятся на соответствующие значения.

4. Пример сквозного использования

Рассмотрим более развёрнутый пример. Допустим, у нас есть файл example.php, в котором выводится приветствие и дата:

<?php
use Bitrix\Main\Localization\Loc;

// Загружаем языковой файл
Loc::loadMessages(__FILE__);

// Подготавливаем данные
$userName = "Иван";
$currentDate = date("d.m.Y");

// Выводим результат
echo Loc::getMessage("WELCOME_TEXT", [
    "#USER_NAME#" => $userName,
    "#DATE#"      => $currentDate
]);
?>

В файле /local/php_interface/lang/ru/example.php (русская локализация) будет:

<?php
$MESS["WELCOME_TEXT"] = "Здравствуйте, #USER_NAME#! Сегодня #DATE#.";
?>

В файле /local/php_interface/lang/en/example.php (английская локализация) будет:

<?php
$MESS["WELCOME_TEXT"] = "Hello, #USER_NAME#! Today is #DATE#.";
?>

Теперь, если на сайте в настройках выбрана локаль ru, при входе получим:

Здравствуйте, Иван! Сегодня 05.03.2025.

А при выборе локали en:

Hello, Иван! Today is 05.03.2025.

5. Возможные проблемы и способы их решения

Неправильная структура папок Убедитесь, что пути к языковым файлам совпадают со структурой основного файла. Если папки расположены неправильно, Loc::loadMessages() не найдёт нужные переводы.
Отсутствие префиксов (учёт уникальных ключей) В крупных проектах лучше использовать префиксы, связанные с модулем или частью функционала. Например, "MYMODULE_WELCOME_TEXT". Это поможет избежать конфликтов при использовании общих ключей в разных частях проекта.
Кодировка файлов В 1С-Битрикс рекомендуется использовать кодировку UTF-8 без BOM. Убедитесь, что языковые файлы сохранены в корректной кодировке, иначе могут возникать проблемы с чтением символов.
Дублирование ключей Если один и тот же ключ встречается в разных языковых файлах, убедитесь, что значение у него действительно должно быть одинаковым или вы используете разные ключи для разных сообщений.

6. Заключение

Пространство имён Bitrix\Main\Localization и класс Loc упрощают процесс работы с языковыми файлами, делая код более чистым и удобным. Использование централизованного механизма локализации даёт гибкость и масштабируемость вашему проекту в 1С-Битрикс:

Легко подключать дополнительные языки.
Просто редактировать переводы без изменения основного кода.
Избежать конфликтов и путаницы в ключах.

Начав с простых примеров, вы сможете последовательно настроить многоязычный интерфейс и обеспечить удобное и понятное взаимодействие для пользователей из разных стран.

Успешных вам переводов и комфортной разработки!

Теги: руководство, D7