SiteLang

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

<h1><?php echo SiteLang::html('catalog.title', 'Каталог'); ?></h1>

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

Файлы переводов

Переводы хранятся в папке lang активной темы. Название языковой папки соответствует префиксу языка:

lang/
  ru/
    common.php
    index.php
    404.php
    page/
      catalog.php
    post/
      news.php
  en/
    common.php

Каждый файл должен возвращать массив:

<?php
return [
    'catalog' => [
        'title' => 'Каталог',
        'description' => 'Товары нашего магазина',
    ],
];

Получение вложенного значения:

$title = SiteLang::get('catalog.title');

Загружаемые файлы

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

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

Дополнительные файлы переводов

load(string ...$segments): void

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

SiteLang::load('components', 'product-card.php');

В этом примере загружается файл lang/{prefix}/components/product-card.php. Он должен возвращать массив переводов:

<?php
return [
    'product-card' => [
        'buy' => 'Купить',
    ],
];

После загрузки значения доступны через обычные методы класса:

$buttonText = SiteLang::html('product-card.buy');

Сначала загружается файл языка по умолчанию, затем текущего языка. Отсутствующие файлы пропускаются.

Значения дополняют уже загруженные переводы. Совпадающие ключи переопределяются, остальные сохраняются.

В пределах одного запроса один и тот же путь загружается только один раз. Метод ничего не возвращает.

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

get(string $path, string $default = ''): string

Возвращает перевод без дополнительной обработки:

$title = SiteLang::get('catalog.title');

Если ключ может отсутствовать, передайте резервное значение:

$title = SiteLang::get('catalog.title', 'Каталог');

Если перевод не найден или найденное значение является массивом, метод возвращает резервное значение.

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

$text = SiteLang::get('navigation.catalog.title');

Вывод в HTML

html(string $path, string $default = ''): string

Возвращает перевод с экранированными специальными HTML-символами:

<p><?php echo SiteLang::html('catalog.description'); ?></p>

Резервное значение также экранируется:

<p><?php echo SiteLang::html('catalog.description', 'Описание каталога'); ?></p>

Метод предназначен для вывода обычного текста. HTML-теги внутри перевода будут показаны как текст, а не обработаны браузером.

Все переводы

all(): array

Возвращает массив всех переводов, загруженных для текущей страницы:

$translations = SiteLang::all();

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

Переводы в JavaScript

useInJS(string ...$paths): void

Отмечает ключи или группы переводов, которые нужно передать в JavaScript. Сам метод не загружает файлы переводов.

Для переводов компонента из примера выше:

SiteLang::load('components', 'product-card.php');
SiteLang::useInJS('product-card.buy');

Вызывайте useInJS() до вывода JavaScript через CurrentTheme::getJS(). При штатном выводе скриптов выбранные переводы передаются автоматически, а объект window.wsSiteLang становится доступен скриптам темы. Отдельное подключение скрипта для него не требуется.

В JavaScript-модуле темы получите строку:

const buyText = window.wsSiteLang.get('product-card.buy', 'Купить');

Второй аргумент является резервным значением. Он используется, если ключ не передан в JavaScript, отсутствует или указывает на группу, а не отдельное значение. По умолчанию возвращается пустая строка.

Можно передать несколько путей отдельными аргументами: SiteLang::useInJS('catalog.title', 'product-card.buy'). Чтобы передать целую группу, укажите её путь, например SiteLang::useInJS('catalog').

В JavaScript передаются только отмеченные ключи и группы, а не весь словарь переводов.

window.wsSiteLang.get() возвращает текст без HTML-экранирования. Для вывода обычной строки в DOM используйте textContent.

Важные замечания

• файлы переводов должны возвращать массив
• вложенные ключи разделяются точкой
• get() возвращает только строковые и другие скалярные значения
• для безопасного вывода текста в HTML используйте html()
• контекстный файл шаблона дополняет и переопределяет общие переводы
• отсутствующие переводы берутся из языка по умолчанию