Humanize (Dart)

Tiny, fast helpers to turn numbers, dates, lists, and text into human-friendly strings — inspired by Django Humanize and Luxon — with simple locale support (en/fr) and a compact API.

Overview
Features
Installation
Quick Start
Dates & Times
Numbers
Lists, Text, Filesize
Calendar Math
i18n Facade
Examples, Tests
Notes
License & Links

Overview

Humanize focuses on pragmatic, readable output for UI strings. It includes “natural” phrases (e.g., “3 minutes ago”, “tomorrow”) and formatting helpers, plus a neat i18n facade.

Features

Relative time: naturaltime, naturaldelta
Natural day: naturalday
DateTime formats: ISO, RFC 2822, HTTP, timestamps
Locale formats: toLocaleString(...) (presets + Intl-like options)
Lists: naturalJoin, oxfordComma
Numbers: intcomma, intword (en/fr), ordinal, apNumber
Filesize: filesizeformat
Text: capfirst, titlecase, truncate*
Calendar math: addCalendarMonths, addCalendarYears
i18n facade: HumanizeI18n

Installation

dependencies:
  humanize: ^1.2.0

import 'package:humanize/humanize.dart';

Quick Start

print(naturaltime(DateTime.now().subtract(Duration(minutes: 3)), locale: 'en')); // 3 minutes ago
print(naturaldelta(Duration(hours: 2), locale: 'fr'));                            // 2 heures

final ref = DateTime(2007, 2, 17, 12);
print(naturalday(DateTime(2007, 2, 16), now: ref, locale: 'en', format: 'dd MMMM yyyy')); // yesterday

print(naturalJoin(['a','b','c'], locale: 'fr')); // a, b et c
print(oxfordComma(['a','b','c'], locale: 'en')); // a, b, and c

print(intcomma(4500.2));            // 4,500.2
print(intcomma(1234567, sep: ' ')); // 1 234 567
print(intword(1200000, locale: 'fr')); // 1,2 millions
print(filesizeformat(1536));        // 1.5 KB

Dates & Times

final now = DateTime(2007, 2, 17, 16, 30, 0);
print(naturaltime(now.add(Duration(days: 9)), now: now)); // in 1 week, 2 days
print(naturaltime(now.subtract(Duration(days: 1, hours: 2)), now: now, locale: 'fr')); // il y a un jour, 2 heures

final dt = DateTime(2017,4,20,11,32);
print(dt.toISO());      // 2017-04-20T11:32:00.000-04:00
print(dt.toRFC2822());  // Thu, 20 Apr 2017 11:32:00 -0400
print(dt.toHTTP());     // Thu, 20 Apr 2017 15:32:00 GMT
print(dt.asLocale('fr').toHTTP()); // jeu., 20 avr. 2017 15:32:00 GMT (display)

// Locale formats
print(dt.toLocaleString());                                 // e.g., 4/20/2017
print(dt.toLocaleString(HumanDateFormat.DATETIME_FULL));    // April 20, 2017...
print(dt.asLocale('fr').toLocaleString(HumanDateFormat.DATETIME_FULL)); // 20 avril 2017...

Numbers

print(intcomma(4500));    // 4,500
print(intword(1500000, short: true)); // 1.5 M
print(ordinal(1, locale: 'fr')); // 1er
print(apNumber(5, locale: 'fr')); // cinq

Lists, Text, Filesize

print(naturalJoin(['a','b','c'], locale: 'fr')); // a, b et c
print(oxfordComma(['a','b','c']));               // a, b, and c
print(capfirst('hello'));                        // Hello
print(filesizeformat(1536));                     // 1.5 KB

Calendar Math

final d = DateTime(2017, 2, 13);
print(d.addCalendarMonths(1).toISODate());    // 2017-03-13
print(d.add(Duration(days: 30)).toISODate()); // 2017-03-15

i18n Facade

final hFr = HumanizeI18n('fr');
print(hFr.naturalTime(DateTime.now().subtract(Duration(minutes: 3))));
print(hFr.intComma(1234567)); // 1 234 567

Examples, Tests

Examples in example/: basic_usage.dart, i18n_facade.dart, intcomma_examples.dart, naturaltime_examples.dart, naturalday_examples.dart, ordinal_examples.dart, formatting_examples.dart, math_examples.dart

Run tests:

dart test

Notes

Built-in locales: en, fr. PRs welcome to extend.
For strict formatting (currencies, complex calendars), combine with package:intl and use Humanize for human-friendly phrasing.
Localized RFC/HTTP outputs are intended for display only (not protocol-compliant).

License & Links

License: see LICENSE
Repo: https://github.com/jeanluc243/humanize
Issues: https://github.com/jeanluc243/humanize/issues