Использование ICU Message Format в PHP

Данный функционал является частью стандартного модуля php-intl, то есть доступен "из коробки" и реализуется с помощью класса MessageFormatter. По сути, это такой printf() на стероидах, с добавлением оператора ветвления и некоторых других возможностей.

Установка модуля intl не должна вызывать сложностей, это стандартное sudo apt install php-intl, либо раскомментировать extension=intl в php.ini под Windows.

Основы

В самом базовом варианте форматтер используется для простой замены плейсхолдеров:

echo msgfmt_format_message("ru", "Привет, {0}!", ['Вася']);
echo msgfmt_format_message("ru", "Привет, {name}!", ['name' => 'Вася']);

Как видно, поддерживаются как нумерованные, так и именованные плейсхолдеры.

Но, разумеется, ради таких простых замен не стоило и затеваться, в этом случае проще использовать обычный sprintf(). ICU message formatter используется из-за развитых возможностей форматирования, и — в частности — с учётом локали:

echo msgfmt_format_message(
    "ru", 
    "Сегодня {0, date, long} или, коротко, {0, date, short}", 
    [new DateTime()]
);
// выведет:
// Сегодня 7 июня 2023 г. или, коротко, 07.06.23

На этом примере видно, что плейсхолдер может содержать от одного до трех аргументов, и в общем виде вызывается, как

{argNameOrNumber, argType, argStyle} 

где argNameOrNumber — это имя или номер плейсхолдера, argType — его тип, и argStyle — дополнительные настройки.

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

Перед началом работы зададим режим выброса исключений, чтобы сразу видеть ошибки, которые неизбежно будут возникать при экспериментах с форматами:

ini_set('intl.use_exceptions', true);

Для получения готовых сообщений можно либо сначала создать формат и затем применить его, либо сделать все в одном вызове. Также можно использовать как объектный, так и процедурный интерфейсы. Я буду использовать в статье функцию msgfmt_format_message(), чтобы код примеров был короче и не вызывал горизонтальный скроллинг.

Типы

К сожалению, внятной документации по этой библиотеке я не нашел. Приходится собирать по крохам и экспериментировать методом тыка, выясняя, как примеры из официальной документации применить к РНР.

К примеру, список из 10 основных типов я взял в статье по Yii::t(), ссылка на которую дана выше. Первые 4 из них требуют обязательного наличия всех трех параметров, а остальные позволяют обойтись двумя.

plural
select
selectordinal
choice (объявлен устаревшим)
number
date
time
spellout
ordinal
duration

Дополнительные настройки

Дополнительные настройки, насколько я понял, делятся на два типа: обычные и начинающиеся с двойного двоеточия, которые называются скелетонами. Обычных настроек всегда немного, например для date и time поддерживаются четыре: short, medium, long, full, а для number — три: integer, currency, percent. Но вот скелетонов может быть сколько угодно, причем они могут быть составными, как в последнем примере (group-off отключает разбивку по тысячам):

echo msgfmt_format_message('ru', '{0, number, percent}', [.50]),"\n";
// 50 %
echo msgfmt_format_message('ru', '{0, number, ::currency/RUR}', [9999.99]),"\n";
// 9 999,99 р.
echo msgfmt_format_message('ru', '{0, number, ::unit/kilogram group-off}', [1000]);
// 1000 кг.

К слову, отдельные числа можно форматировать и с помощью другого класса этого же модуля, NumberFormatter:

echo (new NumberFormatter('@numbers=roman', NumberFormatter::DECIMAL))
    ->format(date('Y'));
// MMXXIII

Интересным типом, относящимся к форматированию чисел, является spellout, который выводит число прописью:

echo msgfmt_format_message('ru', '{0, spellout}', [100500]);
// сто тысяч пятьсот

Ветвление

Но самой, пожалуй, интересной возможностью форматтера является встроенный оператор ветвления (аналогичный конструкции switch), который представлен в нескольких вариантах:

• plural , для образования множественного числа

• select, обычно используется для склонения по родам

• selectordinal для перечислений (поддержка русского языка ограничена)

В шаблонах игнорируются пробельные символы, и благодаря этому их можно форматировать для удобства восприятия сложных конструкций:

$message = 'Всего {files, plural, 
    one{загружен}
    other{загружено}
} {files, number, ::group-off} {files, plural, 
    one{файл}
    few{файла}
    many{файлов}
    other{файла}
}'; 
echo msgfmt_format_message('ru', $message, ['files' => 9991]),"\n";
// Всего загружен 9991 файл

$message = '{host} {host_gender, select, 
        female{будет счастлива} 
        male{будет счастлив}
        neuter{будет счастливо}
        other{будут счастливы}
    } видеть вас на {event},
{event_gender, select, 
        female {которая состоится}
        male{который состоится}
        neuter{которое состоится}
        other{которые состоятся}
    } {date, date} в {date, time, short} {place}
по адресу {address}.';
$data = [
    'host' => 'Мария Ивановна Заподдубная',
    'host_gender' => 'female',
    'event_gender' => 'neuter',
    'event' => 'праздновании дня рождения',
    'date' => new DateTime('2023-05-01 18:00'),
    'place' => 'в кафе "Голубка"',
    'address' => 'улица Садовая, дом 2',
];
echo msgfmt_format_message('ru', $message, $data),"\n";

выведет

Мария Ивановна Заподдубная будет счастлива видеть вас на праздновании дня рождения,
которое состоится 1 мая 2023 г. в 18:00 в кафе "Голубка"
по адресу улица Садовая, дом 2.

$data = [
    'host' => 'Полковник Васин',
    'host_gender' => 'male',
    'event_gender' => 'other',
    'event' => 'посиделках',
    'date' => new DateTime('2023-05-01 18:00'),
    'place' => 'у него дома',
    'address' => 'Коммунистический тупик, дом 2',
];

Полковник Васин будет счастлив видеть вас на посиделках,
которые состоятся 1 мая 2023 г. в 18:00 у него дома
по адресу Коммунистический тупик, дом 2.

Также поддерживаются вложенные конструкции, например в каждую ветку select можно добавить свой plural, но если честно, то я не смог придумать жизненный пример, и поэтому просто скопирую из документации:

{gender_of_host, select,
  female {
    {num_guests, plural, offset:1
      =0 {{host} does not give a party.}
      =1 {{host} invites {guest} to her party.}
      =2 {{host} invites {guest} and one other person to her party.}
      other {{host} invites {guest} and # other people to her party.}}}
  male {
    {num_guests, plural, offset:1
      =0 {{host} does not give a party.}
      =1 {{host} invites {guest} to his party.}
      =2 {{host} invites {guest} and one other person to his party.}
      other {{host} invites {guest} and # other people to his party.}}}
  other {
    {num_guests, plural, offset:1
      =0 {{host} does not give a party.}
      =1 {{host} invites {guest} to their party.}
      =2 {{host} invites {guest} and one other person to their party.}
      other {{host} invites {guest} and # other people to their party.}}}}

Экранирование

Сделано довольно занятно, одинарными кавычками. Любой текст, заключенный в них, интерпретируется, как есть. Чтобы экранировать саму кавычку, её надо удвоить:

echo msgfmt_format_message("ru", "Как есть '{0, date}' O''Neal '{time} {1}'", []);

Заключение

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

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