Руководство по работе с CUtil::translit() в 1С-Битрикс

Транслитерация символов – важная задача при создании URL-адресов, символьных кодов и других полей, где допускаются только латинские буквы и цифры. В 1С-Битрикс для этого предусмотрен статический метод CUtil::translit(), позволяющий преобразовывать строки из кириллицы (и не только) в транслит. Эта функция часто используется для формирования «человеко-понятных» ссылок, символьных кодов элементов инфоблоков, а также для других нужд в веб-разработке.

В данной статье мы детально рассмотрим:

1. Формат метода и его параметры.
2. Примеры использования при работе с инфоблоками.
3. Рекомендации по настройкам и лучшие практики.

1. Что такое CUtil::translit()

Метод CUtil::translit() — это статический метод класса CUtil, который принимает строку (например, «Текст для транслитерации»), язык (ru, en и т.п.) и набор параметров, описывающих правила транслитерации, и возвращает строку, преобразованную к требуемому формату.

Общий вид вызова:

CUtil::translit(
    string $str,
    string $lang,
    array $params = []
);

Описание параметров

1. str Строка, которую нужно транслитерировать.
2. lang Язык оригинальной строки (например, "ru"). Чаще всего применяется русский, однако теоретически можно задать и другие поддерживаемые языки.
3. params Массив дополнительных настроек:

2. Пример простого вызова

Допустим, нужно транслитерировать строку "Текст*89". По умолчанию пробелы и «непонятные» символы заменяются на _, но мы захотим вместо _ использовать -. Рассмотрим код:

<?php
$name = "Текст*89";
$arParams = array(
    "replace_space" => "-",
    "replace_other" => "-"
);

// Выполним транслитерацию
$trans = CUtil::translit($name, "ru", $arParams);

// Выведем результат
echo '<pre>';
var_dump($trans);
echo '</pre>';
?>

Что происходит внутри:

1. "Текст*89" посимвольно обрабатывается, кириллица переводится в латиницу (например, "Т" → T, "е" → e, "к" → k, и т.д.).
2. Пробелы (если бы они были) заменились бы на -.
3. Остальные «левые» символы (например, *) также заменяются на -.
4. По умолчанию change_case равно L, поэтому результат приводится к нижнему регистру.

Если выведете результат, то увидите, что Текст*89 превратился примерно в "tekst-89" (конечный вариант зависит ещё и от точных правил транслита, прописанных в языковых файлах Bitrix).

Важно: Символ & (амперсанд) внутри Битрикс обычно заменяется как amp (например, "Hello & world" → hello-amp-world). Это заложено в файле локализации.

3. Использование в функциях для генерации символьных кодов

Пример 1. Упрощённый метод

Рассмотрим функцию, которая «на лету» возвращает транслитерацию для имени без сложных настроек:

function translitName(string $name, int $iblockId = 0): string
{
    // Удаляем пробелы в начале и конце
    $name = trim($name);

    // Если инфоблок не задан, просто вызовем транслит с настройками по умолчанию
    if (!$iblockId) {
        return \Cutil::translit($name, 'ru');
    }

    // ... некоторая логика, связанная с проверкой настроек
    // Но для наглядности оставим лишь минимальную реализацию:
    return \Cutil::translit($name, 'ru');
}

Здесь если не задан ID инфоблока, мы применяем стандартную логику транслита. Функция вернёт, например, для строки "Пример Названия" что-то вроде "primer-nazvaniya", учитывая настройки по умолчанию.

Пример 2. С учётом реальных настроек инфоблока

Часто при работе с символьными кодами нужно ориентироваться на глобальные настройки инфоблока. В Bitrix у инфоблоков существует настройка полей, где в разделе «Символьный код» можно указать:

• длину (TRANS_LEN),
• регистр (TRANS_CASE),
• символ замены пробела (TRANS_SPACE),
• символ замены «прочих» символов (TRANS_OTHER),
• и т.п.

Приведём более «боевой» пример:

