humanize

Humanize

Humanize for Dart & Flutter 👋

Humanize is a compact toolkit that makes UI strings feel natural. It bridges raw data and human-friendly phrasing with helpers for dates, numbers, lists, and text in English and French.

Table of Contents

• Overview
• Feature Highlights
• Getting Started
  • Installation
  • Quick Start
• Usage Guide
  • Dates & Times
  • Numbers
  • Lists, Text & Filesize
  • Calendar Math
  • i18n Facade
• Examples & Tests
• Notes & Limitations
• Resources
• Keywords
• Maintainers
• Support

Overview

Humanize focuses on pragmatic, readable output for UI strings. It packages natural phrases (e.g., “3 minutes ago”, “tomorrow”) and formatting helpers under a consistent API with light-touch locale support.

Feature Highlights

• Relative time and calendar-friendly deltas via naturaltime, naturaldelta, naturalday
• Flexible formatting for DateTime (ISO, RFC 2822, HTTP, timestamps, locale-aware)
• Humanized lists and text helpers: naturalJoin, oxfordComma, capfirst, titlecase, truncate*
• Number utilities with locale presets: intcomma, intword, ordinal, apNumber
• File size display with filesizeformat
• Calendar math helpers: addCalendarMonths, addCalendarYears
• Lightweight i18n facade through HumanizeI18n

Getting Started

Installation

dependencies:
  humanize: latest_version

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

Usage Guide

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 & Limitations

• 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).

Resources

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

Keywords

• Dart string formatting
• Flutter localization helpers
• humanize dates and numbers
• Dart natural language utilities
• human-readable UI text toolkit

Maintainers

• Jean-Luc Kabulu — @jeanluc243

Support

If Humanize makes your UI sparkle, feel free to fuel the magic with a donation—anything from a cheeky 🍺 to the legendary MacBook Pro upgrade 💻😂. Tap the link, pick your vibe, and let's keep shipping joy: Buy Me a Coffee.