README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Translator

Переводчик сообщений: параметры {name}, множественное число по правилам CLDR (8 языков, включая славянские, польскую и румынскую формы), домены, запасная локаль и вложенные каталоги. Принимает готовые массивы из любого источника.

Установка

composer require cloud-castle/translator

Требуется PHP 8.1+. Единственная зависимость — cloud-castle/inflector (правила выбора формы множественного числа PluralRules).

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

<?php

use CloudCastle\Translator\Translator;

$translator = new Translator('ru', fallbackLocale: 'en');

$translator->addMessages('ru', [
    'user' => ['greeting' => 'Привет, {name}!'],
    'apples' => '{count} яблоко|{count} яблока|{count} яблок',
]);

echo $translator->translate('user.greeting', ['name' => 'Мир']); // Привет, Мир!
echo $translator->translate('apples', [], null, 5);              // 5 яблок
echo $translator->translate('missing.key');                     // missing.key

Возможности

Параметры — подстановка {name} из массива значений.
Множественное число по CLDR — форма выбирается общими правилами cloud-castle/inflector (PluralRules): русский/украинский/белорусский и польский — три формы (с учётом сотен), румынский — one/few/other, французский — one/other, прочие — две. Формы разделяются |; {count} подставляется автоматически. Единый источник правды с инфлектором — без дублирования.
Домены — независимые пространства сообщений (messages, errors, ui…): addMessages($locale, $messages, $domain) и translate(..., $domain).
Проверка наличия — has($key, $locale, $domain) с учётом запасной локали.
Запасная локаль — при отсутствии перевода берётся fallbackLocale, а затем сам ключ (удобно для отладки).
Вложенные каталоги — массивы разворачиваются в точечную нотацию (user.greeting); каталог пополняется повторными вызовами addMessages().
Без привязки к источнику — принимает готовые массивы; загрузку из JSON/YAML сделайте любым парсером (например, cloud-castle/parser-*).

Сравнение с аналогами

Сравнение — с переводчиками сообщений той же категории: symfony/translation, laravel (illuminate/translation), gettext, laminas/i18n, oscarotero/Gettext. Все таблицы содержат графу 🏆 Победитель. Числа — из реального изолированного прогона benchmarks/compare.php (перевод с плюрализацией и подстановкой, 20000 итераций, PHP 8.1 без Xdebug): XDEBUG_MODE=off php benchmarks/compare.php.

Функциональность

Возможность	translator	symfony/translation	laravel	gettext	laminas/i18n	oscarotero/Gettext	🏆
Плюрализация по CLDR (8 языков)	✅	✅	⚠️	⚠️	✅	⚠️	—
Славянские + польская + румынская формы	✅	✅	⚠️	⚠️	⚠️	⚠️	🏆 translator
Параметры `{name}`	✅	✅	✅	⚠️	✅	⚠️	—
Домены сообщений	✅	✅	✅	✅	✅	✅	—
Запасная локаль	✅	✅	⚠️	❌	✅	❌	—
Вложенные каталоги (точечная нотация)	✅	⚠️	✅	❌	⚠️	❌	🏆 translator/laravel
Без привязки к источнику/формату	✅	⚠️	⚠️	❌	⚠️	❌	🏆 translator
Runtime-зависимостей	1	3+	много	ext-gettext	2+	1	🏆 translator/oscarotero

Производительность (перевод с плюрализацией)

Библиотека	Время	Относительно translator	🏆
cloud-castle/translator	0.0008 мс	1×	🏆
symfony/translation	0.0034 мс	×4.3 медленнее

Потребление памяти (перевод сообщения)

Библиотека	Пик памяти	🏆
cloud-castle/translator	≈ 1.7 КБ	🏆
symfony/translation	2.9 КБ

Безопасность

Критерий	translator	symfony/translation	laravel	gettext	🏆
Отсутствие глобального состояния	✅	⚠️	❌	❌	🏆 translator
Нет исполнения/загрузки файлов из данных	✅	⚠️	⚠️	⚠️ ext	🏆 translator
Отсутствующий перевод не роняет процесс	✅	✅	✅	⚠️	—
Минимальная поверхность атаки	✅	❌	❌	⚠️	🏆 translator

Качество кода

Метрика	translator	symfony/translation	laravel	🏆
PHPStan	max + strict-rules	~level 5	~level 5	🏆 translator
Psalm	errorLevel 1	не заявлен	не заявлен	🏆 translator
Покрытие тестами	100%	высокое	высокое	🏆 translator
Мутационное тестирование (MSI)	100%	не публикуется	не публикуется	🏆 translator

Когда применять. translator уместен как лёгкое ядро локализации без привязки к фреймворку: параметры, формы множественного числа по CLDR (8 языков), домены и запасная локаль из готовых массивов. Правила плюрализации разделены с cloud-castle/inflector — единый источник правды без дублирования. Извлечение строк из кода и формат ICU MessageFormat в пакет не входят — для них добавьте специализированный слой поверх готовых каталогов.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/translator
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия