# Pluralization 1.0.2+

# Введение

Языки различаются правилами преобразования слов во множественное число («час», «часа», «часов» и так далее). Одни языки, вроде английского, имеют две формы, другие — только одну форму, а в некоторых есть множествео форм. Данный компонент использует правила плюрализации Unicode CLDR для определения корректной формы слова в указанном числе. CLDR использует короткие мнемонические теги для этих форм:

  • zero
  • one (единственное число)
  • two (двойственное число)
  • few (паукальное число)
  • many (также используется для дробей, если они имеют отдельный класс)
  • other (основная форма множественного числа; также используется, если у языка имеется только одна форма или если требуемая форма не указана. Указание этой формы обязательно)

См. Language Plural Rules для форм каждого языка в CLDR.

Эти формы используются для предоставления локализованных единиц с более естественными способами выражения фраз, которые варьируются во множественном числе, например: «1 час», «2 часа» и «5 часов». Хотя они не могут выразить все сложности ествественных языков, они допускают более ествественную формулировку, чем конструкции вроде «1 час(-а/-ов)».

Плюрализация осуществляется с помощью библиотеки OblikStudio/php-pluralization.

# TC\ComponentLibrary\Util\Pluralization

# pluralPhraseName

Получение название фразы в нужной форме плюрализации.

public static function pluralPhraseName($number, $phrases, \XF\Language $language = null): string

# Параметры

Параметр Тип Значение по умолчанию Описание
number int|float Число для плюрализации.
phrases string[]|string Названия фраз для разных форм плюрализации.
Если указана строка, она будет являться названием фразы в форме other, а названия для других форм будут образованы посредством добавления суффиксов _zero, _one, _two, _few и _many.
Форма other является обязательной.
language XF\Language XF::language() Объект языка, для которого осуществляется плюрализация.

# Примеры

# Получение названия фразы из списка
/**
 * В случае, если текущий язык — английский, а count($items) == 1, будет возвращено «there_is_one_item», в
 * противном случае — «there_are_x_items». Остальные формы не используются английским языком, но могут быть
 * использованы другими языками.
 */
$phraseName = \TC\ComponentLibrary\Util\Pluralization::pluralPhraseName(
    count($items),
    [
        'zero'  => 'there_are_zero_items',
        'one'   => 'there_is_one_item',
        'two'   => 'there_are_two_items',
        'few'   => 'there_are_few_items',
        'many'  => 'there_are_many_items',
        'other' => 'there_are_x_items'
    ]
);
# Получение названия фразы без указания списка фраз
/**
 * В отличе от предыдущего примера, здесь указывается не список названий фраз, а название одной фразы для формы «other». Остальные
 * фразы будут получены путем добавления к ним суффикса с названием формы: «there_are_x_items_zero»,
 * «there_are_x_items_one», «there_are_x_items_two», «there_are_x_items_few», «there_are_x_items_many».
 */
$phraseName = \TC\ComponentLibrary\Util\Pluralization::pluralPhraseName(count($items), 'there_are_x_items');

# phrasePlural

Получение фразы в нужной форме плюрализации.

public static function phrasePlural($number, $phrases, array $params = [], bool $allowHtml = true, \XF\Language $language = null): \XF\Phrase

# Параметры

Параметр Тип Значение по умолчанию Описание
number int|float Число для плюрализации.
phrases string[]|string Названия фраз для разных форм плюрализации.
Если указана строка, она будет являться названием фразы в форме other, а названия для других форм будут образованы посредством добавления суффиксов _zero, _one, _two, _few и _many.
Форма other является обязательной.
params array [] Массив параметров фразы.
allowHtml bool true Включение/отключение экранирования HTML во фразе.
language XF\Language XF::language() Объект языка, для которого осуществляется плюрализация.
# Примеры
$phrase = \TC\ComponentLibrary\Util\Pluralization::pluralPhraseName(
    count($items),
    'there_are_x_items',
    ['count' => count($items)]
);

# getCardinal

Получение названия формы плюрализации для нужного языка.

public static function getCardinal($number, \XF\Language $language = null, array $availableCardinals = []): string

# Параметры

Параметр Тип Значение по умолчанию Описание
number int|float Число для плюрализации.
language XF\Language XF::language() Объект языка, для которого осуществляется плюрализация.
availableCardinals string[] [] Список доступных форм плюрализации. В случае, если нужная форма плюрализации недоступна, будет возвращено other.

# getLanguageCode

Получение кода языка для библиотеки OblikStudio/php-pluralization.

public static function getLanguageCode(\XF\Language $language): string

# Параметры

Параметр Тип Описание
language XF\Language Объект языка, для которого нужно получить код.

# getPluralization

Получение класса плюрализации из библиотеки OblikStudio/php-pluralization для нужного языка.

public static function getLanguageCode(\XF\Language $language): string

# Параметры

Параметр Тип Описание
language XF\Language Объект языка, для которого нужно получить класс плюрализация.

# Плюрализация в шаблонах

# tc_phrase_plural

# Параметры

Параметр Тип Значение по умолчанию Описание
number int|float Число для плюрализации.
phrases string[]|string Названия фраз для разных форм плюрализации.
Если указана строка, она будет являться названием фразы в форме other, а названия для других форм будут образованы посредством добавления суффиксов _zero, _one, _two, _few и _many.
Форма other является обязательной.
params array [] Массив параметров фразы.

# Примеры

# Получение фразы в нужной форме плюрализации из списка фраз
{{ tc_phrase_plural(
    count($items),
    {
        'zero': 'there_are_zero_items',
        'one': 'there_is_one_item',
        'two': 'there_are_two_items',
        'few': 'there_are_few_items',
        'many': 'there_are_many_items',
        'other': 'there_are_x_items'
    },
    {'count': count($items)}
) }}
# Получение фразы в нужной форме плюрализации без списка фраз
{{ tc_phrase_plural(count($items), 'there_are_x_items', {'count': count($items)}) }}

# Плюрализация во фразах

Кроме плюрализации через через PHP и функцию в шаблонах, существует возможность задавать правила плюрализации непосредственно во фразах. Для этого во фразе необходимо создать подобную конструкцию:

{plural
  number="{number}"
  zero="…"
  one="…"
  two="…"
  few="…"
  many="…"
  other="…"
  123="…"
  precision="0"
}

# Параметры

Параметр Описание
number Число для плюрализации. Обязательный параметр.
precision Число знаков после запятой в отображаемом числе.
other Значение для формы other other. Также используется, если требуемая форма недоступна. Обязательный параметр.
Название любой формы Значение для указанной формы.
Любое число Значение для определенного числа.

# Примеры

Создадим фразу test_plural_phrase для русского языка:

На столе {plural
           number="{count}"
           1="одна книга"
           one="#n книга"
           few="#n книги"
           other="#n книг"
         }.

Далее отобразим фразу в шаблоне:

<p>{{ phrase_dynamic('test_plural_phrase', {'count': 1}) }}</p>
<p>{{ phrase_dynamic('test_plural_phrase', {'count': 2}) }}</p>
<p>{{ phrase_dynamic('test_plural_phrase', {'count': 5}) }}</p>
<p>{{ phrase_dynamic('test_plural_phrase', {'count': 10}) }}</p>
<p>{{ phrase_dynamic('test_plural_phrase', {'count': 11}) }}</p>
<p>{{ phrase_dynamic('test_plural_phrase', {'count': 101}) }}</p>

Результат:

На столе одна книга.

На столе 2 книги.

На столе 5 книг.

На столе 10 книг.

На столе 11 книг.

На столе 101 книга.