SiteLang

WS >= 0.95 WS 0.996: обновлён WS 0.997: обновлён

SiteLang является статическим классом для получения локализованных строк активной темы. Он автоматически доступен в обычных шаблонах сайта.

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

общие переводы для всей темы
отдельные переводы страниц и записей
вложенные ключи через точку
резервные значения
наследование переводов языка по умолчанию
безопасный вывод текста в HTML
подключение дополнительных файлов переводов

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

php

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

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

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

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

text

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

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

php

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

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

php

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

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

Контекст	Файл
Все страницы сайта	`lang/{prefix}/common.php`
Главная страница	`lang/{prefix}/index.php`
Страница ошибки	`lang/{prefix}/404.php`
Шаблон страницы	`lang/{prefix}/page/{template}.php`
Шаблон записи	`lang/{prefix}/post/{template}.php`

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

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

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

load(string ...$segments): void

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

php

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

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

php

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

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

php

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

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

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

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

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

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

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

php

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

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

php

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

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

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

php

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

Вывод в HTML

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

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

php

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

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

php

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

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

Все переводы

all(): array

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

php

$translations = SiteLang::all();

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

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

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