ALBIREO CMS
version: 2025.11.01
© Albireo CMS, 2020-2025

Функции перевода Albireo CMS

detectUserLang lang langFile

Функция detectUserLang

Определяет наиболее подходящий язык для пользователя, основываясь на его настройках браузера (заголовок HTTP_ACCEPT_LANGUAGE) и списке языков, разрешенных на сайте. Функция сравнивает предпочтения пользователя с доступными вариантами и возвращает первое найденное совпадение или язык по умолчанию.

Сигнатура

function detectUserLang(string $langs = ''): string

Аргументы

string $langs (необязательный)
Строка, содержащая список разрешенных языков, разделенных запятыми. Если этот параметр не передан, список будет получен из конфигурации системы (getConfig('langAllowed', ...)).

Результат

Возвращает строку (string) с двухбуквенным кодом языка (например, 'ru', 'en'). Логика выбора следующая:

  1. Находится первое совпадение между списком языков из браузера пользователя (с учетом приоритета) и списком разрешенных языков.
  2. Если совпадений не найдено, возвращается язык по умолчанию, также определенный в конфигурации.

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

Пример 1: Стандартное использование

В большинстве случаев функция вызывается без параметров, полагаясь на глобальную конфигурацию сайта.

// Предположим, в конфигурации разрешены 'ru', 'en', 'uk', а язык по умолчанию 'en'.
// Браузер пользователя отправил заголовок: 'uk-UA,uk;q=0.9,ru;q=0.8,en-US;q=0.7'

$userLanguage = detectUserLang(); 

// Функция найдет 'uk' как первое совпадение и вернет 'uk'.
echo "Ваш язык: " . $userLanguage;

Пример 2: Использование с ограниченным набором языков

Это может быть полезно для отдельного компонента или страницы, которая поддерживает не все языки сайта.

// Браузер пользователя отправил заголовок: 'de,en-US;q=0.9'
// Мы хотим выбрать только из английского или русского.

$lang = detectUserLang('en, ru');

// Функция проигнорирует 'de' и выберет 'en' как первое совпадение.
// $lang будет 'en'.
echo "Язык компонента: " . $lang;

Пример 3: Демонстрация работы с языком по умолчанию

// В конфигурации разрешены 'en', 'es', а язык по умолчанию 'en'.
// Браузер пользователя отправил заголовок: 'fr-FR,fr;q=0.9'

$lang = detectUserLang();

// Так как ни 'fr' не входит в список разрешенных, функция вернет язык по умолчанию.
// $lang будет 'en'.
echo "Язык сайта: " . $lang;

Примечания

  • Кеширование: Результат выполнения кешируется в статической переменной. Это значит, что при повторных вызовах в рамках одного HTTP-запроса, сложная логика определения языка выполняться не будет, что повышает производительность.
  • Упрощение языка: Функция упрощает коды языков, полученные из браузера, до двух символов (например, en-US или fr-CH будут обработаны как en и fr соответственно).

Функция lang

Функция lang является центральным элементом системы интернационализации (i18n). Она переводит переданный текст на язык, предпочитаемый пользователем, используя предварительно загруженные языковые словари. Функция также поддерживает форматирование строк с помощью плейсхолдеров, аналогично vsprintf().

Сигнатура

function lang(string $text = '', array $values = []): string

Аргументы

string $text
Строка для перевода. Эта же строка используется как ключ для поиска в языковых файлах. Может содержать плейсхолдеры для форматирования, например %s (строка), %d (число).
array $values (необязательный)
Массив значений, которые будут подставлены в плейсхолдеры в переведенной строке. Порядок элементов в массиве должен соответствовать порядку плейсхолдеров.

Результат

Возвращает переведенную и отформатированную строку (string). Если перевод для данной строки не найден в словарях, будет возвращена исходная строка $text.

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

Пример 1: Простой перевод статического текста

// В языковом файле (например, en.php):
// return ['Привет, мир!' => 'Hello, world!'];

echo lang('Привет, мир!'); // Выведет "Hello, world!" для англоязычного пользователя

Пример 2: Сложное форматирование с несколькими значениями

// В en.php:
// return ['Найдено %d из %d записей.' => 'Found %d of %d records.'];

$found = 15;
$total = 100;
echo lang('Найдено %d из %d записей.', [$found, $total]);
// Для англоязычного пользователя выведет: Found 15 of 100 records.

Примечания

  • Кеширование: Языковые файлы и определенный язык пользователя загружаются только один раз за запрос благодаря использованию статических переменных, что повышает производительность.
  • Загрузка файлов: Языковые словари загружаются из двух мест: SYS_DIR/langs/ (системные переводы) и CONFIG_DIR/langs/ (пользовательские переводы). Пользовательские переводы имеют приоритет и могут переопределять системные.
  • Обнаружение языка: Язык пользователя определяется автоматически с помощью функции detectUserLang(), но может быть переопределен для конкретной страницы через getPageData('lang').
  • Отладка: Если перевод для строки не найден (и язык пользователя не 'en'), эта строка будет отправлена в отладочную панель (debugPanel). Это помогает разработчикам легко находить непереведенные тексты.

Функция langFile

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

Сигнатура

function langFile(string $postfix = '@lang-'): string|false

Аргументы

string $postfix (необязательный)
Строковый префикс, который добавляется между именем основного файла и кодом языка. По умолчанию используется '@lang-', что формирует имена вида page@lang-uk.php.

Результат

Возвращает:

  • string — полный путь к языковой версии файла, если он существует.
  • false — если языковая версия файла не найдена.

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

Сценарий: создание многоязычной страницы "О нас"

Предположим, у нас есть следующая структура файлов:

/pages/
  |- about.php         (файл с контентом по-умолчанию, например, на русском)
  |- about@lang-en.php   (файл с контентом на английском)
  `- about@lang-uk.php   (файл с контентом на украинском)

В основной файл about.php необходимо добавить следующий код в самое начало:

<?php
// В самом начале файла pages/about.php

// Пытаемся найти языковую версию этого файла
if ($langVersionFile = langFile()) {
    // Если файл найден, подключаем его
    require $langVersionFile;

    // И прекращаем выполнение основного файла, чтобы не вывести контент по умолчанию
    return;
}
?>

<!-- Здесь идет HTML-код по умолчанию (на русском языке) -->
<h1>О нас</h1>
<p>Это текст страницы по умолчанию.</p>

Как это работает:

  • Когда страницу посещает пользователь с языком 'en', функция langFile() найдет файл about@lang-en.php, подключит его, и выполнение основного файла about.php прекратится.
  • Когда страницу посещает пользователь с языком 'de' (для которого нет файла), langFile() вернет false, условие не выполнится, и пользователь увидит контент по умолчанию из файла about.php.

Примечания

  • Назначение: Эта функция предназначена для подмены целых файлов с контентом, а не для перевода отдельных строк. Для перевода отдельных фраз следует использовать функцию lang().
  • Структура файлов: Для корректной работы необходимо строго соблюдать соглашение об именовании языковых версий файлов: [имя_основного_файла][постфикс][код_языка].[расширение].