CurrentLanguage

WS >= 0.95

CurrentLanguage предоставляет данные текущего языка сайта и формирует внутренние URL с языковым префиксом.

Поддерживает

определение текущего языка по URL
получение кода и префикса языка
формирование ссылок для текущего или указанного языка
добавление и замену query-параметров
сохранение URL-фрагмента
получение маршрута без языкового префикса
работу с сайтами без мультиязычности

CurrentLanguage является статическим классом и автоматически доступен при работе CMS. Создавать его объект не нужно.

Быстрый старт

php

$language = CurrentLanguage::code();
$url = CurrentLanguage::url('/catalog');

Использование в HTML:

php

<html lang="<?php echo CurrentLanguage::htmlLang(); ?>">

php

<a href="<?php echo CurrentLanguage::url('/contacts'); ?>">Контакты</a>

Состояние языка

Метод	Возвращает	Описание
`isEnabled()`	`bool`	Включена ли мультиязычность.
`isResolved()`	`bool`	Определён ли текущий язык.
`get()`	`?array`	Полные данные текущего языка.
`code()`	`?string`	Код текущего языка.
`prefix()`	`?string`	Префикс текущего языка в URL.
`defaultPrefix()`	`string`	Префикс языка по умолчанию.
`htmlLang()`	`string`	Безопасное значение для атрибута `lang`.

Данные языка

get() возвращает массив настроек текущего языка:

php

$language = CurrentLanguage::get();

Массив может содержать:

Ключ	Описание
`code`	Код языка.
`label`	Отображаемое название.
`prefix`	Префикс в URL.
`default`	Язык используется по умолчанию.
`active`	Язык доступен на сайте.
`order`	Порядок языка в настройках.

Если язык не определён, get(), code() и prefix() возвращают null.

Код и префикс

Код языка и URL-префикс являются разными настройками:

php

$code = CurrentLanguage::code();
$prefix = CurrentLanguage::prefix();

Например:

text

code   -> ru
prefix -> ru

Обычно значения совпадают, но полагаться на это не следует.

Для HTML используйте htmlLang(). Для формирования ссылки текущего языка используйте url(), а для указанного языка — urlFor().

Локализованные URL

url(string $url = '/', array $query = []): string

Формирует внутренний URL для текущего языка:

php

$url = CurrentLanguage::url('/developer');

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

text

/ru/developer

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

text

/developer

urlFor(string $languageCode, string $url = '/', array $query = []): ?string

Формирует внутренний URL для указанного языка:

php

$url = CurrentLanguage::urlFor('en', '/developer');

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

text

/en/developer

Первым параметром передаётся код языка, а не его URL-префикс.

Если язык не существует или неактивен, метод возвращает null:

php

$url = CurrentLanguage::urlFor('unknown', '/developer');

if ($url === null) {
    // Ссылка для этого языка недоступна.
}

Query-параметры передаются третьим аргументом:

php

$url = CurrentLanguage::urlFor('en', '/catalog', ['page' => 2]);

Если мультиязычность отключена, URL без префикса возвращается только для языка сайта по умолчанию.

Замена существующего префикса

Если путь уже начинается с префикса активного языка, он заменяется текущим:

php

$url = CurrentLanguage::url('/en/developer');

Для русского языка результат:

text

/ru/developer

Это позволяет переключать язык без накопления префиксов.

Query-параметры

Второй аргумент добавляет или заменяет query-параметры:

php

$url = CurrentLanguage::url(
    '/catalog?page=1',
    [
        'page' => 2,
        'filter' => 'new',
    ]
);

Результат:

text

/ru/catalog?page=2&filter=new

Параметры кодируются по правилам RFC 3986.

URL-фрагменты

Фрагмент сохраняется:

php

$url = CurrentLanguage::url('/developer#examples');

Результат:

text

/ru/developer#examples

Ссылки, начинающиеся с #, возвращаются без изменений:

php

$url = CurrentLanguage::url('#examples');

Внешние ссылки

Абсолютные и служебные ссылки возвращаются без изменений:

php

$external = CurrentLanguage::url('https://example.com/page');
$email = CurrentLanguage::url('mailto:info@example.com');
$phone = CurrentLanguage::url('tel:+375000000000');

Ссылки, начинающиеся с //, также не изменяются.

Маршрут без языка

При включённой мультиязычности методы маршрута исключают первый языковой сегмент.

Для URL:

text

/ru/developer/api/classes

результат будет следующим:

php

$path = CurrentLanguage::routePath();
$segments = CurrentLanguage::routeSegments();
$section = CurrentLanguage::routeSegment(0);

text

routePath()    -> developer/api/classes
routeSegment(0) -> developer

Методы маршрута

Метод	Возвращает	Описание
`routePath()`	`string`	Маршрут без языкового префикса.
`routeSegments()`	`array`	Все сегменты маршрута.
`routeSegment($index)`	`?string`	Сегмент по индексу или `null`.

Если мультиязычность отключена, методы возвращают путь текущего запроса без дополнительного удаления первого сегмента.

Ограничения и замечания

url() предназначен для внутренних ссылок сайта
сегменты . и .. считаются недопустимыми
неизвестный языковой префикс не удаляется как активный язык
при неразрешённом языке url() использует префикс языка по умолчанию
urlFor() принимает код активного языка, а не URL-префикс
для неизвестного или неактивного языка urlFor() возвращает null