Если цифрами документ показывает 1 251,04 ₽, а словами — «одна тысяча двести пятьдесят рублей», не исправляйте окончание вручную в шаблоне. Сначала сохраните исходное decimal-значение, код валюты, локаль, правило округления и уже разобранные major/minor части. Это быстро отделяет арифметическую ошибку от грамматической.

Строка прописью и форматированное число должны строиться из одного неизменяемого snapshot. Если таблица считает сумму заново после скидки, а текстовый блок использует старый total, обе функции могут быть корректны по отдельности и всё равно дать противоречивый документ.

Деньги разбираются как decimal, а не float

ТестОжидаемое разбиениеЧто ловит
0.00 RUB0 major, 00 minorпустую или пропущенную сумму
1.01 RUB1 major, 01 minorведущий ноль дробной части
2.05 RUB2 major, 05 minorокончание и формат копеек
11.11 RUB11 major, 11 minorисключение для 11
21.20 RUB21 major, 20 minorокончание после составного числа
-15.40 RUBsign, 15 major, 40 minorполитику отрицательных документов

Двоичный float способен представить простую десятичную сумму приближённо. Для денег используйте decimal тип либо целое количество минимальных единиц и выполняйте округление по явной политике. Не определяйте число знаков по длине введённой строки: scale берётся из выбранного каталога валют или конфигурации документа.

Целая и дробная части форматируются раздельно

Сначала нормализуйте сумму, затем получите major и minor без повторного округления. Словами преобразуется major; minor часто остаётся двумя цифрами, но конкретное оформление — правило вашего документа. Не зашивайте «копеек» в общий formatter: для другой валюты единица, грамматический род и scale могут отличаться.

amount_decimal = 1251.04
currency = RUB
locale = ru-RU
scale = currency_metadata.minor_scale
major = 1251
minor = 4
minor_display = 04
snapshot_id = invoice_total/v8

Formatter возвращает структурированный результат: sign, major words, major unit form, minor display и minor unit form. Шаблон только размещает эти поля. Так одна и та же функция обслуживает PDF, HTML и печатную форму, а различия в оформлении не меняют арифметику.

Склонение зависит от locale и числа

Unicode CLDR описывает plural categories и правила отображения currency names; набор форм зависит от языка. ICU предоставляет RuleBasedNumberFormat для spellout, но это не отменяет проверку бизнес-терминов и юридического стиля. В русском особенно важны последние две цифры: 11 не следует правилу для 1, а 21 следует.

  • Локаль задаётся явно и не наследуется случайно от ОС сервера.
  • Код валюты хранится отдельно от символа и переведённого названия.
  • Грамматический род числительного проверяется вместе с названием единицы.
  • Знак минус оформляется по политике документа, а не теряется.
  • Очень большие значения либо поддерживаются тестами, либо отклоняются с понятной ошибкой.

Библиотечный spellout может давать языково корректные слова, но не обязательно утверждённую формулировку конкретной организации. Для документов с правовыми последствиями согласуйте написание, регистр, союз между частями и представление minor units с ответственным специалистом.

Шаблон получает цифры и слова из одного snapshot

Рассчитайте subtotal, скидку, налог, округление и итог один раз. После фиксации snapshot передайте его числовому formatter и модулю spellout. В PDF сохраните технический version ID вне видимой суммы, чтобы можно было доказать, какой алгоритм сформировал документ.

Не вызывайте formatter заново в каждом шаблонном блоке и не передавайте локализованную строку обратно в арифметику. Строка «1 251,04» предназначена для показа, а не для парсинга. Источником истины остаётся typed decimal и currency code.

Граничная матрица ловит ошибки до печати

  1. Проверить ноль, единицу, 2–4, 5–20, 21–24 и 100+ для каждой локали.
  2. Добавить значения с 01, 05, 10 и максимальной minor частью.
  3. Проверить отрицательные корректировки и политику нулевого документа.
  4. Сравнить HTML, PDF и повторную печать одного snapshot.
  5. Зафиксировать golden cases, утверждённые владельцем документа.

Исправление принято, когда цифры и слова совпадают на одной версии данных, а тесты защищают валюту, локаль и границы. Для разбора приложите decimal до округления, currency code, locale, formatter version и обезличенный фрагмент результата. Полный договор и реквизиты контрагента обычно не нужны.

Проверенные источники