function translitName(string $name, int $iblockId = 0): string
{
    static $cachedIblockFields;

    $name = trim($name);

    // Если не передан ID инфоблока, просто вернём строку, транслитерованную по умолчанию
    if (!$iblockId) {
        return \Cutil::translit($name, 'ru');
    }

    // Кэшируем запрос к настройкам полей инфоблока
    if (!isset($cachedIblockFields[$iblockId])) {
        $cachedIblockFields[$iblockId] = \CIBlock::GetFields($iblockId);
    }

    $iblockFields = $cachedIblockFields[$iblockId];

    // Допустим, если поле 'CODE' не является обязательным — вернём пустую строку
    if (!$iblockFields || $iblockFields['CODE']['IS_REQUIRED'] != 'Y') {
        return '';
    }

    // Формируем массив настроек транслита на основе настроек поля
    $params = [
        'max_len'        => $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_LEN'],
        'change_case'    => $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_CASE'],
        'replace_space'  => $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_SPACE'],
        'replace_other'  => $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_OTHER']
    ];

    // Выполняем транслитерацию с учётом параметров
    $translitted = \Cutil::translit($name, 'ru', $params);

    // Удаляем повторяющиеся символы в конце, если нужно
    return rtrim(
        rtrim($translitted, $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_SPACE']),
        $iblockFields['CODE']['DEFAULT_VALUE']['TRANS_OTHER']
    );
}

В данном примере функция подстраивается под настройки конкретного инфоблока. Если в админке у инфоблока задано, что пробелы заменяются на дефис, то итогом будет дефис. Если указано ограничение длины (например, 50 символов), то и транслит обрежется до 50 символов.

4. Практический пример при добавлении элемента инфоблока

Частый случай использования: мы создаём элемент инфоблока и хотим, чтобы его символьный код (CODE) генерировался автоматически, опираясь на поле NAME. Код может выглядеть так:

<?php
$el = new CIBlockElement;

$params = [
    "max_len"               => "100",   // обрезает символьный код до 100 символов
    "change_case"           => "L",     // приводим все буквы к нижнему регистру
    "replace_space"         => "-",     // меняем пробелы на дефис
    "replace_other"         => "-",     // «левые» символы на дефис
    "delete_repeat_replace" => "true",  // удаляем повторяющиеся символы замены
    "safe_chars"            => "false", // строка из символов, замена которых не производится
];

// Исходные данные
$data = [
    'name' => 'Пример названия элемента!',
];

// Формируем массив полей для добавления
$fields = [
    "NAME"               => $data['name'],
    "IBLOCK_SECTION_ID"  => $sectionID,
    "IBLOCK_ID"          => $iblockId,
    "ACTIVE"             => "Y",
    "CODE"               => CUtil::translit($data['name'], "ru", $params),
    "PROPERTY_VALUES"    => [
        // Заполнение свойств (при необходимости)
    ],
];

// Добавляем элемент
$elementId = $el->Add($fields);

if ($elementId) {
    echo "Элемент добавлен, ID: {$elementId}";
} else {
    echo "Ошибка: " . $el->LAST_ERROR;
}
?>

Здесь значение поля CODE заранее формируется через CUtil::translit(). В процессе:

• Пробелы заменяются на дефис -.
• В итоге символы вроде ! «схлопнутся» в дефис.
• Строка будет переведена в нижний регистр.
• Если встретятся несколько подряд пробелов или недопустимых символов, они превратятся в один дефис (благодаря delete_repeat_replace).

5. Дополнительные нюансы и рекомендации

1. Нужно ли всегда указывать params? Не обязательно. Если параметры не заданы, то будут использоваться настройки «по умолчанию» из ядра Bitrix:

[
    "max_len"               => 100,
    "change_case"           => "L",
    "replace_space"         => "_",
    "replace_other"         => "_",
    "delete_repeat_replace" => true,
    "safe_chars"            => '',
]

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

2. safe_chars Параметр safe_chars позволяет указать набор символов, которые не будут тронуты во время транслитерации. Это может быть полезно, если нужно «уберечь» определённые символы от замены. Например:

$params = [
    "safe_chars" => ".",
];

Тогда точка не будет заменяться на _ или другой символ.

3. Обратите внимание на длину Параметр max_len по умолчанию равен 100, что часто подходит для SEO и форматов хранения (SIMCODE), но если нужно меньше или больше, следует менять это значение. Если требуется, к примеру, чтобы символьный код не превышал 50 символов, то можно передать max_len => 50.
4. Символ & По умолчанию в таблице транслита, которая прописана в файлах локализации Bitrix, амперсанд заменяется последовательностью amp. То есть "hello & world" превратится в "hello-amp-world", если использовать дефис как символ замены пробелов и «прочих» символов.
5. Простота эксплуатации Часто удобнее всего настроить в админке автоматический транслит для символьных кодов в настройках инфоблока. Тогда при сохранении элемента в форме админки Bitrix сам выполнит транслитерацию поля NAME. Но если требуется делать это в собственном коде или автоматически в скриптах миграции/импорта, то CUtil::translit() — идеальный инструмент.

6. Взгляд «под капот» – как устроен метод

Если заглянуть в исходный файл modules/main/classes/general/util.php, то можно увидеть, что метод translit():

1. Загружает файлы локализации с правилами (TRANS_FROM, TRANS_TO).
2. В цикле обрабатывает строку посимвольно, проверяя каждый символ:
• Если символ — латиница, цифра или указанный в safe_chars, то он оставляется как есть.
• Если это пробел, то заменяется на replace_space (учитывая настройку delete_repeat_replace).
• Если встречен символ, для которого есть сопоставление в массиве search[$lang], подставляет соответствующую транслитерацию.
• Остальные символы заменяются на replace_other.
3. Приводит всё к верхнему/нижнему регистру (если указано U или L).
4. Обрезает строку до max_len.

Метод CUtil::translit() написан таким образом, чтобы быть универсальным и гибким при разных настройках.

Заключение

Функция CUtil::translit() — один из ключевых инструментов при работе с 1С-Битрикс, обеспечивающий корректную транслитерацию строк. Она позволяет автоматически получать URL-friendly тексты, генерировать аккуратные символьные коды элементов инфоблока и другие поля, требующие латиницы без нежелательных символов.

Краткая памятка по использованию:

1. Подключайте функцию в любом месте вашего проекта, где нужно транслитеровать строку (в компонентах, обработчиках, скриптах импорта).
2. Настраивайте параметры (max_len, replace_space, delete_repeat_replace и пр.) в соответствии с вашими SEO-требованиями и техническими ограничениями.
3. Опирайтесь на настройки инфоблока, если вам нужна единообразная система формирования символьных кодов.
4. Проверяйте итоговый результат транслитерации, особенно если используете специфические символы или нестандартные правила.

На этом всё! Надеемся, что данное руководство поможет вам эффективно использовать CUtil::translit() и сэкономит время при разработке. Если у вас остались вопросы или есть дополнительные примеры, которые стоит обсудить — пишите в комментариях к статье!