Aughtone Format

Aughtone Format is a suite of Kotlin Multiplatform libraries designed to provide consistent, localized formatting for Dates, Times, Numbers, and other human-readable metrics across all platforms.

Aughtone Format 3.1.0 focuses on relative-time expressiveness and completing localization coverage:

• Direction-Aware LocalTime Relative Time: New RelativeDirection { Past, Present, Future, Nearest } enum and a direction parameter on LocalTime.formatReadableRelative resolve the ambiguity of a date-less clock time across midnight (modelled on ICU's Direction). The default is now Nearest (shortest distance on a 24-hour clock) — a behaviour change from the previous linear same-day math; pass RelativeDirection.Present for the old behaviour.
• Calendar-Anchored LocalTime: A new LocalTime.formatReadableRelative(now: Instant, timeZone, …) overload resolves the time to a concrete occurrence relative to a dated anchor, so it can render day labels like "Yesterday"/"Today"/"Tomorrow".
• "Shortly" Near-Future Label: LocalDate relative formatting gains a "Shortly" label — the future mirror of "Recently" — for near-future dates within the nowThreshold window.
• Completed Localizations: Relative time now works for Danish, Norwegian (Bokmål/Nynorsk), Swedish, and Icelandic (previously fell back to English); Inuktitut gains full time-zone names (143 zones); Traditional Chinese gains its own compass points and era names; and 11 locales gained proper AM/PM markers.
• English-Fallback Fixes: Indonesian/Malay/Swahili relative time, duration formatting for 10 locales (az, eu, hy, ka, kk, lt, lv, sq, uz, iu), and Persian money symbol placement were silently falling back to English or formatting incorrectly — all now fixed, with a coverage-guard test preventing this class of regression.

• :datetime: Advanced formatting for kotlinx-datetime types with multi-locale support.
• :readable: Human-friendly formatting for metrics (abbreviations), ordinals, and data sizes.
• :viewable: Platform-agnostic vector graphics representation, styling, and path conversion (GeoJSON, SVG, WKT).
• :viewable-compose: Jetpack / Compose Multiplatform integration for rendering viewable vector graphics (Painters, ImageVectors).
• :toolbox: Shared utilities and common formatting primitives.

This project follows a specialized 5-sector documentation hierarchy.

• 📐 Architecture: Engineering rules and design patterns.
• 🧠 Functional Specifications: Business logic and domain constraints.
• 🎨 Design & UI: Presentation layer and user stories.
• 📋 Acceptance Criteria: Success outcomes and verification.
• 📖 Developer Guide: Environment setup and onboarding.
• 📜 Changelog: History of changes and release notes.

• 55+ Languages and Regions Supported: Deep grammatical parity for Slavic, Arabic, Hebrew, Inuktitut, and more.
• Relative Time Formatting: Convert instants, dates, and times into natural language (e.g., "5 minutes ago", "Yesterday", "Shortly"), with direction-aware LocalTime handling across midnight.
• Automatic Fallback: Smartly switches from relative to absolute formatting based on configurable thresholds.
• Ordinal Numbers: Localized ordinal suffix support (e.g., 1st, 2nd, 3.º, 第1).
• Duration Scaling: Human-friendly duration strings with perceptual rounding (e.g., "2 weeks" vs "14 days").
• Numeric Abbreviations: Scaling large numbers into abbreviated forms (e.g., 1.5K, 1.2M).
• Geospatial Formatting: Localized altitude, azimuth (with cardinal directions), and coordinates.

The library provides deep grammatical parity and full BCP 47 subtag fallback (e.g., en-ZA → en) for 59 supported language and region combinations:

val now = Clock.System.now()
// Format with styles (Short, Medium, Long, Full)
println(now.format(DateTimeStyle.Short, locale = Locale("en-US"))) // "4/23/26, 4:15 PM"
println(now.format(DateTimeStyle.Short, locale = Locale("en-CA"))) // "2026-04-23, 4:15 p.m."

// Ordinals
println(123L.formatReadableOrdinal(Locale("en-US"))) // "123rd"
println(123L.formatReadableOrdinal(Locale("fr-FR"))) // "123e"

// Durations
println(1.5.hours.formatReadable(Locale("en-US"))) // "1.5 hours"
println(1.5.hours.formatReadable(Locale("es-ES"))) // "1,5 horas"

// Relative Time
println(instant.formatReadableRelative(locale = Locale("en-US"))) // "3 minutes ago"
println(instant.formatReadableRelative(locale = Locale("de-DE"))) // "vor 3 Minuten"

// Relative Time — direction-aware LocalTime (disambiguates a clock time across midnight)
val alarm = LocalTime(1, 0)
println(alarm.formatReadableRelative(now = LocalTime(23, 0), direction = RelativeDirection.Future)) // "in 2 hours"

// Data Sizes
println(1048576L.formatReadableDataSize()) // "1.0 MiB"

Access the Governance Skills for specialized development rules.

This library includes embedded, machine-readable "skills" to help AI assistants understand its APIs and best practices.

• Discovery: Look for META-INF/ai-skills/*.ai-skill.md

If you are using an AI assistant (like Claude, Gemini, or ChatGPT) to write code with this library, paste this prompt first:

"Scan all project dependencies for AI Skill files in META-INF/ai-skills/ with the prefix io.github.aughtone. Use these to understand the API patterns, types, and governance for this library. If they are not found in the local classpath, refer to the Aughtone Format GitHub repository for the source definitions."

To learn how to add this capability to your own library, see our AI Skill Publishing Standard.